fuchsia.paver

PROTOCOLS

PayloadStream

Defined in fuchsia.paver/paver.fidl

Protocol for streaming the FVM payload.

RegisterVmo

Registers a VMO to stream into.

Request

NameType
vmo handle<vmo>

Response

NameType
status zx/status

ReadData

Reads data into the pre-registered vmo.

Request

NameType

Response

NameType
result ReadResult

Paver

Defined in fuchsia.paver/paver.fidl

FindDataSink

Attempts to auto-discover the data sink where assets and volumes will get paved to. On devices with GPT, the partition must have a valid FVM partition in order for auto-discovery to find it. If multiple devices are found suitable, error is returned.

|data_sink| will be closed on error, with an epitaph provided on failure reason.

Request

NameType
data_sink request<DataSink>

UseBlockDevice

Provide a block device to use as a data sink. Assets and volumes will be paved to partitions within this block device.

It assumes that channel backing |block_device| also implements fuchsia.io.Node for now.

|data_sink| will be closed on error, with an epitaph provided on failure reason.

Request

NameType
block_device request<fuchsia.hardware.block/Block>
data_sink request<DynamicDataSink>

FindBootManager

Attempts to auto-discover the boot manager.

|initialize| should only be set to true to initialize ABR metadata for the first time (i.e. it should not be called every boot), or recover from corrupted ABR metadata.

|boot_manager| will be closed on error, with an epitaph provided on failure reason. ZX_ERR_NOT_SUPPORTED indicates lack of support and configuration A is always booted from.

Request

NameType
boot_manager request<BootManager>
initialize bool

DataSink

Defined in fuchsia.paver/paver.fidl

Protocol for reading and writing boot partitions.

ReadAsset

Reads partition corresponding to |configuration| and |asset| into a vmo and returns it.

Request

NameType
configuration Configuration
asset Asset

Response

NameType
result DataSink_ReadAsset_Result

WriteAsset

Writes partition corresponding to configuration and asset with data from payload. payload may need to be resized to the partition size, so the provided vmo must have been created with ZX_VMO_RESIZABLE or must be a child VMO that was created with ZX_VMO_CHILD_RESIZABLE. Will zero out rest of the partition if payload is smaller than the size of the partition being written.

Returns ZX_ERR_INVALID_ARGS if configuration specifies active configuration.

Request

NameType
configuration Configuration
asset Asset
payload fuchsia.mem/Buffer

Response

NameType
status zx/status

WriteVolumes

Writes FVM with data from streamed via payload. This potentially affects all configurations.

Request

NameType
payload request<PayloadStream>

Response

NameType
status zx/status

WriteBootloader

Writes bootloader partition with data from payload.

payload may need to be resized to the partition size, so the provided vmo must have been created with ZX_VMO_RESIZABLE or must be a child VMO that was created with ZX_VMO_CHILD_RESIZABLE.

Request

NameType
payload fuchsia.mem/Buffer

Response

NameType
status zx/status

WriteDataFile

Writes /data/filename with data from payload. Overwrites file if it already exists.

Request

NameType
filename string[4096]
payload fuchsia.mem/Buffer

Response

NameType
status zx/status

WipeVolume

Wipes the FVM partition from the device. Should not be confused with factory reset, which is less intrusive. The result is that the default FVM volumes are re-created, but empty.

Notable use cases include recovering from corrupted FVM as well as setting device to a "clean" state for automation.

If |block_device| is not provided, the paver will perform a search for the the FVM. If multiple block devices have valid GPT, |block_device| can be provided to specify which one to target. It assumed that channel backing |block_device| also implements fuchsia.io.Node for now.

On success, returns a channel to the initialized FVM volume.

Request

NameType

Response

NameType
result DataSink_WipeVolume_Result

DynamicDataSink

Defined in fuchsia.paver/paver.fidl

Specialized DataSink with dynamic partition tables.

ReadAsset

Reads partition corresponding to |configuration| and |asset| into a vmo and returns it.

Request

NameType
configuration Configuration
asset Asset

Response

NameType
result DataSink_ReadAsset_Result

WriteAsset

Writes partition corresponding to configuration and asset with data from payload. payload may need to be resized to the partition size, so the provided vmo must have been created with ZX_VMO_RESIZABLE or must be a child VMO that was created with ZX_VMO_CHILD_RESIZABLE. Will zero out rest of the partition if payload is smaller than the size of the partition being written.

Returns ZX_ERR_INVALID_ARGS if configuration specifies active configuration.

Request

NameType
configuration Configuration
asset Asset
payload fuchsia.mem/Buffer

Response

NameType
status zx/status

WriteVolumes

Writes FVM with data from streamed via payload. This potentially affects all configurations.

Request

NameType
payload request<PayloadStream>

Response

NameType
status zx/status

WriteBootloader

Writes bootloader partition with data from payload.

payload may need to be resized to the partition size, so the provided vmo must have been created with ZX_VMO_RESIZABLE or must be a child VMO that was created with ZX_VMO_CHILD_RESIZABLE.

