blobfs

Enumerations

enum class Writability

Name	Value	Comments
ReadOnlyDisk	0	Do not write to persistent storage under any circumstances whatsoever.
ReadOnlyFilesystem	1	Do not allow users of the filesystem to mutate filesystem state. This state allows the journal to replay while initializing writeback.
Writable	2	Permit all operations.

Defined at line 17 of file ../../src/storage/blobfs/mount.h

enum class CompressionAlgorithm

Name	Value
kUncompressed	0
kChunked	1

Unique identifiers for each |Compressor|/|Decompressor| strategy.

Defined at line 18 of file ../../src/storage/blobfs/compression_settings.h

enum class BlobLayoutFormat : uint8_t

Name	Value	Comments
kDeprecatedPaddedMerkleTreeAtStart	0	THIS VALUE IS DEPRECATED. It is used only on Astro devices. It uses more space because of the additional padding to block-align the beginning blob data. Do not add new uses, it will be removed once Astro support is no longer needed. The "Padded Merkle Tree at Start" layout stores the Merkle tree in the padded format at the start of the blob. The data is stored at the start of the block following the Merkle tree. \| block 001 \| block 002 \| block 003 \| block 004 \| block 005 \| ... \| block 579 \| block 580 \| \| < - Padded Merkle Tree ->\| < - Data ->\| This is the layout format that was in use prior to the layout format being added to the superblock. The new field was added to a section of the superblock that was already zero and to maintain backwards compatibility this enum value has the value zero.
kCompactMerkleTreeAtEnd	1	The "Compact Merkle Tree at End" layout stores the data at the start of the blob. The Merkle tree is stored in the compact format after the data and aligned so it ends at the end of the blob. The Merkle tree and the data may share a block. \| block 001 \| block 002 \| ... \| block 576 \| block 577 \| block 578 \| block 579 \| \| < - Data ->\| \| < - Compact Merkle Tree ->\|

Name

Value

Comments

kDeprecatedPaddedMerkleTreeAtStart

THIS VALUE IS DEPRECATED. It is used only on Astro devices. It uses more space because of the
additional padding to block-align the beginning blob data. Do not add new uses, it will be
removed once Astro support is no longer needed.

The "Padded Merkle Tree at Start" layout stores the Merkle tree in the padded format at the
start of the blob. The data is stored at the start of the block following the Merkle tree.
| block 001 | block 002 | block 003 | block 004 | block 005 | ... | block 579 | block 580 |
|
<
- Padded Merkle Tree ->|
<
- Data ->|
This is the layout format that was in use prior to the layout format being added to the
superblock. The new field was added to a section of the superblock that was already zero and
to maintain backwards compatibility this enum value has the value zero.

kCompactMerkleTreeAtEnd

Possible formats for how a blob can be laid out in storage.

This enum is serialized and stored in blobfs's superblock which prevents the enum values from

being changed.

Defined at line 19 of file ../../src/storage/blobfs/blob_layout.h

enum class EnqueueType

Name	Value
kJournal	0
kData	1

EnqueueType describes the classes of data which may be enqueued to the underlying storage medium.

Defined at line 21 of file ../../src/storage/blobfs/transaction_manager.h

enum class DeliveryBlobType : uint32_t

Name	Value	Comments
kReserved	0	Reserved for future use.
kType1	1	Type-1 blobs support the zstd-chunked compression format or are uncompressed.
kType2	2	Type-2 blobs are the same as Type-1 except that they specifically use zstd compression level 21 and chunk sizes of 128KiB.

Type of the delivery blob's metadata/payload. Corresponds to the `--type` argument used to

generate the blob with the `blobfs-compression` tool.

*WARNING*: The underlying values of these fields form are used in external tools when generating

delivery blobs as per RFC 0207. Use caution when changing or re-using the values specified here.

Defined at line 30 of file ../../src/storage/blobfs/delivery_blob.h

enum class PagerErrorStatus : zx_status_t

Name	Value	Comments
kErrIO	ZX_ERR_IO	--
kErrDataIntegrity	ZX_ERR_IO_DATA_INTEGRITY	--
kErrBadState	ZX_ERR_BAD_STATE	--
kOK	ZX_OK	This value is not supported by zx_pager_op_range(). Instead, it is used to determine if the zx_pager_op_range() call is required in the first place - PagerErrorStatus::kOK indicates no error, so we don't make the call.

