diff --git a/README.md b/README.md index 8e1a7a4ee13f921a955bb35e33ff7414819f3685..0b925bcfd4d5ebbd7fe503d3fc6960e30b7288e8 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,9 @@ This repository contains documentation for Fuchsia. # Individual Project Documentation -+ [Magenta][magenta] ++ [Zircon][zircon] - Magenta is the microkernel underlying the rest of Fuchsia. Magenta + Zircon is the microkernel underlying the rest of Fuchsia. Zircon also provides core drivers and Fuchsia's libc implementation. # Reference Material @@ -32,12 +32,12 @@ This repository contains documentation for Fuchsia. + [The Fuchsia Book](book.md) -[magenta]: https://fuchsia.googlesource.com/magenta/+/master/README.md "Magenta" +[zircon]: https://fuchsia.googlesource.com/zircon/+/master/README.md "Zircon" [getting_started]: getting_started.md "Getting started" [build_system]: build_system.md "Build system" -[acer_12]: https://fuchsia.googlesource.com/magenta/+/master/docs/targets/acer12.md "Acer 12" -[intel_nuc]: https://fuchsia.googlesource.com/magenta/+/master/docs/targets/nuc.md "Intel NUC" -[rpi3]: https://fuchsia.googlesource.com/magenta/+/master/docs/targets/rpi3.md "Rasperry Pi 3" +[acer_12]: https://fuchsia.googlesource.com/zircon/+/master/docs/targets/acer12.md "Acer 12" +[intel_nuc]: https://fuchsia.googlesource.com/zircon/+/master/docs/targets/nuc.md "Intel NUC" +[rpi3]: https://fuchsia.googlesource.com/zircon/+/master/docs/targets/rpi3.md "Rasperry Pi 3" [flutter_module]: https://fuchsia.googlesource.com/modular/+/master/examples/HOWTO_FLUTTER.md "Flutter modules" [ci_guide]: https://fuchsia.googlesource.com/infra/infra/+/master/docs/guide "Continuous integration guide" [contributing]: https://fuchsia.googlesource.com/docs/+/master/CONTRIBUTING.md "Contributing changes" diff --git a/block_devices.md b/block_devices.md index 7bb5aa6328130e11af5c4c00517d3695161c39d7..d5346ffdf629d9f80107cc0410ef65d28177e377 100644 --- a/block_devices.md +++ b/block_devices.md @@ -6,13 +6,13 @@ will have one or more handles to these underlying drivers. Similar to filesystem clients, which may send “read†or “write†requests to servers by encoding these requests within RPC messages, programs may act as clients to block devices, and may transmit RPC messages to a “device host†(referred to as “devhost†within -Magenta). The devhost process then transforms these requests into +Zircon). The devhost process then transforms these requests into driver-understood “I/O transactionsâ€, where they are actually transmitted to the particular block device driver, and eventually to real hardware. Particular block device drivers (USB, AHCI / SATA, Ramdisk, GPT, etc) implement -the [`MX_PROTOCOL_BLOCK_CORE` -prototol](https://fuchsia.googlesource.com/magenta/+/master/system/public/magenta/device/block.h), +the [`ZX_PROTOCOL_BLOCK_CORE` +prototol](https://fuchsia.googlesource.com/zircon/+/master/system/public/zircon/device/block.h), which allows clients to queue transactions and query the block device. ## Fast Block I/O diff --git a/book.md b/book.md index 794179d34a0cd4e0dce7291f5a18f9610e9f7f43..1c0d478c30a5e8851b0280f6d1931d7368559be7 100644 --- a/book.md +++ b/book.md @@ -5,17 +5,17 @@ _A modular, capability-based operating system_ This "book" is a collection of topics describing the Fuchsia operating system. Sections will be populated over time. -# Magenta Kernel +# Zircon Kernel - - [Concepts][magenta-concepts] - - [System Calls][magenta-syscalls] / VDSO (libmagenta) + - [Concepts][zircon-concepts] + - [System Calls][zircon-syscalls] / VDSO (libzircon) - Boot Sequence -# Magenta Core +# Zircon Core - Device Manager & Device Hosts - Device Driver Model (DDK) - - [C Library (libc) & POSIX IO (libmxio)](libc.md) + - [C Library (libc) & POSIX IO (libfdio)](libc.md) - [Process Start / ELF Loading (liblaunchpad)](launchpad.md) # Framework @@ -98,8 +98,8 @@ Sections will be populated over time. -[magenta-concepts]: https://fuchsia.googlesource.com/magenta/+/master/docs/concepts.md "Magenta concepts" -[magenta-syscalls]: https://fuchsia.googlesource.com/magenta/+/master/docs/syscalls.md "Magenta syscalls" +[zircon-concepts]: https://fuchsia.googlesource.com/zircon/+/master/docs/concepts.md "Zircon concepts" +[zircon-syscalls]: https://fuchsia.googlesource.com/zircon/+/master/docs/syscalls.md "Zircon syscalls" [framework-story]: https://fuchsia.googlesource.com/modular/+/master/docs/story.md "Framework story" [framework-module]: https://fuchsia.googlesource.com/modular/+/master/docs/module.md "Framework module" [framework-agent]: https://fuchsia.googlesource.com/modular/+/master/docs/agent.md "Framework agent" diff --git a/boot_sequence.md b/boot_sequence.md index 25003fcc4a96d872bc0a85a5679aeed621ac0eba..a4e503f6d254f2f9f3dc1dfb2af9ca4265b32509 100644 --- a/boot_sequence.md +++ b/boot_sequence.md @@ -1,7 +1,7 @@ Fuchsia Boot Sequence ===================== -This document describes the boot sequence for Fuchsia from the time the Magenta +This document describes the boot sequence for Fuchsia from the time the Zircon layer hands control over to the Fuchsia layer. This document is a work in progress that will need to be extended as we bring up more of the system @@ -9,7 +9,7 @@ progress that will need to be extended as we bring up more of the system `appmgr`'s job is to host the environment tree and help create processes in these environments. Processes created by `appmgr` -have an `mx::channel` back to their environment, which lets them create other +have an `zx::channel` back to their environment, which lets them create other processes in their environment and to create nested environments. At startup, `appmgr` creates an empty root environment and creates diff --git a/build_overview.md b/build_overview.md index 871a4b60129c017223b390ec325b24a466ef1a99..a67b3c2dd9b9d09b4193f200c142273569510770 100644 --- a/build_overview.md +++ b/build_overview.md @@ -66,9 +66,9 @@ Available commands and constructs are defined in the ##### A -The first step is to build the Magenta kernel which uses its own build system: +The first step is to build the Zircon kernel which uses its own build system: ``` -$ scripts/build-magenta.sh +$ scripts/build-zircon.sh ``` ##### B @@ -107,7 +107,7 @@ or if you need to include a new module, you should rerun **B** before running #### After syncing sources -You’ll most likely need to run **A** once if anything in the Magenta tree was +You’ll most likely need to run **A** once if anything in the Zircon tree was changed. After that, run **C** again. In the rare case that a module file you depend on was sync’d in the process, you’ll also need to run **B** in the usual order. diff --git a/build_system.md b/build_system.md index 071dc06ce9ee1159e0c147a2aa6f9ba09e915fa6..8937929c4bc8b55ed7e9ce68efdec5de8f614bef 100644 --- a/build_system.md +++ b/build_system.md @@ -1,20 +1,20 @@ # Fuchsia Build Notes These are notes on using the `gen.py` script and `ninja` directly for builds, -and the `scripts/run-magenta-*` scripts to launch QEMU. +and the `scripts/run-zircon-*` scripts to launch QEMU. You can alternatively use the [standard build instructions](https://fuchsia.googlesource.com/docs/+/master/getting_started.md#Setup-Build-Environment) using commands defined in `env.sh` instead. -### Build Magenta and the sysroot +### Build Zircon and the sysroot First, you need to -[build the Magenta kernel](https://fuchsia.googlesource.com/magenta/+/master/docs/getting_started.md) +[build the Zircon kernel](https://fuchsia.googlesource.com/zircon/+/master/docs/getting_started.md) and the sysroot: ``` -(cd magenta; make -j32 magenta-pc-x86-64) -./scripts/build-magenta.sh +(cd zircon; make -j32 zircon-pc-x86-64) +./scripts/build-zircon.sh ``` ### Build Fuchsia @@ -71,27 +71,27 @@ For a list of all `gen.py` options, run `gen.py --help`. The commands above create an `out/debug-{arch}/user.bootfs` file. To run the system with this filesystem attached in QEMU, pass the path to user.bootfs as -the value of the `-x` parameter in Magenta's start command script, for example: +the value of the `-x` parameter in Zircon's start command script, for example: ``` -./scripts/run-magenta-x86-64 -x out/debug-x86-64/user.bootfs -m 2048 -./scripts/run-magenta-arm64 -x out/debug-aarch64/user.bootfs -m 2048 +./scripts/run-zircon-x86-64 -x out/debug-x86-64/user.bootfs -m 2048 +./scripts/run-zircon-arm64 -x out/debug-aarch64/user.bootfs -m 2048 ``` See the [standard build instructions](https://fuchsia.googlesource.com/docs/+/master/getting_started.md#Boot-from-QEMU) for other flags you can pass to QEMU. -[magenta]: https://fuchsia.googlesource.com/magenta/+/HEAD/docs/getting_started.md "Magenta" +[zircon]: https://fuchsia.googlesource.com/zircon/+/HEAD/docs/getting_started.md "Zircon" ### Running on ARM Hardware To build a fuchsia image for a particular ARM hardware target, you must also -provide the magenta project name for that particular target to gen.py via the -magenta_project argument. For example, to build a fuchsia image for the +provide the zircon project name for that particular target to gen.py via the +zircon_project argument. For example, to build a fuchsia image for the Raspberry Pi 3, you might invoke gen.py as follows: ``` -./packages/gn/gen.py --magenta_project=magenta-rpi3-arm64 --target_cpu=aarch64 +./packages/gn/gen.py --zircon_project=zircon-rpi3-arm64 --target_cpu=aarch64 ./buildtools/ninja -C out/debug-aarch64 ``` \ No newline at end of file diff --git a/core_libraries.md b/core_libraries.md index bb99a5c9f3d4dfd2e9e3d14ff0ecfca59d550209..e57c771f4baa090ea9c4af4f5d47c5fa681e6eeb 100644 --- a/core_libraries.md +++ b/core_libraries.md @@ -4,29 +4,29 @@ Fuchsia Core Libraries This document describes the core libraries in the Fuchsia system, starting from the bottom of the dependency chain. -# Magenta libraries +# Zircon libraries -## libmagenta +## libzircon -This library defines the Magenta system ABI. +This library defines the Zircon system ABI. TODO(kulakowski) Talk about how this is not quite the kernel syscall interface, since the VDSO abstracts that. -## libmx +## libzx -libmagenta defines C types and function calls acting on those -objects. libmx is a light C++ wrapper around those. It adds type -safety beyond `mx_handle_t`, so that every kernel object type has a +libzircon defines C types and function calls acting on those +objects. libzx is a light C++ wrapper around those. It adds type +safety beyond `zx_handle_t`, so that every kernel object type has a corresponding C++ type, and adds ownership semantics to those handles. It otherwise takes no opinions around naming or policy. -For more information about libmx, see -[its documentation](https://fuchsia.googlesource.com/magenta/+/master/system/ulib/mx/README.md). +For more information about libzx, see +[its documentation](https://fuchsia.googlesource.com/zircon/+/master/system/ulib/zx/README.md). ## FBL -Much of Magenta is written in C++, both in kernel and in +Much of Zircon is written in C++, both in kernel and in userspace. Linking against the C++ standard library is not especially well suited to this environment (it is too easy to allocate, throw exceptions, etc., and the library itself is large). There are a number @@ -39,13 +39,13 @@ are useful library code for kernel and device driver environments (for instance, slab allocation). For more information about FBL, -[read its overview](https://fuchsia.googlesource.com/magenta/+/master/docs/cxx.md#fbl). +[read its overview](https://fuchsia.googlesource.com/zircon/+/master/docs/cxx.md#fbl). # FXL FXL is a platform-independent library containing basic C++ building blocks, such as logging and reference counting. FXL depends on the C++ standard library but -not on any Magenta- or Fuchsia-specific libraries. We build FXL both for target +not on any Zircon- or Fuchsia-specific libraries. We build FXL both for target (Fuchsia) and for host (Linux, Mac) systems. Generally speaking, we try to use the C++ standard library for basic building @@ -56,10 +56,10 @@ doesn't meet our requirements (e.g., `std::shared_ptr` is twice as large as # FSL -FSL is a Magenta-specific library containing high-level C++ concepts for working -with the Magenta system calls. For example, FSL provides an `fsl::MessageLoop` -abstraction on top of Magenta's underlying waiting primitives. FSL also contains -helpers for working with Magenta primitives asynchronously that build upon +FSL is a Zircon-specific library containing high-level C++ concepts for working +with the Zircon system calls. For example, FSL provides an `fsl::MessageLoop` +abstraction on top of Zircon's underlying waiting primitives. FSL also contains +helpers for working with Zircon primitives asynchronously that build upon `fsl::MessageLoop` (e.g., for draining a socket asynchronously). FSL depends on FXL and implements some interfaces defined in FXL, such as diff --git a/ctu_analysis.md b/ctu_analysis.md index 8d5c65272d98529f3092b25da01eb6d051fb05c4..dfeda431910ebec50b749b91bba6a35c127b34f3 100644 --- a/ctu_analysis.md +++ b/ctu_analysis.md @@ -1,12 +1,12 @@ -# Cross Translation Unit Static Analysis in Magenta +# Cross Translation Unit Static Analysis in Zircon This document describes: -* How to set up cross-translation-unit analysis (**CTU**) with the Clang Static Analyzer (**CSA**) in Magenta; +* How to set up cross-translation-unit analysis (**CTU**) with the Clang Static Analyzer (**CSA**) in Zircon; * The work done by Kareem Khazem during his internship; and -* The remaining work needed to get CTU fully supported on Magenta. +* The remaining work needed to get CTU fully supported on Zircon. -## Setting up and running CTU on Magenta +## Setting up and running CTU on Zircon **Summary**: Download the source for Clang, and apply several non-mainline patches to it before compiling it. Run my wrapper script around the analysis tools. Download the `CodeChecker` tool; use it to digest the results of the analysis, and start a web server to view the results with a web interface. @@ -17,7 +17,7 @@ There are two patchsets to be aware of: * The [Samsung](https://github.com/haoNoQ/clang/tree/summary-ipa-draft) patchset, which is an enormous patch adding AST merging support to Clang. It consists mostly of additions to `lib/AST/ASTImporter.cpp`. There is also a (primitive, not working very well) set of tools for CTU analysis under `tools/xtu-build/*`. This patchset is based on an old revision of Clang; this fact, as well as its large size, makes it very difficult to rebase wholesale onto tip-of-tree (**ToT**) Clang. * The [Ericsson](https://github.com/dkrupp/clang/blob/ctu-master/tools/xtu-build-new/xtu-analyze.py) patchset, which includes a subset of Samsung’s AST merging work and also adds several new tools (`tools/xtu-build-new/*` and `tools/scan-build-py/*`) that allow for CTU analysis. The xtu-build-new tools improve on, and are somewhat different to, Samsung’s xtu-build tools. This patchset is much newer than the Samsung one, and the authors are making an effort to keep it rebased on ToT. -We will be patching Clang with Ericsson’s patchset, since the AST merging work rebases cleanly and we also get the newer analysis tools. However, note that CTU support for Magenta is incomplete; in some cases, the Samsung patchset contains code that provides the required functionality (more details below). +We will be patching Clang with Ericsson’s patchset, since the AST merging work rebases cleanly and we also get the newer analysis tools. However, note that CTU support for Zircon is incomplete; in some cases, the Samsung patchset contains code that provides the required functionality (more details below). ### Steps to build CTU-capable CSA @@ -32,12 +32,12 @@ We will be patching Clang with Ericsson’s patchset, since the AST merging work ``` for p in $(ls $PATCH_DIR/*.patch | sort -n); do git am < $p; done ``` -5. Apply Kareem Khazem’s patches that are listed [below](#magenta-patches) if they haven’t already landed +5. Apply Kareem Khazem’s patches that are listed [below](#zircon-patches) if they haven’t already landed 6. Re-build upstream Clang & LLVM. ## Running CTU analysis -**Summary:** Run my wrapper script. This builds Magenta normally, then builds it again but dumping serialised ASTs instead of object files, and then finally analyses each file using the dumped ASTs to achieve CTU. +**Summary:** Run my wrapper script. This builds Zircon normally, then builds it again but dumping serialised ASTs instead of object files, and then finally analyses each file using the dumped ASTs to achieve CTU. ### How CTU works @@ -47,11 +47,11 @@ Non-CTU static analysis analyzes the AST of each TU; any function calls to exter Thus, a CTU analysis will start analyzing an AST as usual, but when it encounters a function call node, it will try to *merge in* the AST for that function. This relies on the AST for the function already having been serialized to disk beforehand, so that the analyzer can re-load the AST into memory. It also relies on support for AST merging, which is what the Samsung patch to `ASTImporter.cpp` (and the Ericsson patch derived from it) is for. -In order to serialize the ASTs to disk, we need to emulate the real build process. The way to do this is to actually do a real build of Magenta while recording the compiler invocations; this allows us to ‘play back’ the invocations, but with the compiler flags modified to dump AST files rather than object files. +In order to serialize the ASTs to disk, we need to emulate the real build process. The way to do this is to actually do a real build of Zircon while recording the compiler invocations; this allows us to ‘play back’ the invocations, but with the compiler flags modified to dump AST files rather than object files. So to summarise, forwards this time: -* Build magenta using Clang, and wrap the build process in a program like [bear](https://github.com/rizsotto/Bear) in order to record compiler invocations and generate a JSON compilation database. +* Build zircon using Clang, and wrap the build process in a program like [bear](https://github.com/rizsotto/Bear) in order to record compiler invocations and generate a JSON compilation database. * Replay the same compilation steps, but dumping AST files instead of object files. This is what the [xtu-build.py](https://github.com/dkrupp/clang/blob/ctu-master/tools/xtu-build-new/xtu-build.py) tool does. * Perform static analysis as usual, but deserialize the AST of every called function when needed. This is what the [xtu-analyze.py](https://github.com/dkrupp/clang/blob/ctu-master/tools/xtu-build-new/xtu-analyze.py) tool does at the top level, by invoking tools in the [scan-build-py/libscanbuild](https://github.com/dkrupp/clang/tree/ctu-master/tools/scan-build-py/libscanbuild) directory through the thin [scan-build replacement](https://github.com/dkrupp/clang/blob/ctu-master/tools/scan-build-py/bin/scan-build) written by the Ericsson team. @@ -66,7 +66,7 @@ There are two sets of tools for running cross-translation-unit analysis: ### Fuchsia wrapper script<a name="fuchsia-wrapper-script"></a> -[This very small shell script](https://gist.github.com/karkhaz/c8ded50e564d73853731266fec729454) wraps the Ericsson `xtu-build-new` wrappers. To do a complete analysis of Magenta, make sure to clean first, and specify the correct path to your build of Clang. Then, in the magenta directory: +[This very small shell script](https://gist.github.com/karkhaz/c8ded50e564d73853731266fec729454) wraps the Ericsson `xtu-build-new` wrappers. To do a complete analysis of Zircon, make sure to clean first, and specify the correct path to your build of Clang. Then, in the zircon directory: ``` make clean && ./run.sh @@ -75,10 +75,10 @@ make clean && ./run.sh In order to build only the kernel, specify a `TARGET` as an environment variable: ``` -make clean && TARGET=./build-magenta-pc-x86-64/magenta.elf ./run.sh +make clean && TARGET=./build-zircon-pc-x86-64/zircon.elf ./run.sh ``` -The script also requires [clangify.py](https://gist.github.com/karkhaz/2ab5e8c7a8783318d44ceca715f20438) to be in the magenta directory with executable bit set. After the analysis has finished, there will be a `.result-xtu` directory, containing: +The script also requires [clangify.py](https://gist.github.com/karkhaz/2ab5e8c7a8783318d44ceca715f20438) to be in the zircon directory with executable bit set. After the analysis has finished, there will be a `.result-xtu` directory, containing: * A bunch of Apple plist files, which are the bug reports; * A fails directory, containing the std{out,err} of analyzer invocations that returned non-zero; @@ -104,23 +104,23 @@ I ([Kareem Khazem](mailto:karkhaz@karkhaz.com)) am also happy to help out where The LLVM irc channel can also be helpful. -## Magenta-specific analyses +## Zircon-specific analyses -Upstream Clang has been very receptive to receiving patches for Magenta-specific Clang checkers. The [MutexInInterruptContext](https://reviews.llvm.org/D27854) checker is one example (ported from an LLVM pass written by Farid Molazem Tabrizi), as are the [SpinLockChecker](https://reviews.llvm.org/D26340) and [MutexChecker](https://reviews.llvm.org/D26342). Potential reviewers for Clang checks are Devin Coughlin (from Apple), Artem Dergachev (on Aleksei Sidorin’s team at Samsung) and Anna Zaks (also at Apple). +Upstream Clang has been very receptive to receiving patches for Zircon-specific Clang checkers. The [MutexInInterruptContext](https://reviews.llvm.org/D27854) checker is one example (ported from an LLVM pass written by Farid Molazem Tabrizi), as are the [SpinLockChecker](https://reviews.llvm.org/D26340) and [MutexChecker](https://reviews.llvm.org/D26342). Potential reviewers for Clang checks are Devin Coughlin (from Apple), Artem Dergachev (on Aleksei Sidorin’s team at Samsung) and Anna Zaks (also at Apple). -These checkers are typically *opt-in*, meaning that you need to pass a flag to the analyzer to enable them: something like `-analyzer-checker=optin.magenta.MutexInInterruptContext`. +These checkers are typically *opt-in*, meaning that you need to pass a flag to the analyzer to enable them: something like `-analyzer-checker=optin.zircon.MutexInInterruptContext`. -If those patches haven’t landed in Clang, you will need to apply them. To use them for analyzing Magenta with the [Ericsson wrapper scripts](#ericsson-wrapper-script), you should modify the [Fuchsia wrapper script](#fuchsia-wrapper-script) by adding the option `-e optin.magenta.MutexInInterruptContext` to the invocation of `xtu-analyze.py` at the end of the file. The patch for `MutexInInterruptContext` has a test suite, which can be used as an example of what the analysis is capable of. +If those patches haven’t landed in Clang, you will need to apply them. To use them for analyzing Zircon with the [Ericsson wrapper scripts](#ericsson-wrapper-script), you should modify the [Fuchsia wrapper script](#fuchsia-wrapper-script) by adding the option `-e optin.zircon.MutexInInterruptContext` to the invocation of `xtu-analyze.py` at the end of the file. The patch for `MutexInInterruptContext` has a test suite, which can be used as an example of what the analysis is capable of. -# Progress on CTU support in Magenta +# Progress on CTU support in Zircon ## Problems fixed in the AST importer -The upstream CSA crashes on the vast majority of Magenta files. This section describes some of the problems that Kareem Khazem encountered and their fixes. +The upstream CSA crashes on the vast majority of Zircon files. This section describes some of the problems that Kareem Khazem encountered and their fixes. -### Unsupported AST Nodes<a name="magenta-patches"></a> +### Unsupported AST Nodes<a name="zircon-patches"></a> -The Clang Static Analyzer is unable to import a lot of Magenta code, due to not having implemented support for importing certain kinds of AST nodes. Patches to support these nodes are listed here: +The Clang Static Analyzer is unable to import a lot of Zircon code, due to not having implemented support for importing certain kinds of AST nodes. Patches to support these nodes are listed here: <table> <tr> diff --git a/debugging.md b/debugging.md index dbe085437926cb87f92362d0a17c129621396cc3..7ac82d440a54df34a3baae06e0af701ce5c2c710 100644 --- a/debugging.md +++ b/debugging.md @@ -43,7 +43,7 @@ $ /boot/test/debugger-test segfault [00029.045] 01093.01133> arch: x86_64 [00029.064] 01093.01133> dso: id=018157dff2cf7052d9a0e198c08875cf080d1fc5 base=0x4000000e1000 name=<vDSO> [00029.064] 01093.01133> dso: id=bbcefdf213bbac0271e69abc2ea163e9a7bb83a8 base=0x400000000000 name=libc.so -[00029.064] 01093.01133> dso: id=fcb157b4ae828f8456769dcd217f29745902393c base=0x101a000 name=libmxio.so +[00029.064] 01093.01133> dso: id=fcb157b4ae828f8456769dcd217f29745902393c base=0x101a000 name=libfdio.so [00029.064] 01093.01133> dso: id=62e9ae64cd4b9915f4aa0fae8817df47f236f3ef base=0x1011000 name=liblaunchpad.so [00029.064] 01093.01133> dso: id=2bdcafce47915aa12e0942d59f44726c3832f0a2 base=0x100d000 name=libunittest.so [00029.064] 01093.01133> dso: id=cc891abcdb9d2f0d8fcae0ae2a98f421a0a592a8 base=0x1008000 name=libtest-utils.so @@ -72,26 +72,26 @@ addresses in the backtrace to symbolic form. This program is `symbolize`: Copy the above to a file, say `backtrace.out`, and then run: ``` -bash$ MAGENTA_BUILD_DIR=$FUCHSIA_DIR/out/build-magenta/build-magenta-pc-x86-64 -bash$ cat backtrace.out | $FUCHSIA_DIR/magenta/scripts/symbolize \ - --build-dir=$MAGENTA_BUILD_DIR \ - $MAGENTA_BUILD_DIR/system/utest/debugger/debugger.elf +bash$ ZIRCON_BUILD_DIR=$FUCHSIA_DIR/out/build-zircon/build-zircon-pc-x86-64 +bash$ cat backtrace.out | $FUCHSIA_DIR/zircon/scripts/symbolize \ + --build-dir=$ZIRCON_BUILD_DIR \ + $ZIRCON_BUILD_DIR/system/utest/debugger/debugger.elf [00029.042] 01093.01133> <== fatal exception: process [6354] thread [6403] ... same output as "raw" backtrace ... start of symbolized stack: -#01: test_segfault_leaf at /home/fuchsia/magenta/system/utest/debugger/debugger.c:570 -#02: test_segfault_doit1 at /home/fuchsia/magenta/system/utest/debugger/debugger.c:585 -#03: test_segfault_doit2 at /home/fuchsia/magenta/system/utest/debugger/debugger.c:589 -#04: test_segfault_doit1 at /home/fuchsia/magenta/system/utest/debugger/debugger.c:582 -#05: test_segfault_doit2 at /home/fuchsia/magenta/system/utest/debugger/debugger.c:589 -#06: test_segfault_doit1 at /home/fuchsia/magenta/system/utest/debugger/debugger.c:582 -#07: test_segfault_doit2 at /home/fuchsia/magenta/system/utest/debugger/debugger.c:589 -#08: test_segfault_doit1 at /home/fuchsia/magenta/system/utest/debugger/debugger.c:582 -#09: test_segfault_doit2 at /home/fuchsia/magenta/system/utest/debugger/debugger.c:589 -#10: test_segfault_doit1 at /home/fuchsia/magenta/system/utest/debugger/debugger.c:582 -#11: test_segfault at /home/fuchsia/magenta/system/utest/debugger/debugger.c:599 -#12: main at /home/fuchsia/magenta/system/utest/debugger/debugger.c:640 -#13: start_main at /home/fuchsia/magenta/third_party/ulib/musl/src/env/__libc_start_main.c:47 +#01: test_segfault_leaf at /home/fuchsia/zircon/system/utest/debugger/debugger.c:570 +#02: test_segfault_doit1 at /home/fuchsia/zircon/system/utest/debugger/debugger.c:585 +#03: test_segfault_doit2 at /home/fuchsia/zircon/system/utest/debugger/debugger.c:589 +#04: test_segfault_doit1 at /home/fuchsia/zircon/system/utest/debugger/debugger.c:582 +#05: test_segfault_doit2 at /home/fuchsia/zircon/system/utest/debugger/debugger.c:589 +#06: test_segfault_doit1 at /home/fuchsia/zircon/system/utest/debugger/debugger.c:582 +#07: test_segfault_doit2 at /home/fuchsia/zircon/system/utest/debugger/debugger.c:589 +#08: test_segfault_doit1 at /home/fuchsia/zircon/system/utest/debugger/debugger.c:582 +#09: test_segfault_doit2 at /home/fuchsia/zircon/system/utest/debugger/debugger.c:589 +#10: test_segfault_doit1 at /home/fuchsia/zircon/system/utest/debugger/debugger.c:582 +#11: test_segfault at /home/fuchsia/zircon/system/utest/debugger/debugger.c:599 +#12: main at /home/fuchsia/zircon/system/utest/debugger/debugger.c:640 +#13: start_main at /home/fuchsia/zircon/third_party/ulib/musl/src/env/__libc_start_main.c:47 #14: (unknown) end of symbolized stack ``` @@ -107,7 +107,7 @@ backtrace at a particular point in your code. Include this header: ``` -#include <magenta/crashlogger.h> +#include <zircon/crashlogger.h> ``` and then add the following where you want the backtrace printed: diff --git a/dotdot.md b/dotdot.md index ce983f6071b8cd39b72b8e4d5266082af39ee5f9..31d14383c1e02fe0f2128969d9b5b93f20b43f19 100644 --- a/dotdot.md +++ b/dotdot.md @@ -41,9 +41,9 @@ Certain paths, such as “foo/../barâ€, which can be transformed to “barâ€, determined without accessing a filesystem server in the absence of symbolic links (and at the time of writing, symbolic links do not exist on Fuchsia). These paths may be canonicalized, or cleaned, on the client-side, prior to -sending path-based requests to filesystem servers: the libmxio library already -does this for any mxio operations which are eventually transmitted to -filesystem servers in a function called `__mxio_cleanpath`. +sending path-based requests to filesystem servers: the libfdio library already +does this for any fdio operations which are eventually transmitted to +filesystem servers in a function called `__fdio_cleanpath`. ## What about shell traversal? diff --git a/filesystems.md b/filesystems.md index 6b5f78470f8c2618e92e73f1d772d9f0d2bfadf1..c7c267db660ee9b410a22c93740e1e7d4788bd88 100644 --- a/filesystems.md +++ b/filesystems.md @@ -69,7 +69,7 @@ redirect these requests to a local handle representing the “/bin†directory, rather than sending a request directly to the “bin†directory within the “root†directory. Namespaces, like all filesystem constructs, are not visible from the kernel: rather, they are implemented in client-side runtimes (such as -[libmxio](life_of_an_open.md#Mxio)) and are interposed between most client code +[libfdio](life_of_an_open.md#Fdio)) and are interposed between most client code and the handles to remote filesystems. Since namespaces operate on handles, and most Fuchsia resources and services @@ -97,20 +97,20 @@ In the case of files, directories, and devices, these operations use the RemoteIO protocol; in the case of services, these operations use the FIDL2 protocol, though there are plans to unify all operations into the FIDL protocol. -As an example, to seek within a file, a client would send an `MXRIO_SEEK` +As an example, to seek within a file, a client would send an `ZXRIO_SEEK` message with the desired position and “whence†within the RIO message, and the -new seek position would be returned. To truncate a file, an `MXIO_TRUNCATE` +new seek position would be returned. To truncate a file, an `FDIO_TRUNCATE` message could be sent with the new desired filesystem, and a status message -would be returned. To read a directory, an `MXRIO_READDIR` message could be +would be returned. To read a directory, an `ZXRIO_READDIR` message could be sent, and a list of direntries would be returned. If these requests were sent to a filesystem entity that can’t handle them, an error would be sent, and the -operation would not be executed (like an `MXRIO_READDIR` message sent to a text +operation would not be executed (like an `ZXRIO_READDIR` message sent to a text file). ### Memory Mapping For filesystems capable of supporting it, memory mapping files is slightly more -complicated. To actually “mmap†part of a file, a client sends an “MXIO_MMAP†+complicated. To actually “mmap†part of a file, a client sends an “FDIO_MMAP†message, and receives a Virtual Memory Object, or VMO, in response. This object is then typically mapped into the client’s address space using a Virtual Memory Address Region, or VMAR. Transmitting a limited view of the file’s internal @@ -142,7 +142,7 @@ location. This complicates their usage: if a call to “rename(‘/foo/bar’, * Open the parent directories of both paths * Operate on both parent directories and trailing pathnames simultaneously -To satisfy this behavior, the VFS layer takes advantage of a Magenta concept +To satisfy this behavior, the VFS layer takes advantage of a Zircon concept called “cookiesâ€. These cookies allow client-side operations to store open state on a server, using a handle, and refer to it later using that same handles. Fuchsia filesystems use this ability to refer to one Vnode while @@ -171,7 +171,7 @@ this channel is saved as a field named “remote†in the parent Vnode, the oth end will be connected to the root directory of the new filesystem), and (optionally) another to contact the underlying [block device](block_devices.md). Once a filesystem has been initialized (reading initial state off the block -device, finding the root vnode, etc) it flags a signal (`MX_USER_SIGNAL0`) on +device, finding the root vnode, etc) it flags a signal (`ZX_USER_SIGNAL0`) on the mount point channel. This informs the parent (mounting) system that the child filesystem is ready to be utilized. At this point, the channel passed to the filesystem on initialization may be used to send filesystem requests, such @@ -199,7 +199,7 @@ intending to satisfy a variety of distinct needs. ### MemFS: An in-memory filesystem -[MemFS](https://fuchsia.googlesource.com/magenta/+/master/system/core/devmgr/vfs-memory.cpp) +[MemFS](https://fuchsia.googlesource.com/zircon/+/master/system/core/devmgr/vfs-memory.cpp) is used to implement requests to temporary filesystems like `/tmp`, where files exist entirely in RAM, and are not transmitted to an underlying block device. This filesystem is also currently used for the “bootfs†protocol, where a @@ -209,7 +209,7 @@ unwrapped into user-accessible Vnodes at boot (these files are accessible in ### MinFS: A persistent filesystem -[MinFS](https://fuchsia.googlesource.com/magenta/+/master/system/uapp/minfs/) +[MinFS](https://fuchsia.googlesource.com/zircon/+/master/system/uapp/minfs/) is a simple, traditional filesystem which is capable of storing files persistently. Like MemFS, it makes extensive use of the VFS layers mentioned earlier, but unlike MemFS, it requires an additional handle to a block device @@ -220,7 +220,7 @@ filesystems to a namespace from the command line. ### Blobstore: An immutable, integrity-verifying package storage filesystem -[Blobstore](https://fuchsia.googlesource.com/magenta/+/master/system/uapp/blobstore/) +[Blobstore](https://fuchsia.googlesource.com/zircon/+/master/system/uapp/blobstore/) is a simple, flat filesystem optimized for “write-once, then read-only†[signed data](merkleroot.md), such as [application packages](package_metadata.md). Other than two small prerequisites (file names which are deterministic, content @@ -241,11 +241,11 @@ filesystem, found on EFI partitions and many USB sticks. ### ServiceFS (svcfs): A filesystem used for service discovery -[ServiceFS](https://fuchsia.googlesource.com/magenta/+/master/system/ulib/svcfs), +[ServiceFS](https://fuchsia.googlesource.com/zircon/+/master/system/ulib/svcfs), used by the [Fuchsia Application Manager](https://fuchsia.googlesource.com/application/+/master), provides a mechanism for discovering non-filesystem services using the filesystem -namespace. As mentioned earlier, the client-provided tools in mxio which can be +namespace. As mentioned earlier, the client-provided tools in fdio which can be used to access files have the option of both synchronous and asynchronous operations, and upon success, return a handle (or handles) to a remote filesystem. ServiceFS takes this one step further -- since arbitrary services diff --git a/getting_started.md b/getting_started.md index 45c783e0bc2d118a5422cf600e8da6f5a57adf85..22d7df0f41e2fcfe88155fb5815573c96c59bf2a 100644 --- a/getting_started.md +++ b/getting_started.md @@ -9,11 +9,11 @@ Fuchsia. *** note NOTE: The Fuchsia source includes -[Magenta](https://fuchsia.googlesource.com/magenta/+/master/README.md), +[Zircon](https://fuchsia.googlesource.com/zircon/+/master/README.md), the core platform that underpins Fuchsia. -The Fuchsia build process will build Magenta as a side-effect; -to work on Magenta only, read and follow Magenta's -[Getting Started](https://fuchsia.googlesource.com/magenta/+/master/docs/getting_started.md) +The Fuchsia build process will build Zircon as a side-effect; +to work on Zircon only, read and follow Zircon's +[Getting Started](https://fuchsia.googlesource.com/zircon/+/master/docs/getting_started.md) doc. *** @@ -122,7 +122,7 @@ Once you have setup your build environment, simply run: fbuild ``` -This builds Magenta, the sysroot, and the default Fuchsia build. +This builds Zircon, the sysroot, and the default Fuchsia build. ## Boot Fuchsia @@ -136,25 +136,25 @@ target hardware, using a USB drive is a good option for doing this. If you want to netboot or create a bootable USB drive, but not install Fuchsia you can use the [build-bootable-usb-gigaboot.sh script](https://fuchsia.googlesource.com/scripts/+/master/build-bootable-usb-gigaboot.sh). If you plan to netboot, pass the `-m` and `-f` options to skip copying over the -Magenta kernel and Fuchsia system images since the bootserver will supply these. +Zircon kernel and Fuchsia system images since the bootserver will supply these. It may be useful to look at some of the hardware specific instructions. The Raspberry Pi 3 requires very different procedures and the other guides may help with hardware-specific firmware configuration. -* [Acer Switch Alpha 12](https://fuchsia.googlesource.com/magenta/+/master/docs/targets/acer12.md) -* [Intel NUC](https://fuchsia.googlesource.com/magenta/+/master/docs/targets/nuc.md) -* [Raspberry Pi 3](https://fuchsia.googlesource.com/magenta/+/master/docs/targets/rpi3.md) +* [Acer Switch Alpha 12](https://fuchsia.googlesource.com/zircon/+/master/docs/targets/acer12.md) +* [Intel NUC](https://fuchsia.googlesource.com/zircon/+/master/docs/targets/nuc.md) +* [Raspberry Pi 3](https://fuchsia.googlesource.com/zircon/+/master/docs/targets/rpi3.md) Once your hardware is configured, you can run `fboot` to start the bootserver. ### Boot from QEMU If you don't have the supported hardware, you can run Fuchsia under emulation -using [QEMU](https://fuchsia.googlesource.com/magenta/+/HEAD/docs/qemu.md). +using [QEMU](https://fuchsia.googlesource.com/zircon/+/HEAD/docs/qemu.md). Fuchsia includes prebuilt binaries for QEMU under `buildtools/qemu`. -The `frun` command will launch Magenta within QEMU, using the locally built +The `frun` command will launch Zircon within QEMU, using the locally built `user.bootfs`: ``` @@ -180,7 +180,7 @@ frun -g Note: Networking support within QEMU is only available under x86_64. -First, [configure](https://fuchsia.googlesource.com/magenta/+/master/docs/qemu.md#Enabling-Networking-under-QEMU-x86_64-only) +First, [configure](https://fuchsia.googlesource.com/zircon/+/master/docs/qemu.md#Enabling-Networking-under-QEMU-x86_64-only) a virtual interface for QEMU's use. Once this is done you can add the `-N` and `-u` flags to `frun`: @@ -245,7 +245,7 @@ box and typing "moterm" ## Additional helpful documents -* Using Magenta - copying files, network booting, log viewing, and more are [here](https://fuchsia.googlesource.com/magenta/+/master/docs/getting_started.md#Copying-files-to-and-from-Magenta) +* Using Zircon - copying files, network booting, log viewing, and more are [here](https://fuchsia.googlesource.com/zircon/+/master/docs/getting_started.md#Copying-files-to-and-from-Zircon) * [Fuchsia documentation](https://fuchsia.googlesource.com/docs) hub * Build [Fuchsia's toolchain](toolchain.md) * More about the [build commands](build_system.md) called under-the-hood by `fbuild` diff --git a/glossary.md b/glossary.md index fd5c41b787cc08c3f3354f1a9752d4b386e201d2..073c5baeb88dd92f4cb1f6a52c9ebef4313ef9da 100644 --- a/glossary.md +++ b/glossary.md @@ -54,10 +54,10 @@ but are certainly not limited to modules and agents. #### **Channel** -A Channel is the fundamental IPC primitive provided by Magenta. It is a bidirectional, +A Channel is the fundamental IPC primitive provided by Zircon. It is a bidirectional, datagram-like transport that can transfer small messages including [Handles](#Handle). -- [Channel Overview](https://fuchsia.googlesource.com/magenta/+/master/docs/objects/channel.md) +- [Channel Overview](https://fuchsia.googlesource.com/zircon/+/master/docs/objects/channel.md) #### **DevHost** @@ -73,10 +73,10 @@ servers for the boot filesystem, launching [AppMgr](#AppMgr), and so on). #### **DDK** -The Driver Development Kit is the documentation, APIs, and ABIs necessary to build Magenta -Device Drivers. Device drivers are implemented as ELF shared libraries loaded by Magenta's +The Driver Development Kit is the documentation, APIs, and ABIs necessary to build Zircon +Device Drivers. Device drivers are implemented as ELF shared libraries loaded by Zircon's Device Manager. -- [DDK includes](https://fuchsia.googlesource.com/magenta/+/master/system/ulib/ddk/include/ddk/) +- [DDK includes](https://fuchsia.googlesource.com/zircon/+/master/system/ulib/ddk/include/ddk/) #### **Escher** @@ -87,8 +87,8 @@ qualities suitable for user interfaces. #### **FAR** -The Fuchsia Archive Format is a container for files to be used by Magenta and Fuchsia. -It will replace Magenta's older BootFS container and be used in Fuchsia Packages. +The Fuchsia Archive Format is a container for files to be used by Zircon and Fuchsia. +It will replace Zircon's older BootFS container and be used in Fuchsia Packages. - [FAR Spec](https://fuchsia.googlesource.com/docs/+/master/archive_format.md) #### **FIDL** @@ -117,9 +117,9 @@ GN files, named `BUILD.gn`, are located all over the repository. #### **Handle** -The "file descriptor" of the Magenta kernel. A Handle is how a userspace process refers +The "file descriptor" of the Zircon kernel. A Handle is how a userspace process refers to a kernel object. They can be passed to other processes over [Channel](#Channel)s. -- [Handle (in Magenta Concepts Doc)](https://fuchsia.googlesource.com/magenta/+/master/docs/concepts.md) +- [Handle (in Zircon Concepts Doc)](https://fuchsia.googlesource.com/zircon/+/master/docs/concepts.md) #### **Jiri** @@ -127,12 +127,12 @@ to a kernel object. They can be passed to other processes over [Channel](#Chann #### **Launchpad** -[Launchpad](launchpad.md) is a library provided by Magenta that provides the +[Launchpad](launchpad.md) is a library provided by Zircon that provides the functionality to create and start new processes (including loading ELF binaries, passing initial RPC messages needed by runtime init, etc). It is a low-level library and over time it is expected that few pieces of code will make direct use of it. -- [Launchpad API (launchpad.h)](https://fuchsia.googlesource.com/magenta/+/master/system/ulib/launchpad/include/launchpad/launchpad.h) +- [Launchpad API (launchpad.h)](https://fuchsia.googlesource.com/zircon/+/master/system/ulib/launchpad/include/launchpad/launchpad.h) #### **Ledger** @@ -143,19 +143,19 @@ Ledger under-the-hood. #### **LK** -Little Kernel (LK) is the embedded kernel that formed the core of the Magenta Kernel. +Little Kernel (LK) is the embedded kernel that formed the core of the Zircon Kernel. LK is more microcontroller-centric and lacks support for MMUs, userspace, system calls -- -features that Magenta added. +features that Zircon added. - [LK on Github](https://github.com/littlekernel/lk) -#### **Magenta** +#### **Zircon** -Magenta is the [microkernel](https://en.wikipedia.org/wiki/Microkernel) and lowest level +Zircon is the [microkernel](https://en.wikipedia.org/wiki/Microkernel) and lowest level userspace components (driver runtime environment, core drivers, libc, etc) at the core of -Fuchsia. In a traditional monolithic kernel, many of the userspace components of Magenta +Fuchsia. In a traditional monolithic kernel, many of the userspace components of Zircon would be part of the kernel itself. -- [Magenta Documentation](https://fuchsia.googlesource.com/magenta/+/master/README.md) -- [Magenta Concepts](https://fuchsia.googlesource.com/magenta/+/master/docs/concepts.md) +- [Zircon Documentation](https://fuchsia.googlesource.com/zircon/+/master/README.md) +- [Zircon Concepts](https://fuchsia.googlesource.com/zircon/+/master/docs/concepts.md) #### **Maxwell** @@ -176,19 +176,19 @@ The view subsystem. Includes views, input, compositor, and GPU service. #### **Musl** Fuchsia's standard C library (libc) is based on Musl Libc. -- [Source](https://fuchsia.googlesource.com/magenta/+/master/third_party/ulib/musl/) +- [Source](https://fuchsia.googlesource.com/zircon/+/master/third_party/ulib/musl/) - [Musl Homepage](https://www.musl-libc.org/) -#### **MX** +#### **ZX** -MX is an abbreviation of "Magenta" used in Magenta C APIs/ABIs (`mx_channel_create()`, `mx_handle_t`, - `MX_EVENT_SIGNALED`, etc) and libraries (libmx in particular). +ZX is an abbreviation of "Zircon" used in Zircon C APIs/ABIs (`zx_channel_create()`, `zx_handle_t`, + `ZX_EVENT_SIGNALED`, etc) and libraries (libzx in particular). -#### **mxio** +#### **fdio** -mxio is the Magenta IO Library. It provides the implementation of posix-style open(), close(), +fdio is the Zircon IO Library. It provides the implementation of posix-style open(), close(), read(), write(), select(), poll(), etc, against the RemoteIO RPC protocol. These APIs are -return-not-supported stubs in libc, and linking against libmxio overrides these stubs with +return-not-supported stubs in libc, and linking against libfdio overrides these stubs with functional implementations. #### **Namespace** @@ -212,7 +212,7 @@ should be generated by more featureful systems, such as [GN](#gn) in Fuchsia. #### **RemoteIO** -RemoteIO is the Magenta RPC protocol used between mxio (open/close/read/write/ioctl) +RemoteIO is the Zircon RPC protocol used between fdio (open/close/read/write/ioctl) and filesystems, device drivers, etc. As part of [FIDL](#FIDL) v2, it will become a set of FIDL Interfaces (File, Directory, Device, ...) allowing easier interoperability, and more flexible asynchronous IO for clients or servers. @@ -248,21 +248,21 @@ with modules. #### **VDSO** -The VDSO is a Virtual Shared Library -- it is provided by the [Magenta](#Magenta) kernel -and does not appear in the filesystem or a package. It provides the Magenta System Call +The VDSO is a Virtual Shared Library -- it is provided by the [Zircon](#Zircon) kernel +and does not appear in the filesystem or a package. It provides the Zircon System Call API/ABI to userspace processes in the form of an ELF library that's "always there." -In the Fuchsia SDK and [Magenta DDK](#DDK) it exists as `libmagenta.so` for the purpose of +In the Fuchsia SDK and [Zircon DDK](#DDK) it exists as `libzircon.so` for the purpose of having something to pass to the linker representing the VDSO. #### **VMAR** -A Virtual Memory Address Range is a Magenta Kernel Object that controls where and how +A Virtual Memory Address Range is a Zircon Kernel Object that controls where and how VMOs may be mapped into the address space of a process. -- [VMAR Overview](https://fuchsia.googlesource.com/magenta/+/master/docs/objects/vm_address_region.md) +- [VMAR Overview](https://fuchsia.googlesource.com/zircon/+/master/docs/objects/vm_address_region.md) #### **VMO** -A Virtual Memory Object is a Magenta Kernel Object that represents a collection of pages +A Virtual Memory Object is a Zircon Kernel Object that represents a collection of pages (or the potential for pages) which may be read, written, mapped into the address space of a process, or shared with another process by passing a Handle over a Channel. -- [VMO Overview](https://fuchsia.googlesource.com/magenta/+/master/docs/objects/vm_object.md) +- [VMO Overview](https://fuchsia.googlesource.com/zircon/+/master/docs/objects/vm_object.md) diff --git a/launchpad.md b/launchpad.md index 5f90f7e157435674495a2ad885d65a41af2db42c..23c8d1621b07fd4f6bddcd813c08d60ffd9598a7 100644 --- a/launchpad.md +++ b/launchpad.md @@ -1,6 +1,6 @@ # launchpad -[launchpad][launchpad] is a Magenta library that provides the +[launchpad][launchpad] is a Zircon library that provides the functionality to create and start new processes (including loading ELF binaries, passing initial RPC messages needed by runtime init, etc). It is a low-level library and over time it is expected that few pieces @@ -17,5 +17,5 @@ new Process. This includes: There is extensive documentation about launchpad in [its primary header file][launchpad-header]. -[launchpad]: https://fuchsia.googlesource.com/magenta/+/master/system/ulib/launchpad "launchpad" -[launchpad-header]: https://fuchsia.googlesource.com/magenta/+/master/system/ulib/launchpad/include/launchpad/launchpad.h "launchpad header" +[launchpad]: https://fuchsia.googlesource.com/zircon/+/master/system/ulib/launchpad "launchpad" +[launchpad-header]: https://fuchsia.googlesource.com/zircon/+/master/system/ulib/launchpad/include/launchpad/launchpad.h "launchpad header" diff --git a/libc.md b/libc.md index 9efebc87a10c63d5e5a0cf1a3f28a76db701bed7..deb1fcf947621d1bbed3c51a60388d56fb74d3c8 100644 --- a/libc.md +++ b/libc.md @@ -17,9 +17,9 @@ interface. In constast, Windows does not provide a systemwide libc in its stable win32 interface. On Fuchsia the story is a bit different from Posix systems. First, the -Magenta kernel (Fuchsia's microkernel) does not provide a typical +Zircon kernel (Fuchsia's microkernel) does not provide a typical Posix system call interface. So a Posix function like `open` can't -call a Magenta `open` syscall. Secondly, Fuchsia implements some parts +call a Zircon `open` syscall. Secondly, Fuchsia implements some parts of Posix, but omits large parts of the Posix model. Most conspicuously absent are signals, fork, and exec. Third, Fuchsia does not require that programs use libc's ABI. Programs are free to use their own libc, @@ -39,7 +39,7 @@ Fuchsia's libc implements the C11 standard. In particular this includes the threading-related interfaces such as threads (`thrd_t`) and mutexes (`mtx_t`). A small handful of extensions are also in this portion of the system to bridge the C11 structures, like a `thrd_t`, -to underlying kernel structures, like the `mx_handle_t` underlying it. +to underlying kernel structures, like the `zx_handle_t` underlying it. ### Posix @@ -48,16 +48,16 @@ exhaustively): file I/O, BSD sockets, and pthreads. #### File I/O and BSD sockets -Recall that Magenta is a microkernel that is not in the business of +Recall that Zircon is a microkernel that is not in the business of implementing file I/O. Instead, other Fuchsia userspace services provide filesystems. libc itself defines weak symbols for Posix file I/O functions such as `open`, `write`, and `fstat`. However, all these calls simply fail. In addition to libc.so, programs can link the -mxio.so library. mxio knows how to speak to those other Fuchsia +fdio.so library. fdio knows how to speak to those other Fuchsia services over [Channel IPC](concepts.md#message-passing-sockets-and-channels), and provides a Posix-like layer for libc to expose. Sockets are similarly -implemented via mxio communicating with the userspace network stack. +implemented via fdio communicating with the userspace network stack. #### pthreads @@ -70,7 +70,7 @@ be comprehensive. #### Signals -Fuchsia does not have Unix-style signals. Magenta provides no way to +Fuchsia does not have Unix-style signals. Zircon provides no way to directly implement them (the kernel provides no way to cause another thread to jump off its thread of execution). Fuchsia's libc does not, therefore, have a notion of signal-safe functions, and is not @@ -84,8 +84,8 @@ and code written for both Posix and Fuchsia may still have #### fork and exec -Magenta does not have fork or exec. Instead, process creation is -provided by [launchpad](launchpad.md). While Magenta has Process and +Zircon does not have fork or exec. Instead, process creation is +provided by [launchpad](launchpad.md). While Zircon has Process and Thread objects, these are pretty raw and know nothing about ELF. Launchpad knows how to turn an ELF and some initial state into a running process. diff --git a/life_of_an_open.md b/life_of_an_open.md index dc77d1f9a8438cb196636313124197b7672650a7..bf86fc6ac3f2484b5df2a318198e199f0d1ec525 100644 --- a/life_of_an_open.md +++ b/life_of_an_open.md @@ -17,7 +17,7 @@ Where does that request go? The ‘open’ call is a function, provided by a [standard library](libc.md). For C/C++ programs, this will normally be declared in `unistd.h`, which has a backing definition in -[libmxio](https://fuchsia.googlesource.com/magenta/+/master/system/ulib/mxio/). +[libfdio](https://fuchsia.googlesource.com/zircon/+/master/system/ulib/fdio/). For Go programs, there is an equivalent (but distinct) implementation in the Go standard library. For each language and runtime, developers may opt into their own definition of “openâ€. @@ -25,7 +25,7 @@ own definition of “openâ€. On a monolithic kernel, `open` would be a lightweight shim around a system call, where the kernel might handle path parsing, redirection, etc. In that model, the kernel would need to mediate access to resources based on exterior -knowledge about the caller. The Magenta kernel, however, intentionally has no +knowledge about the caller. The Zircon kernel, however, intentionally has no such system call. Instead, clients access filesystems through **channels** -- when a process is initialized, it may be provided a handle representing the **root (“/â€) directory** and a handle representing the current working @@ -45,10 +45,10 @@ pipes, etc, what does the standard library do to make all these resources appear functionally the same? How does that client know what messages to send over these handles? -## Mxio +## Fdio A library called -[**mxio**](https://fuchsia.googlesource.com/magenta/+/master/system/ulib/mxio/) +[**fdio**](https://fuchsia.googlesource.com/zircon/+/master/system/ulib/fdio/) is responsible for providing a unified interface to a variety of resources -- files, sockets, services, pipes, and more. This layer defines a group of functions, such as **read, write, open, close, seek, etc** that may be used on @@ -67,16 +67,16 @@ used by filesystem clients: RemoteIO. ## RemoteIO A program calling `open("foo")` will have called into the standard library, -found an “mxio†object corresponding to the current working directory, and will +found an “fdio†object corresponding to the current working directory, and will need to send a request to a remote server to “please open fooâ€. How can this be accomplished? The program has the following tools: * One or more **handles** representing a connection to the CWD - * [mx_channel_write](https://fuchsia.googlesource.com/magenta/+/master/docs/syscalls/channel_write.md): + * [zx_channel_write](https://fuchsia.googlesource.com/zircon/+/master/docs/syscalls/channel_write.md): A system call which can send bytes and handles (over a channel) - * [mx_channel_read](https://fuchsia.googlesource.com/magenta/+/master/docs/syscalls/channel_read.md): + * [zx_channel_read](https://fuchsia.googlesource.com/zircon/+/master/docs/syscalls/channel_read.md): A system call which can receive bytes and handles (over a channel) - * [mx_object_wait_one](https://fuchsia.googlesource.com/magenta/+/master/docs/syscalls/object_wait_one.md): + * [zx_object_wait_one](https://fuchsia.googlesource.com/zircon/+/master/docs/syscalls/object_wait_one.md): A system call which can wait for a handle to be readable / writable Using these primitives, the client can write a message to the filesystem server @@ -93,11 +93,11 @@ have arbitrary control over the server, this communication layer would be ripe for exploitation. The [RemoteIO protocol -(RIO)](https://fuchsia.googlesource.com/magenta/+/master/system/ulib/mxio/include/mxio/remoteio.h) +(RIO)](https://fuchsia.googlesource.com/zircon/+/master/system/ulib/fdio/include/fdio/remoteio.h) describes the wire-format of what these bytes and handles should actually mean when transmitted between two entities. The protocol describes things like “expected number of handlesâ€, “enumerated operationâ€, and “dataâ€. In our case, -`open("foo")` creates an `MXRIO_OPEN` message, and sets the “data†field of the RIO +`open("foo")` creates an `ZXRIO_OPEN` message, and sets the “data†field of the RIO message to the string “fooâ€. Additionally, if any flags are passed to open (such as `O_RDONLY, O_RDWR, O_CREAT`, etc) these flags would be placed in the “arg†field of the rio structure. However, if the operation was changed @@ -117,7 +117,7 @@ advantage of the multiple-runtime interoperability that FIDL provides. In the future, the two protocols will become unified, and FIDL binding will be automatically generated and typechecked in a variety of languages. -**libmxio** contains both the client and server-side code for the C/C++ +**libfdio** contains both the client and server-side code for the C/C++ implementation of RIO, and is responsible for cautiously verifying the input and output of both ends. @@ -134,9 +134,9 @@ is actually opened. This behavior is critical for interaction with services (which will be described in more detail in the “ServiceFS†section). To recap, an “open†call has gone through the standard library, acted on the -“CWD†mxio object, which transformed the request into a RIO message which is -sent to the server using the `mx_channel_write` system call. The client can -optionally wait for the server’s response using `mx_object_wait_one`, or continue +“CWD†fdio object, which transformed the request into a RIO message which is +sent to the server using the `zx_channel_write` system call. The client can +optionally wait for the server’s response using `zx_object_wait_one`, or continue processing asynchronously. Either way, a channel has been created, where one end lives with the client, and the other end is transmitted to the “server". @@ -159,7 +159,7 @@ to read the message transmitted by the client. This process isn’t automatic -- the server will need to intentionally wait for incoming messages on the receiving handle, which in this case was the “current working directory†handle. When server objects (files, directories, services, etc) are opened, -their handles are registered with a server-side Magenta **port** that waits for +their handles are registered with a server-side Zircon **port** that waits for their underlying handles to be **readable** (implying a message has arrived) or **closed** (implying they will never receive more messages). This object which dispatches incoming requests to appropriate handles is known as the dispatcher; @@ -184,7 +184,7 @@ For C++ filesystems using libfs, this callback function is called This handler function, equipped with this information, acts as a large “switch/case†table, redirecting the RIO message to an appropriate function depending on the “operation†field provided by the client. In the open case, the -`MXRIO_OPEN` field is noticed as the operation, so (1) a handle is expected, and +`ZXRIO_OPEN` field is noticed as the operation, so (1) a handle is expected, and (2) the ‘data’ field (“fooâ€) is interpreted as the path. ### VFS Layer @@ -197,9 +197,9 @@ they have no obligation to use it. To be a filesystem server, a process must merely understand the remote IO wire format. As a consequence, there could be any number of “VFS†implementations in a language, but at the time of writing, two well-known implementations exist: one written in C++ within the [libfs -library](https://fuchsia.googlesource.com/magenta/+/master/system/ulib/fs/), +library](https://fuchsia.googlesource.com/zircon/+/master/system/ulib/fs/), and another written in Go in the [rpc package of -ThinFS](https://fuchsia.googlesource.com/thinfs/+/master/magenta/rpc/rpc.go)] +ThinFS](https://fuchsia.googlesource.com/thinfs/+/master/zircon/rpc/rpc.go)] The VFS layer defines the interface of operations which may be routed to the underlying filesystem, including: @@ -252,7 +252,7 @@ server. Since the call was synchronous, the client proceeded to wait for a response on the handle. Once the server properly found, opened, and initialized I/O state for this file, it sent back a “success†RIO description object. This object would be read by the client, identifying that the call completed -successfully. At this point, the client could create an mxio object +successfully. At this point, the client could create an fdio object representing the handle to “fooâ€, reference it with an entry in a file descriptor table, and return the fd back to whoever called the original “open†function. Furthermore, if the client wants to send any additional requests @@ -267,13 +267,13 @@ need to route through the ‘CWD’ on future requests. | Client Program | +-----------------------------+ | fd: x | fd: y | -| Mxio (RIO) | Mxio (RIO) | +| Fdio (RIO) | Fdio (RIO) | +-------------------------+ | '/' Handle | CWD Handle | +-------------------------+ ^ ^ | | -Magenta Channels, speaking RIO State BEFORE open(‘foo’) +Zircon Channels, speaking RIO State BEFORE open(‘foo’) | | v v +-------------------------+ @@ -291,13 +291,13 @@ Magenta Channels, speaking RIO State BEFORE open(‘foo’) | Client Program | +-----------------------------+ | fd: x | fd: y | -| Mxio (RIO) | Mxio (RIO) | +| Fdio (RIO) | Fdio (RIO) | +-------------------------+ | '/' Handle | CWD Handle | **foo Handle x2** +-------------------------+ ^ ^ | | -Magenta Channels, speaking RIO Client Creates Channel +Zircon Channels, speaking RIO Client Creates Channel | | v v +-------------------------+ @@ -315,13 +315,13 @@ Magenta Channels, speaking RIO Client Creates Channel | Client Program | +-----------------------------+ | fd: x | fd: y | -| Mxio (RIO) | Mxio (RIO) | +| Fdio (RIO) | Fdio (RIO) | +-------------------------+--------------+ | '/' Handle | CWD Handle | ‘foo’ Handle | +-------------------------+--------------+ ^ ^ | | -Magenta Channels, speaking RIO Client Sends RIO message to Server +Zircon Channels, speaking RIO Client Sends RIO message to Server | | Message includes a ‘foo’ handle v v (and waits for response) +-------------------------+ @@ -339,13 +339,13 @@ Magenta Channels, speaking RIO Client Sends RIO message to Ser | Client Program | +-----------------------------+ | fd: x | fd: y | -| Mxio (RIO) | Mxio (RIO) | +| Fdio (RIO) | Fdio (RIO) | +-------------------------+--------------+ | '/' Handle | CWD Handle | ‘foo’ Handle | +-------------------------+--------------+ ^ ^ | | -Magenta Channels, speaking RIO Server dispatches message to I/O State, +Zircon Channels, speaking RIO Server dispatches message to I/O State, | | Interprets as ‘open’ v v Finds or Creates ‘foo’ +-------------------------+ @@ -363,13 +363,13 @@ Magenta Channels, speaking RIO Server dispatches message to I/ | Client Program | +-----------------------------+ | fd: x | fd: y | -| Mxio (RIO) | Mxio (RIO) | +| Fdio (RIO) | Fdio (RIO) | +-------------------------+--------------+ | '/' Handle | CWD Handle | ‘foo’ Handle | +-------------------------+--------------+ ^ ^ ^ | | | -Magenta Channels, speaking RIO| Server allocates I/O state for Vnode +Zircon Channels, speaking RIO| Server allocates I/O state for Vnode | | | Responds to client-provided handle v v v +-------------------------+--------------+ @@ -387,14 +387,14 @@ Magenta Channels, speaking RIO| Server allocates I/O state for | Client Program | +-----------------------------+----------+ | fd: x | fd: y | fd: z | -| Mxio (RIO) | Mxio (RIO) | Mxio (RIO) | +| Fdio (RIO) | Fdio (RIO) | Fdio (RIO) | +-------------------------+--------------+ | '/' Handle | CWD Handle | ‘foo’ Handle | +-------------------------+--------------+ ^ ^ ^ | | | -Magenta Channels, speaking RIO| Client recognizes that ‘foo’ was opened - | | | Allocated Mxio + fd, ‘open’ succeeds. +Zircon Channels, speaking RIO| Client recognizes that ‘foo’ was opened + | | | Allocated Fdio + fd, ‘open’ succeeds. v v v +-------------------------+--------------+ | '/' Handle | CWD Handle | ‘foo’ Handle | diff --git a/magentix.md b/magentix.md index 1a0e0ac4575e0bd36e05962e4336651618fcc963..48ebb4d2be2ece4329c1b7cb6a88d9a60dc66c46 100644 --- a/magentix.md +++ b/magentix.md @@ -1,6 +1,6 @@ # Magentix -Magentix is a build configuration of the system that contains the Magenta +Magentix is a build configuration of the system that contains the Zircon kernel, drivers, benchmarks, and some traditional POSIX-like userland tools. The Magentix configuration can be built with a subset of the full source tree. diff --git a/merkleroot.md b/merkleroot.md index fcfa6fded3fe77645fb8e772d75d1d74a28a6252..a008aaea7a52680c215f55034bb0c39f220dd46b 100644 --- a/merkleroot.md +++ b/merkleroot.md @@ -4,10 +4,10 @@ including the [FAR Archive Format][far], the Blob Storage Filesystem, and the [Package Manager][pm]. -In [Magenta][magenta] `mx-verity` provides an API for application components to +In [Zircon][zircon] `zx-verity` provides an API for application components to read data from local storage. When retrieving data the integrity of the data is verified and causing reads to fail when the data has been modified or corrupted. -mx-verity is based on a [Merkle Tree][merkletree], and is derived form a similar +zx-verity is based on a [Merkle Tree][merkletree], and is derived from a similar system in [Chrome OS][dmverity]. All of these implementations share the algorithm documented herein. @@ -81,4 +81,4 @@ the SHA-256 of 8 0 bytes, the block identity of a single 0 length block. [dmverity]: https://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot "Chrome OS Verified Boot" [far]: archive_format.md "Archive Format" [pm]: https://fuchsia.googlesource.com/pm/+/master/README.md "Package Manager" -[magenta]: https://fuchsia.googlesource.com/magenta/+/master/README.md "Magenta" +[zircon]: https://fuchsia.googlesource.com/zircon/+/master/README.md "Zircon" diff --git a/multi_device.md b/multi_device.md index 38f30c7e0dd57f5da5255e496e0b891d55e0176f..07d56cfac050ed206eaa44ed880c7a69caaed397 100644 --- a/multi_device.md +++ b/multi_device.md @@ -44,7 +44,7 @@ synchronize their state across multiple devices. Follow the steps in Ledger's [User Guide](https://fuchsia.googlesource.com/ledger/+/master/docs/user_guide.md) to: -* Set up [persistent storage](https://fuchsia.googlesource.com/magenta/+/master/docs/minfs.md). (optional) +* Set up [persistent storage](https://fuchsia.googlesource.com/zircon/+/master/docs/minfs.md). (optional) * Verify the network is connected. * Configure a Firebase instance. * Setup sync on each device using `configure_ledger`. diff --git a/namespaces.md b/namespaces.md index 2a269c213c716f23afa01c8a5198e69f31874be2..4e5a88deeecd317d4b964696f2d392d0b13f0574 100644 --- a/namespaces.md +++ b/namespaces.md @@ -172,7 +172,7 @@ are not valid arguments to a container's `Open()` method; they must be translated by the client prior to communicating with the namespace. See [FIDL Interfaces](#fidl-interfaces). -For example, `mxio` implements client-side interpretation of `..` paths +For example, `fdio` implements client-side interpretation of `..` paths in file manipulation APIs such as `open()`, `stat()`, `unlink()`, etc. ## Namespace Transfer diff --git a/qemu_persistent_disk.md b/qemu_persistent_disk.md index f5237ac030300aaa99c7e8374c0a71ec70b3d49d..ea6f270a3b274582a90a24cbc8346237d00cead7 100644 --- a/qemu_persistent_disk.md +++ b/qemu_persistent_disk.md @@ -25,8 +25,8 @@ $ cd $FUCHSIA_DIR $ mkfile -n 1g blk.bin ``` -## Start magenta -You don't need a full Fuchsia UI to set up the disk image so start just magenta +## Start zircon +You don't need a full Fuchsia UI to set up the disk image so start just zircon but tell it to mount ``` $ mrun -d [00000.000] 00000.00000> multiboot: info @ 0xffffff8000009500 diff --git a/toolchain.md b/toolchain.md index 623cbd4aeff54db7bc9f535d50f7b816e4ff84a6..781a02e75ec9564f9c5c61ce5130b145fb53675a 100644 --- a/toolchain.md +++ b/toolchain.md @@ -27,20 +27,20 @@ LLVM_SRCDIR=${HOME}/llvm ``` Before building the runtime libraries that are built along with the -compiler, you need a Magenta `sysroot` built. This comes from the -Magenta build and sits in the `sysroot` subdirectory of the main Magenta -build directory. For example, `.../build-magenta-pc-x86-64/sysroot`. +compiler, you need a Zircon `sysroot` built. This comes from the +Zircon build and sits in the `sysroot` subdirectory of the main Zircon +build directory. For example, `.../build-zircon-pc-x86-64/sysroot`. In the following commands, the string `${FUCHSIA_${arch}_SYSROOT}` stands in for this absolute directory name. You can cut & paste these commands into a shell after setting the `FUCHSIA_${arch}_SYSROOT` variable, e.g.: ```bash -make magenta-pc-x86-64 -FUCHSIA_x86_64_SYSROOT=`pwd`/build-magenta-pc-x86-64/sysroot +make zircon-pc-x86-64 +FUCHSIA_x86_64_SYSROOT=`pwd`/build-zircon-pc-x86-64/sysroot -make magenta-qemu-arm64 -FUCHSIA_aarch64_SYSROOT=`pwd`/build-magenta-qemu-arm64/sysroot +make zircon-qemu-arm64 +FUCHSIA_aarch64_SYSROOT=`pwd`/build-zircon-qemu-arm64/sysroot ``` You can build a Fuchsia Clang compiler using the following commands. @@ -64,7 +64,7 @@ ninja stage2-install-distribution To use the compiler just built without installing it into a system-wide shared location, you can just refer to its build directory explicitly as `${LLVM_OBJDIR}/tools/clang/stage2-bins/bin/` (where `LLVM_OBJDIR` is -your LLVM build directory). For example, in a Magenta build, you can +your LLVM build directory). For example, in a Zircon build, you can pass the argument: ```bash @@ -104,7 +104,7 @@ flags: For this kind of build, the `bin` directory immediate under your main LLVM build directory contains the compiler binaries. You can put that directory into your shell's `PATH`, or use it explicitly in commands, or use it in the -`CLANG_TOOLCHAIN_PREFIX` variable (with trailing slash) for a Magenta build. +`CLANG_TOOLCHAIN_PREFIX` variable (with trailing slash) for a Zircon build. Clang is a large project and compiler performance is absolutely critical. To reduce the build time, we recommend using Clang as a host compiler, and if @@ -119,7 +119,7 @@ To set the host compiler, you can use the following extra flags: This assumes that `${CLANG_TOOLCHAIN_PREFIX}` points to the `bin` directory of a Clang installation, with a trailing slash (as this Make variable is used -in the Magenta build). For example, to use the compiler from your Fuchsia +in the Zircon build). For example, to use the compiler from your Fuchsia checkout (on Linux): ```bash diff --git a/wireless_networking.md b/wireless_networking.md index 8b75fbf32cf4b26d39e1a3f96cc8ecc2746faeb9..6fc994927844d6c1d662aba1c7e4a9884fa67372 100644 --- a/wireless_networking.md +++ b/wireless_networking.md @@ -16,7 +16,7 @@ in the firmware and the host OS, respectively. +------------------+ +------------------+ ^ ^ ^ | | | - mxio/FIDL ------|------------------------|----------------|------------------- + fdio/FIDL ------|------------------------|----------------|------------------- | | | v | v +------------------+ | +--------------+