Request

NameType
payload fuchsia.mem/Buffer

Response

NameType
status zx/status

WriteDataFile

Writes /data/filename with data from payload. Overwrites file if it already exists.

Request

NameType
filename string[4096]
payload fuchsia.mem/Buffer

Response

NameType
status zx/status

WipeVolume

Wipes the FVM partition from the device. Should not be confused with factory reset, which is less intrusive. The result is that the default FVM volumes are re-created, but empty.

Notable use cases include recovering from corrupted FVM as well as setting device to a "clean" state for automation.

If |block_device| is not provided, the paver will perform a search for the the FVM. If multiple block devices have valid GPT, |block_device| can be provided to specify which one to target. It assumed that channel backing |block_device| also implements fuchsia.io.Node for now.

On success, returns a channel to the initialized FVM volume.

Request

NameType

Response

NameType
result DataSink_WipeVolume_Result

InitializePartitionTables

Initializes partitions on given block device.

Request

NameType

Response

NameType
status zx/status

WipePartitionTables

Wipes all entries from the partition table of the specified block device. Currently only supported on devices with a GPT.

WARNING: This API may destructively remove non-fuchsia maintained partitions from the block device.

Request

NameType

Response

NameType
status zx/status

BootManager

Defined in fuchsia.paver/paver.fidl

Protocol for managing boot configurations.

QueryActiveConfiguration

Queries active configuration.

Request

NameType

Response

NameType
result BootManager_QueryActiveConfiguration_Result

QueryConfigurationStatus

Queries status of |configuration|.

Returns ZX_ERR_INVALID_ARGS if Configuration.RECOVERY is passed in via |configuration|.

Request

NameType
configuration Configuration

Response

NameType
result BootManager_QueryConfigurationStatus_Result

SetConfigurationActive

Updates persistent metadata identifying which configuration should be selected as 'primary' for booting purposes. Should only be called after KERNEL as well as optional VERIFIED_BOOT_METADATA assets for specified configuration were written successfully.

Returns ZX_ERR_INVALID_ARGS if Configuration.RECOVERY is passed in via |configuration|.

Request

NameType
configuration Configuration

Response

NameType
status zx/status

SetConfigurationUnbootable

Updates persistent metadata identifying whether |configuration| is bootable. Should only be called in the following situations:

  • Before KERNEL as well as optional VERIFIED_BOOT_METADATA assets for specified |configuration| are written.
  • After successfully booting from a new configuration and marking it healthy. This method would be then called on the old configuration.
  • After "successfully" booting from a new configuration, but encountering an unrecoverable error during health check. This method would be then called on the new configuration.

If the configuration is unbootable, no action is taken.

Returns ZX_ERR_INVALID_ARGS if Configuration.RECOVERY is passed in via |configuration|.

Request

NameType
configuration Configuration

Response

NameType
status zx/status

SetActiveConfigurationHealthy

Updates persistent metadata identifying that active configuration is stable. Used to signal "rollback to previous slot" logic is not needed anymore. Meant to be called in subsequent boot attempt after SetActiveConfiguration was called. Will return error if active configuration is currently unbootable.

If the configuration is already marked healthy, no action is taken.

Request

NameType

Response

NameType
status zx/status

STRUCTS

SomeLongAnonymousPrefix0

generated

anonymous struct

NameTypeDescriptionDefault
vmo handle<vmo> No default

SomeLongAnonymousPrefix1

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

SomeLongAnonymousPrefix3

generated

anonymous struct

NameTypeDescriptionDefault
result ReadResult No default

SomeLongAnonymousPrefix4

generated

anonymous struct

NameTypeDescriptionDefault
data_sink request<DataSink> No default

SomeLongAnonymousPrefix5

generated

anonymous struct

NameTypeDescriptionDefault
block_device request<fuchsia.hardware.block/Block> No default
data_sink request<DynamicDataSink> No default

SomeLongAnonymousPrefix6

generated

anonymous struct

NameTypeDescriptionDefault
boot_manager request<BootManager> No default
initialize bool No default

SomeLongAnonymousPrefix7

generated

anonymous struct

NameTypeDescriptionDefault
configuration Configuration No default
asset Asset No default

DataSink_ReadAsset_Response

generated

NameTypeDescriptionDefault
asset fuchsia.mem/Buffer No default

SomeLongAnonymousPrefix8

generated

anonymous struct

NameTypeDescriptionDefault
result DataSink_ReadAsset_Result No default

SomeLongAnonymousPrefix9

generated

anonymous struct

NameTypeDescriptionDefault
configuration Configuration No default
asset Asset No default
payload fuchsia.mem/Buffer No default

SomeLongAnonymousPrefix10

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

SomeLongAnonymousPrefix11

generated

anonymous struct

NameTypeDescriptionDefault
payload request<PayloadStream> No default

SomeLongAnonymousPrefix12

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

SomeLongAnonymousPrefix13

generated

anonymous struct