Wrapper enum for error codes supported by the zx_pager_op_range(ZX_PAGER_OP_FAIL) syscall, used

to communicate userpager errors to the kernel, so that the error can be propagated to the

originator of the page request (if required), and the waiting thread can be unblocked. We use

this wrapper enum instead of a raw zx_status_t as not all error codes are supported.

Defined at line 42 of file ../../src/storage/blobfs/page_loader.h

enum class BlobState : uint8_t

Name	Value	Comments
kEmpty	0	After open.
kDataWrite	1	After space reserved (but allocation not yet persisted).
kReadable	2	After writing.
kPurged	3	After unlink.
kError	4	Unrecoverable error state.

Defined at line 46 of file ../../src/storage/blobfs/blob.h

enum class BlobOverwriteConfig : uint8_t

Name	Value
kNoOverwrite	0
kOverwriteToCompact	1
kOverwriteToPadded	2

Defined at line 66 of file ../../src/storage/blobfs/blobfs.h

Records

Functions

```
zx_status_t Fsck (Blobfs * blobfs)
```
Defined at line 15 of file ../../src/storage/blobfs/fsck_host.cc
```
zx_status_t Fsck (std::unique_ptr<block_client::BlockDevice> device, const MountOptions & options)
```
To run Fsck we mount Blobfs on the given BlockDevice. This requires a dispatcher. This function

may be called in different contexts where there might not be an easily known dispatcher or none

set up.

To make this uniform from the caller's perspective, Blobfs is run on a new thread with a

dedicated dispatcher.

Defined at line 34 of file ../../src/storage/blobfs/fsck.cc
```
const char * CompressionAlgorithmToString (CompressionAlgorithm )
```
Defined at line 20 of file ../../src/storage/blobfs/compression_settings.cc
```
zx::result<CompressionAlgorithm> AlgorithmForInode (const Inode & inode)
```
Returns the compression algorithm used in |inode|.

Defined at line 32 of file ../../src/storage/blobfs/compression_settings.cc

template <typename T, typename U>

int StreamAll (T func, int fd, U * buf, size_t max)

Defined at line 40 of file ../../src/storage/blobfs/test/blob_utils.h

```
uint16_t CompressionInodeHeaderFlags (CompressionAlgorithm algorithm)
```
Return an Inode header flagset with the flags associated with |algorithm| set, and all other

flags are unset.

Defined at line 46 of file ../../src/storage/blobfs/compression_settings.cc
```
zx::result<> StartComponent (ComponentOptions options, fidl::ServerEnd<fuchsia_io::Directory> root, fidl::ServerEnd<fuchsia_process_lifecycle::Lifecycle> lifecycle)
```
Start blobfs as a component. Begin serving requests on the provided |root|. Initially it starts

the filesystem in an unconfigured state, only serving the fuchsia.fs.Startup protocol. Once

fuchsia.fs.Startup/Start is called with the block device and mount options, the filesystem is

started with that configuration and begins serving requests to other protocols, including the

actual root of the filesystem at /root.

Also expects a lifecycle server end over which to serve fuchsia.process.lifecycle/Lifecycle for

shutting down the blobfs component.

This function blocks until the filesystem terminates.

Defined at line 25 of file ../../src/storage/blobfs/mount.cc
```
FilesystemOptions DefaultFilesystemOptions ()
```
Defined at line 31 of file ../../src/storage/blobfs/test/blobfs_test_setup.h
```
zx_status_t IterateToBlock (BlockIterator * iter, uint64_t block_num)
```
IterateToBlock is a utility function which moves the iterator to block number |block_num|.

Used by the blobfs pager to navigate to an arbitrary offset within a blob.

NOTE: This can only move the iterator forward relative to the current position.

Defined at line 49 of file ../../src/storage/blobfs/iterator/block_iterator.cc
```
PagerErrorStatus ToPagerErrorStatus (zx_status_t status)
```
Defined at line 52 of file ../../src/storage/blobfs/page_loader.h
```
zx_status_t FormatFilesystem (block_client::BlockDevice * device, const FilesystemOptions & options)
```
Formats the underlying device with an empty Blobfs partition.

