| # Launching Filesystems on Fuchsia | |
| Filesystems on Fuchsia are regular programs that run in userspace. They consume a block device and | |
| a set of options, and produce an export directory with several protocols, first and foremost a | |
| fuchsia.io.Directory representing the root of the filesystem at `/root`. | |
| There are currently two ways to launch a filesystem. One way, the old way which is being | |
| deprecated, is to launch the raw filesystem binary, and the other way, which filesystems are moving | |
| to, is to launch as a component via the component framework. Both of these methods are supported by | |
| fs_management libraries in C++ and Rust (the Rust implementation is pending - https://fxbug.dev/42178109). | |
| No matter how the filesystem is launched (the old way or the new way), all our platform filesystems | |
| have the same structure to the export directory. The basic entries are - | |
| ``` | |
| /diagnostics | |
| /fuchsia.fs.Admin | |
| /root | |
| ``` | |
| `diagnostics` provides the inspect tree implementation, which has a bunch of statistics and | |
| metrics. `fuchsia.fs.Admin` provides the ability to shut down a filesystem instance. `root` is the | |
| root of the filesystem. Other platform filesystems may include additional entries. For example, | |
| blobfs provides `/fuchsia.update.verify.ComponentOtaHealthVerification`. | |
| ## Launching filesystems with fs_management | |
| Filesystems are launched using the `fs_management::Mount`, which takes a block device file | |
| descriptor, an optional mount path, the disk format, options, and a launch callback. Mount returns | |
| an RAII MountedFilesystem object with which you can Unmount and get access to the export directory. | |
| The block device should be opened as read-write unless you configure the filesystem to be in | |
| read-only mode. One option for block device paths to open is in `/block` (or `/debug_block`), which | |
| is an enumerated list of block devices Fuchsia knows about (starting at `000` and counting up). | |
| It's populated in the order that the drivers are bound, which is _not_ consistent across boots. The | |
| other option is to use the topological path, which will depend on the drivers the storage uses (but | |
| is otherwise consistent). Both of these can be found using `lsblk` on the command line. A couple of | |
| examples - | |
| ``` | |
| /dev/sys/platform/00:00:2d/ramctl/ramdisk-0/block | |
| /dev/sys/platform/pci/00:1f.2/ahci/sata0/block | |
| ``` | |
| If you are launching a filesystem on a ramdisk, you can use the ramdisk functions to get the | |
| ramdisk path. | |
| The `mount_path` is expected to be a non-existing path in your namespace. fs_management uses | |
| fdio_namespace_bind to place the root of the filesystem at that path in your local namespace. Note: | |
| This path is process local! Only your process sees the namespace, and a new one is created for | |
| every process. See //docs/concepts/process/namespaces.md for more information. | |
| The options struct, `fs_management::MountOptions`, contains a union of all possible filesystem | |
| configuration. That is, not all filesystems support all the options. Make sure that the filesystem | |
| you are launching supports the option you are using, or else it may fail to launch. | |
| If both `component_child_name` and `component_collection_name` are provided, then fs_management | |
| will assume the component is a dynamic child in the realm. It attempts to connect to it's exposed | |
| directory via `fuchsia.component.Realm`, and if it fails because it can't find a component with the | |
| given name, it attempts to launch a new instance, using a component url based on the disk format. | |
| If only `component_child_name` is provided, then fs_management will assume the component is a static | |
| child in the realm. It attempts to connect to it's exposed directory via | |
| `fuchsia.component.Realm`. | |
| A shard is provided for cml files to include if they plan to launch filesystems as dynamic children | |
| at `//src/storage/lib/fs_management/client.shard.cml`. The `component_collection_name` using this | |
| shard is `fs-collection`. | |
| Launching a filesystem using regular processes - | |
| ```cpp | |
| fbl::unique_fd device_fd(open("/block/001/fuchsia.storage.block.Block", O_RDWR)); | |
| ASSERT_TRUE(device_fd); | |
| fs_management::MountOptions options; | |
| auto fs = fs_management::Mount(std::move(device_fd), fs_management::kDiskFormatMinfs, options); | |
| ASSERT_EQ(fs.status(), ZX_OK); | |
| auto data = fs->DataRoot(); | |
| ASSERT_EQ(data.status(), ZX_OK); | |
| auto binding = fs_management::NamespaceBinding::Create("/fs", std::move(*data)); | |
| ASSERT_EQ(binding.status(), ZX_OK); | |
| // Now /fs points at the root of the filesystem. | |
| ``` | |
| Launching a filesystem using a component collection - | |
| ```cpp | |
| fbl::unique_fd device_fd(open("/block/001/fuchsia.storage.block.Block", O_RDWR)); | |
| ASSERT_TRUE(device_fd); | |
| fs_management::MountOptions options { | |
| .component_child_name = "minfs", | |
| .component_collection_name = "fs-collection", | |
| }; | |
| auto fs = fs_management::Mount(std::move(device_fd), fs_management::kDiskFormatMinfs, options); | |
| ASSERT_EQ(fs.status(), ZX_OK); | |
| auto data = fs->DataRoot(); | |
| ASSERT_EQ(data.status(), ZX_OK); | |
| auto binding = fs_management::NamespaceBinding::Create("/fs", std::move(*data)); | |
| ASSERT_EQ(binding.status(), ZX_OK); | |
| // Now /fs points at the root of the filesystem. | |
| ``` | |
| ## Launching a filesystem as a process | |
| This section has a detailed description of how fs_management launches platform filesystem | |
| processes. It's intended for filesystem developers - if you just want to mount a filesystem, in | |
| code, see the previous section. | |
| Platform filesystem processes take 2 startup handles and a handful of command line arguments. The | |
| two startup handles are the server end of the export directory (`PA_DIRECTORY_REQUEST`), and a | |
| handle to the block device (`PA_HND(PA_USER0, 1)`). | |
| The export directory should have the structure described at the beginning of this document. | |
| The block device should be a handle to something that speaks `fuchsia.storage.block.Block`. | |
| Filesystems can use protocols from their namespace, but they should fail gracefully if they are not | |
| there. This is because many test environments don't construct consistent namespaces for the | |
| filesystems they run. The most common production environment is fshost, which copies all it's | |
| services to filesystems it launches, so using anything it uses in it's cml is probably fine. | |
| ## Launching a filesystem as a component | |
| This section has a detailed description of how fs_management launches platform filesystem | |
| components. It's intended for filesystem developers - if you just want to mount a filesystem, in | |
| code, see the previous section. | |
| There is currently one filesystem that supports being launched as a component, blobfs. The cml file | |
| for blobfs is in //src/storage/blobfs/bin-component/meta/blobfs.cml. | |
| When a filesystem component is launched, it starts in a partially configured state. They serve one | |
| protocol - `fuchsia.fs.startup.Startup`. This is served from the path | |
| `/<fs_component>/svc/fuchsia.fs.startup.Startup`. Filesystems need two things to run - a set of | |
| options and a block device handle. This protocol provides methods for `Start`, as well as `Format` | |
| and `Check`, which take the block device and a set of options as arguments. | |
| `Start` returns once the filesystem is launched. Before this point, it's expected that filesystems | |
| queue incoming open requests to be processed once `Start` is called. In blobfs, this is done by | |
| selectively calling Serve on parts of the export directory at a time. If a `Start` call fails, | |
| fs_management will attempt to destroy and restart the lifecycle component. | |
| Filesystems that are launched as components are also expected to consume an extra startup handle, | |
| PA_LIFECYCLE. This handle is the server end of a fuchsia.process.lifecycle.Lifecycle protocol, | |
| which the component framework can use to send shutdown requests. |