NameTypeDescriptionDefault
payload fuchsia.mem/Buffer No default

SomeLongAnonymousPrefix14

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

SomeLongAnonymousPrefix15

generated

anonymous struct

NameTypeDescriptionDefault
filename string[4096] No default
payload fuchsia.mem/Buffer No default

SomeLongAnonymousPrefix16

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

DataSink_WipeVolume_Response

generated

NameTypeDescriptionDefault
volume request<fuchsia.hardware.block.volume/VolumeManager> No default

SomeLongAnonymousPrefix18

generated

anonymous struct

NameTypeDescriptionDefault
result DataSink_WipeVolume_Result No default

SomeLongAnonymousPrefix20

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

SomeLongAnonymousPrefix22

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

BootManager_QueryActiveConfiguration_Response

generated

NameTypeDescriptionDefault
configuration Configuration No default

SomeLongAnonymousPrefix24

generated

anonymous struct

NameTypeDescriptionDefault
result BootManager_QueryActiveConfiguration_Result No default

SomeLongAnonymousPrefix25

generated

anonymous struct

NameTypeDescriptionDefault
configuration Configuration No default

BootManager_QueryConfigurationStatus_Response

generated

NameTypeDescriptionDefault
status ConfigurationStatus No default

SomeLongAnonymousPrefix26

generated

anonymous struct

NameTypeDescriptionDefault
result BootManager_QueryConfigurationStatus_Result No default

SomeLongAnonymousPrefix27

generated

anonymous struct

NameTypeDescriptionDefault
configuration Configuration No default

SomeLongAnonymousPrefix28

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

SomeLongAnonymousPrefix29

generated

anonymous struct

NameTypeDescriptionDefault
configuration Configuration No default

SomeLongAnonymousPrefix30

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

SomeLongAnonymousPrefix32

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

ReadInfo

Defined in fuchsia.paver/paver.fidl

NameTypeDescriptionDefault
offset zx/off

Offset into VMO where read data starts.

No default
size uint64

Size of read data.

No default

SomeLongAnonymousPrefix7

generated

anonymous struct

NameTypeDescriptionDefault
configuration Configuration No default
asset Asset No default

SomeLongAnonymousPrefix8

generated

anonymous struct

NameTypeDescriptionDefault
result DataSink_ReadAsset_Result No default

SomeLongAnonymousPrefix9

generated

anonymous struct

NameTypeDescriptionDefault
configuration Configuration No default
asset Asset No default
payload fuchsia.mem/Buffer No default

SomeLongAnonymousPrefix10

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

SomeLongAnonymousPrefix11

generated

anonymous struct

NameTypeDescriptionDefault
payload request<PayloadStream> No default

SomeLongAnonymousPrefix12

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

SomeLongAnonymousPrefix13

generated

anonymous struct

NameTypeDescriptionDefault
payload fuchsia.mem/Buffer No default

SomeLongAnonymousPrefix14

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

SomeLongAnonymousPrefix15

generated

anonymous struct

NameTypeDescriptionDefault
filename string[4096] No default
payload fuchsia.mem/Buffer No default

SomeLongAnonymousPrefix16

generated

anonymous struct

NameTypeDescriptionDefault
status zx/status No default

SomeLongAnonymousPrefix18

generated

anonymous struct

NameTypeDescriptionDefault
result DataSink_WipeVolume_Result No default

ENUMS

Configuration

Type: uint32

Defined in fuchsia.paver/paver.fidl

Describes the version of an asset.

NameValueDescription
A 1
B 2
RECOVERY 3

Asset

Type: uint32

Defined in fuchsia.paver/paver.fidl

Describes assets which may be updated. Each asset has 3 versions, each tied to a particular configuration.

NameValueDescription
KERNEL 1

Zircon Boot Image (ZBI) containing the kernel image as well as bootfs.

VERIFIED_BOOT_METADATA 2

Metadata used for verified boot purposes.

ConfigurationStatus

Type: uint32

Defined in fuchsia.paver/paver.fidl

Set of states configuration may be in.

NameValueDescription
HEALTHY 1

Bootable and health checked.

PENDING 2

Bootable but not yet marked healthy.

UNBOOTABLE 3

Unbootable.

UNIONS

DataSink_ReadAsset_Result

generated

NameTypeDescription
response DataSink_ReadAsset_Response
err zx/status

DataSink_WipeVolume_Result

generated

NameTypeDescription
response DataSink_WipeVolume_Response
err zx/status

BootManager_QueryActiveConfiguration_Result

generated

NameTypeDescription
response BootManager_QueryActiveConfiguration_Response
err zx/status

BootManager_QueryConfigurationStatus_Result

generated

NameTypeDescription
response BootManager_QueryConfigurationStatus_Response
err zx/status

ReadResult

Defined in fuchsia.paver/paver.fidl

NameTypeDescription
err zx/status

Error encountered while reading data.

eof bool

End of file reached.

info ReadInfo

Information about location of successfully read data within pre-registered VMO.