Defined at line 290 of file ../../src/storage/blobfs/mkfs.cc
```
void SetCompressionAlgorithm (Inode * inode, CompressionAlgorithm algorithm)
```
Clear any existing compression flags and apply the new one.

Defined at line 58 of file ../../src/storage/blobfs/compression_settings.cc
```
const char * BlobLayoutFormatToString (BlobLayoutFormat format)
```
Returns enum name for |format|.

Defined at line 247 of file ../../src/storage/blobfs/blob_layout.cc
```
bool ShouldUseCompactMerkleTreeFormat (BlobLayoutFormat format)
```
Returns whether |format| uses the compact Merkle tree format or not.

Defined at line 256 of file ../../src/storage/blobfs/blob_layout.cc
```
zx::result<chunked_compression::CompressionParams> GetChunkedCompressionParamsForType (DeliveryBlobType type, size_t input_size)
```
Returns the chunked compression params used for the given blob type and blob size. If the type

does not use ChunkedCompression, this will return an error.

Defined at line 186 of file ../../src/storage/blobfs/delivery_blob.cc
```
zx_status_t CheckSuperblock (const Superblock * info, uint64_t max, bool quiet)
```
Validate the metadata for the superblock, given a maximum number of available blocks.

Defined at line 66 of file ../../src/storage/blobfs/common.cc

zx_status_t StreamBlocks (BlockIterator * iterator, uint64_t block_count, StreamFn stream)

Defined at line 65 of file ../../src/storage/blobfs/iterator/block_iterator.cc

```
bool VerifyContents (const zx::vmo & blob_vmo, std::span<const uint8_t> expected_data)
```
Verifies that a vmo contains the data in the provided buffer.

Defined at line 82 of file ../../src/storage/blobfs/test/blob_utils.cc

zx_status_t VerifyTailZeroed (const void * data, size_t data_size, size_t buffer_size)

Defined at line 92 of file ../../src/storage/blobfs/blob_verifier.cc

```
uint64_t BlocksRequiredForInode (uint64_t inode_count)
```
Returns number of blocks required for inode_count inodes

Defined at line 197 of file ../../src/storage/blobfs/common.cc
```
uint64_t GetVmoSize (const zx::vmo & vmo)
```
The the stream size of a VMO.

Defined at line 95 of file ../../src/storage/blobfs/test/blob_utils.cc
```
uint64_t BlocksRequiredForBits (uint64_t bit_count)
```
Returns number of blocks required for bit_count bits

Defined at line 201 of file ../../src/storage/blobfs/common.cc
```
uint64_t GetVmoStreamSize (const zx::vmo & vmo)
```
The the stream size of a VMO.

Defined at line 101 of file ../../src/storage/blobfs/test/blob_utils.cc
```
std::string GetBlobLayoutFormatNameForTests (BlobLayoutFormat format)
```
Returns the name of |format| for use in parameterized tests.

Defined at line 107 of file ../../src/storage/blobfs/test/blob_utils.cc
```
void InitializeSuperblockOptions (const FilesystemOptions & options, Superblock * info)
```
Calling this method will initialize the superblock's common fields with non-fvm values but leave

all of the size-related fields set to zero. It is the caller's responsibility to set the

size-related and fvm-specific fields to appropriate values.

Defined at line 205 of file ../../src/storage/blobfs/common.cc
```
zx_status_t CheckFvmConsistency (const Superblock * info, BlockDevice * device, bool repair)
```
Validate that the contents of the superblock matches the results claimed in the underlying

volume manager.

If the results are inconsistent, update the FVM's allocation accordingly.

Defined at line 202 of file ../../src/storage/blobfs/blobfs_checker.cc
```
zx_status_t InitializeSuperblock (uint64_t block_count, const FilesystemOptions & options, Superblock * info)
```
Creates a superblock, formatted for |block_count| disk blocks on a non-FVM volume. Calls

|InitializeSuperblockOptions|. Returns ZX_ERR_NO_SPACE if there is not enough blocks to make a

minimal partition.

Defined at line 217 of file ../../src/storage/blobfs/common.cc
```
BlobLayoutFormat GetBlobLayoutFormat (const Superblock & info, const Inode & inode)
```
Returns the blob layout format that was used to store the contents of `inode`. |CheckSuperblock|

should be used to validate |info| before trying to access the blob layout format.

Defined at line 248 of file ../../src/storage/blobfs/common.cc
```
void SetDeadlineProfile (const std::vector<zx::unowned_thread> & threads)
```
Applies the scheduling deadline profile to the given pager thread.

Defined at line 141 of file ../../src/storage/blobfs/page_loader.cc
```
fs_test::TestFilesystemOptions BlobfsDefaultTestParam ()
```
Different blobfs settings to use with |ParameterizedBlobfsTest|.

Defined at line 93 of file ../../src/storage/blobfs/test/integration/blobfs_fixtures.cc
```
fs_test::TestFilesystemOptions BlobfsWithFvmTestParam ()
```
Defined at line 99 of file ../../src/storage/blobfs/test/integration/blobfs_fixtures.cc
```
std::ostream & operator<< (std::ostream & stream, const Superblock & info)
```
Pretty-print formatter for Blobfs Superblock fields.

Defined at line 48 of file ../../src/storage/blobfs/common.cc
```
fs_test::TestFilesystemOptions BlobfsWithPaddedLayoutTestParam ()
```
Defined at line 105 of file ../../src/storage/blobfs/test/integration/blobfs_fixtures.cc
```
fs_test::TestFilesystemOptions BlobfsWithFixedDiskSizeTestParam (uint64_t disk_size)
```
Defined at line 112 of file ../../src/storage/blobfs/test/integration/blobfs_fixtures.cc
```
void InitializeAllocator (size_t blocks, size_t nodes, MockSpaceManager * space_manager, std::unique_ptr<Allocator> * out)
```
Create a block and node map of the requested size, update the superblock of

the |space_manager|, and create an allocator from this provided info.

Defined at line 98 of file ../../src/storage/blobfs/test/unit/utils.cc
```
void ForceFragmentation (Allocator * allocator, size_t blocks)
```
Force the allocator to become maximally fragmented by allocating

every-other block within up to |blocks|.

Defined at line 116 of file ../../src/storage/blobfs/test/unit/utils.cc
```
void CopyExtents (const std::vector<ReservedExtent> & in, std::vector<Extent> * out)
```
Save the extents within |in| in a non-reserved vector |out|.

Defined at line 129 of file ../../src/storage/blobfs/test/unit/utils.cc
```
void CopyNodes (const std::vector<ReservedNode> & in, std::vector<uint32_t> * out)
```
Save the nodes within |in| in a non-reserved vector |out|.

Defined at line 137 of file ../../src/storage/blobfs/test/unit/utils.cc
```
void DeviceBlockRead (BlockDevice * device, void * buf, size_t size, uint64_t dev_offset)
```
Reads |size| bytes from the |device| at byte offset |dev_offset| into |buf|.

Expects |size| and |dev_offset| to be multiple of |device| block size.

Defined at line 144 of file ../../src/storage/blobfs/test/unit/utils.cc
```
void DeviceBlockWrite (BlockDevice * device, const void * buf, size_t size, uint64_t dev_offset)
```
Writes |size| bytes from the |buf| to the |device| at offset |dev_offset|.

Expects |size| and |dev_offset| to be multiple of |device| block size.

Defined at line 163 of file ../../src/storage/blobfs/test/unit/utils.cc
```
uint64_t SuperblockBlocks (const Superblock & info)
```
Defined at line 180 of file ../../src/storage/blobfs/format.h
```
uint64_t BlockMapStartBlock (const Superblock & info)
```
Defined at line 182 of file ../../src/storage/blobfs/format.h

std::string GetCompressionAlgorithmName (CompressionAlgorithm compression_algorithm)

Defined at line 182 of file ../../src/storage/blobfs/test/unit/utils.cc

```
zx::result<> VerifyNullBlob (Blobfs & blobfs, const Digest & digest)
```
Verifies the integrity of the null blob (i.e. that |digest| is correct). On failure, the |blobfs|

metrics and corruption notifier will be updated accordingly.

Defined at line 48 of file ../../src/storage/blobfs/blob.cc
```
uint64_t BlockMapBlocks (const Superblock & info)
```
Defined at line 190 of file ../../src/storage/blobfs/format.h
```
uint64_t NodeMapStartBlock (const Superblock & info)
```
Defined at line 194 of file ../../src/storage/blobfs/format.h
```
uint64_t NodeBitmapBlocks (const Superblock & info)
```
Defined at line 204 of file ../../src/storage/blobfs/format.h
```
uint64_t NodeMapBlocks (const Superblock & info)
```
Defined at line 208 of file ../../src/storage/blobfs/format.h
```
uint64_t JournalStartBlock (const Superblock & info)
```
Defined at line 212 of file ../../src/storage/blobfs/format.h
```
uint64_t JournalBlocks (const Superblock & info)
```
Defined at line 221 of file ../../src/storage/blobfs/format.h
```
uint64_t DataStartBlock (const Superblock & info)
```
Defined at line 223 of file ../../src/storage/blobfs/format.h
```
uint64_t DataBlocks (const Superblock & info)
```
Defined at line 232 of file ../../src/storage/blobfs/format.h
```
uint64_t TotalNonDataBlocks (const Superblock & info)
```
Defined at line 234 of file ../../src/storage/blobfs/format.h
```
uint64_t TotalBlocks (const Superblock & info)
```
Defined at line 238 of file ../../src/storage/blobfs/format.h
```
BlobLayoutFormat GetDefaultBlobLayoutFormat (const Superblock & info)
```
The default format to use for this filesystem based on superblock fields.

Defined at line 261 of file ../../src/storage/blobfs/common.cc
```
void SetBlobLayoutFormat (Inode * inode, BlobLayoutFormat blob_layout_format)
```
Stores the `blob_layout_format` inside of the Inode.

Defined at line 274 of file ../../src/storage/blobfs/common.cc
```
zx::result<fbl::Array<uint8_t>> GenerateDeliveryBlobWithType (DeliveryBlobType type, std::span<const uint8_t> data, std::optional<bool> compress)
```
Generate a specific type of delivery blob payload from the given blob `data`.

If `compress` is not specified, the result will be uncompressed if the compressed data is larger

than the input. If `compress` is true, the result will always be compressed, and if false, will

always be uncompressed.

*WARNING*: Modifying the compression parameters used by this function can cause a mismatch

between the calculated on-disk size used for size checking. This function is used to calculate

`compressed_file_size` in the blob info JSON file.

Defined at line 204 of file ../../src/storage/blobfs/delivery_blob.cc
```
zx::result<digest::Digest> CalculateDeliveryBlobDigest (std::span<const uint8_t> data)
```
Calculate the Merkle root of an RFC 0207 compliant delivery blob. `data` must be a complete

delivery blob and cannot include any trailing data.

*WARNING*: Aside from checksum verification and basic validity checks provided by the

chunked_compression library, this function makes no security guarantees. Decompression is

performed in the thread/address space of the caller.

Defined at line 246 of file ../../src/storage/blobfs/delivery_blob.cc
```
std::ostream & operator<< (std::ostream & stream, const Extent & extent)
```
This is inlined because format.cc only compiles on Fuchsia builds (not host).

Defined at line 294 of file ../../src/storage/blobfs/format.h
```
VmoNameBuffer FormatBlobDataVmoName (const Digest & digest)
```
Defined at line 298 of file ../../src/storage/blobfs/common.cc

template <size_t N>

std::ostream & operator<< (std::ostream & stream, const Extent (&)[N] extents)

Defined at line 300 of file ../../src/storage/blobfs/format.h

VmoNameBuffer FormatInactiveBlobDataVmoName (const Digest & digest)

Defined at line 302 of file ../../src/storage/blobfs/common.cc

VmoNameBuffer FormatWritingBlobDataVmoName (const Digest & digest)

Defined at line 306 of file ../../src/storage/blobfs/common.cc

```
zx_status_t ReadBlock (int fd, uint64_t block_number, void * data)
```
Reads block |block_number| into |data| from |fd|.

Defined at line 314 of file ../../src/storage/blobfs/host.cc
```
std::ostream & operator<< (std::ostream & stream, const NodePrelude & prelude)
```
This is inlined because format.cc only compiles on Fuchsia builds (not host).

Defined at line 368 of file ../../src/storage/blobfs/format.h
```
zx::result<fbl::RefPtr<Blob>> CreateBlob (Blobfs & blobfs, const TestDeliveryBlob & delivery_blob)
```
Creates a new blob in `blobfs` with the contents of `delivery_blob`. The returned blob will be in

the same state as if it had just been written by `BlobWriter`.

Defined at line 383 of file ../../src/storage/blobfs/test/blob_utils.cc
```
zx_status_t GetBlockCount (int fd, uint64_t * out)
```
Returns the number of blobfs blocks that fit in |fd|.

Defined at line 318 of file ../../src/storage/blobfs/host.cc
```
std::ostream & operator<< (std::ostream & stream, const Inode & inode)
```
This is inlined because format.cc only compiles on Fuchsia builds (not host).

Defined at line 406 of file ../../src/storage/blobfs/format.h
```
zx::result<fbl::RefPtr<Blob>> GetBlob (Blobfs & blobfs, const Digest & digest)
```
Retrieve a blob in `blobfs` with the digest `digest`.

Defined at line 406 of file ../../src/storage/blobfs/test/blob_utils.cc
```
int Mkfs (int fd, uint64_t block_count, const FilesystemOptions & options)
```
Formats a blobfs filesystem, meant to contain |block_count| blobfs blocks, to the device

represented by |fd|.

Returns -1 on error, 0 on success.

Defined at line 327 of file ../../src/storage/blobfs/host.cc
```
zx_status_t UsedDataSize (const fbl::unique_fd & fd, uint64_t * out_size)
```
Copies into |out_size| the number of bytes used by data in a blobfs partition contained in |fd|.

blobfs is assumed to start at offset 0 in the provided file handle.

Defined at line 402 of file ../../src/storage/blobfs/host.cc
```
zx_status_t UsedInodes (const fbl::unique_fd & fd, uint64_t * out_inodes)
```
Copies into |out_inodes| the number of allocated inodes in a blobfs partition contained in |fd|.

blobfs is assumed to start at offset 0 in the provided file handle.

Defined at line 412 of file ../../src/storage/blobfs/host.cc
```
zx_status_t UsedSize (const fbl::unique_fd & fd, uint64_t * out_size)
```
Copies into |out_size| the number of bytes used by data and bytes reserved for superblock,

bitmaps, inodes and journal for a blobfs partition contained in |fd|.

blobfs is assumed to start at offset 0 in the provided file handle.

Defined at line 422 of file ../../src/storage/blobfs/host.cc
```
std::ostream & operator<< (std::ostream & stream, const ExtentContainer & container)
```
This is inlined because format.cc only compiles on Fuchsia builds (not host).

Defined at line 425 of file ../../src/storage/blobfs/format.h

zx_status_t blobfs_create (std::unique_ptr<Blobfs> * out, fbl::unique_fd blockfd)

Defined at line 432 of file ../../src/storage/blobfs/host.cc

zx_status_t blobfs_fsck (fbl::unique_fd fd, const std::vector<size_t> & extent_lengths)

Defined at line 501 of file ../../src/storage/blobfs/host.cc

```
zx_status_t blobfs_create_sparse (std::unique_ptr<Blobfs> * out, fbl::unique_fd fd, const std::vector<size_t> & extent_vector)
```
Create a blobfs from a sparse file.

|start| indicates where the blobfs partition starts within the file (in bytes).

|end| indicates the end of the blobfs partition (in bytes).

|extent_lengths| contains the length (in bytes) of each blobfs extent: currently this includes

the superblock, block bitmap, inode table, and data blocks.

Defined at line 471 of file ../../src/storage/blobfs/host.cc
```
fpromise::result<void, std::string> ExportBlobs (int output_dir, Blobfs & fs)
```
Write each blob contained in this image into |output_dir| as a standalone file, with the merkle

root hash as the filename.

Defined at line 961 of file ../../src/storage/blobfs/host.cc