Google is committed to advancing racial equity for Black communities. See how.

fuchsia.paver

PROTOCOLS

BootManager

Defined in fuchsia.paver/paver.fidl

Protocol for managing boot configurations.

All functions will first check the A/B/R metadata and reset it to the default state if it's invalid. The new configuration is not guaranteed to persist to storage before Flush() is called.

Flush

Flush all previously buffered writes to persistent storage.

Request

<EMPTY>

Response

NameType
status zx/status

QueryActiveConfiguration

Queries the configuration which will be used as the default boot choice on a normal cold boot, which may differ from the currently running configuration. Configuration::RECOVERY should never be active.

Returns ZX_ERR_NOT_SUPPORTED if Configuration.RECOVERY is active.

Request

<EMPTY>

Response

NameType
result BootManager_QueryActiveConfiguration_Result

QueryConfigurationLastSetActive

Queries the configuration that was last explicitly marked as active by SetConfigurationActive(). The result is not affected by the current status of the slot.

A newly updated slot is typically marked as active immediately. Therefore this interface can be used as a way to identify the newest slot.

Returns ZX_ERR_IO if fail to load abr metadata. Returns ZX_ERR_INTERNAL if invalid slot index is returned by libabr routine.

Request

<EMPTY>

Response

NameType
result BootManager_QueryConfigurationLastSetActive_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

QueryCurrentConfiguration

Queries the configuration the system is currently running.

Returns ZX_ERR_NOT_SUPPORTED if the zvb.current_slot boot argument cannot be read or is an unexpected value.

Request

<EMPTY>

Response

NameType
result BootManager_QueryCurrentConfiguration_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

SetConfigurationHealthy

Updates persistent metadata to mark a fuchsia.paver/Configuration as successful.

This function is typically used by the OS update system after having confirmed that the configuration works as intended and the "rollback to previous slot" logic is not needed anymore.

Compatibility between the newly successful configuration and the other configuration is unknown. Even if the other configuration was successful at one point, it may no longer be. This function adds a success mark to the given configuration but also removes any success mark on the other.

If configuration is unbootable or is fuchsia.paver/Configuration.RECOVERY, response will be ZX_ERR_INVALID_ARGS.

  • request configuration the Configuration to mark as healthy. Must not be RECOVERY.
  • response status a zx_status value indicating success or failure.

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

DataSink

Defined in fuchsia.paver/paver.fidl

Protocol for reading and writing boot partitions.

A note on DataSink.Flush() (and BootManager.Flush() coming after):

Some platforms may implement the Flush() fidl interface of DataSink/BootManager. For these platforms, the update of some system images and A/B configuration is not persisted to storage immediately and only buffered internally when the write fidl interfaces return. The data is guaranteed to be persisted only after the Flush() interfaces are called.

If not implemented, Flush() is no-op and system images and A/B configuration will be persisted to storage immediately after the write fidl interfaces return.

For all platforms, it is guaranteed that if DataSink.Flush() is implemented, BootManager.Flush() is implemented as well. Therefore, in the context of system update, both of the following update sequences are safe in the sense that, new A/B configuration will not be persisted to storage before new system images. DataSink.Write... --> DataSink.Flush() --> BootManager.Set... --> BootManager.Flush() DataSink.Write... --> BootManager.Set... --> DataSink.Flush() --> BootManager.Flush()

Flush

Flush all previously buffered writes to persistent storage.

Request

<EMPTY>

Response

NameType
status zx/status

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

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

<EMPTY>

Response

NameType
result DataSink_WipeVolume_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

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.

DEPRECATED

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

WriteFirmware

Writes firmware data from payload.

configuration represents the A/B/R configuration. For platforms that do not support firmware A/B/R, the parameter will be ignored by the underlying device-specific logic .

type is a device-specific string identifying the payload contents, used to select the proper paving logic. For example, a device with multiple bootloader stages might send them as separate calls to WriteFirmware(), differentiated by type. An empty string indicates the default type.

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
configuration Configuration
type string[256]
payload fuchsia.mem/Buffer

Response

NameType
result WriteFirmwareResult

WriteVolumes

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

Request

NameType
payload PayloadStream

Response

NameType
status zx/status

DynamicDataSink

Defined in fuchsia.paver/paver.fidl

Specialized DataSink with dynamic partition tables.

Flush

Flush all previously buffered writes to persistent storage.

Request

<EMPTY>

Response

NameType
status zx/status

InitializePartitionTables

Initializes partitions on given block device.

Request

<EMPTY>

Response

NameType
status zx/status

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

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

<EMPTY>

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

<EMPTY>

Response

NameType
result DataSink_WipeVolume_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

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.

DEPRECATED

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

WriteFirmware

Writes firmware data from payload.

configuration represents the A/B/R configuration. For platforms that do not support firmware A/B/R, the parameter will be ignored by the underlying device-specific logic .

type is a device-specific string identifying the payload contents, used to select the proper paving logic. For example, a device with multiple bootloader stages might send them as separate calls to WriteFirmware(), differentiated by type. An empty string indicates the default type.

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
configuration Configuration
type string[256]
payload fuchsia.mem/Buffer

Response

NameType
result WriteFirmwareResult

WriteVolumes

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

Request

NameType
payload PayloadStream

Response

NameType
status zx/status

Paver

Defined in fuchsia.paver/paver.fidl

FindBootManager

Attempts to auto-discover the boot manager.

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>

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>

FindSysconfig

Find Sysconfig service.

Request

NameType
sysconfig request<Sysconfig>

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 fuchsia.hardware.block/Block
data_sink request<DynamicDataSink>

PayloadStream

Defined in fuchsia.paver/paver.fidl

Protocol for streaming the FVM payload.

ReadData

Reads data into the pre-registered vmo.

Request

<EMPTY>

Response

NameType
result ReadResult

RegisterVmo

Registers a VMO to stream into.

This can be called once per PayloadStream. Any subsequent calls will return ZX_ERR_ALREADY_BOUND.

Request

NameType
vmo handle<vmo>

Response

NameType
status zx/status

Sysconfig

Defined in fuchsia.paver/paver.fidl

Protocol that provides access to sysconfig-data sub-partition in sysconfig partition. The main user of the protocol are pkg-solver and system update-checker, which need to read/write sysconfig-data channel.

Flush

Flush all previously buffered data to persistent storage.

Request

<EMPTY>

Response

NameType
status zx/status

GetPartitionSize

Get sub-partition size.

Request

<EMPTY>

Response

NameType
result Sysconfig_GetPartitionSize_Result

Read

Read from the sub-partition

Request

<EMPTY>

Response

NameType
result Sysconfig_Read_Result

Wipe

Wipe all data in the sub-partition (write 0 to all bytes).

Request

<EMPTY>

Response

NameType
status zx/status

Write

Writes to the sub-partition

Request

NameType
payload fuchsia.mem/Buffer

Response

NameType
status zx/status

STRUCTS

BootManager_QueryActiveConfiguration_Response

Defined in fuchsia.paver/paver.fidl

FieldTypeDescriptionDefault
configuration Configuration No default

BootManager_QueryConfigurationLastSetActive_Response

Defined in fuchsia.paver/paver.fidl

FieldTypeDescriptionDefault
configuration Configuration No default

BootManager_QueryConfigurationStatus_Response

Defined in fuchsia.paver/paver.fidl

FieldTypeDescriptionDefault
status ConfigurationStatus No default

BootManager_QueryCurrentConfiguration_Response

Defined in fuchsia.paver/paver.fidl

FieldTypeDescriptionDefault
configuration Configuration No default

DataSink_ReadAsset_Response resource

Defined in fuchsia.paver/paver.fidl

FieldTypeDescriptionDefault
asset fuchsia.mem/Buffer No default

DataSink_WipeVolume_Response resource

Defined in fuchsia.paver/paver.fidl

FieldTypeDescriptionDefault
volume fuchsia.hardware.block.volume/VolumeManager No default

ReadInfo

Defined in fuchsia.paver/paver.fidl

FieldTypeDescriptionDefault
offset zx/off

Offset into VMO where read data starts.

No default
size uint64

Size of read data.

No default

Sysconfig_GetPartitionSize_Response

Defined in fuchsia.paver/paver.fidl

FieldTypeDescriptionDefault
size uint64 No default

Sysconfig_Read_Response resource

Defined in fuchsia.paver/paver.fidl

FieldTypeDescriptionDefault
data fuchsia.mem/Buffer No default

ENUMS

Asset strict

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.

Configuration strict

Type: uint32

Defined in fuchsia.paver/paver.fidl

Describes the version of an asset.

NameValueDescription
A 1
B 2
RECOVERY 3

ConfigurationStatus strict

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

BootManager_QueryActiveConfiguration_Result strict

Defined in fuchsia.paver/paver.fidl

Ordinal
VariantTypeDescription
1 response BootManager_QueryActiveConfiguration_Response
2 err zx/status

BootManager_QueryConfigurationLastSetActive_Result strict

Defined in fuchsia.paver/paver.fidl

Ordinal
VariantTypeDescription
1 response BootManager_QueryConfigurationLastSetActive_Response
2 err zx/status

BootManager_QueryConfigurationStatus_Result strict

Defined in fuchsia.paver/paver.fidl

Ordinal
VariantTypeDescription
1 response BootManager_QueryConfigurationStatus_Response
2 err zx/status

BootManager_QueryCurrentConfiguration_Result strict

Defined in fuchsia.paver/paver.fidl

Ordinal
VariantTypeDescription
1 response BootManager_QueryCurrentConfiguration_Response
2 err zx/status

DataSink_ReadAsset_Result strict resource

Defined in fuchsia.paver/paver.fidl

Ordinal
VariantTypeDescription
1 response DataSink_ReadAsset_Response
2 err zx/status

DataSink_WipeVolume_Result strict resource

Defined in fuchsia.paver/paver.fidl

Ordinal
VariantTypeDescription
1 response DataSink_WipeVolume_Response
2 err zx/status

ReadResult strict

Defined in fuchsia.paver/paver.fidl

Ordinal
VariantTypeDescription
1 err zx/status

Error encountered while reading data.

2 eof bool

End of file reached.

3 info ReadInfo

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

Sysconfig_GetPartitionSize_Result strict

Defined in fuchsia.paver/paver.fidl

Ordinal
VariantTypeDescription
1 response Sysconfig_GetPartitionSize_Response
2 err zx/status

Sysconfig_Read_Result strict resource

Defined in fuchsia.paver/paver.fidl

Ordinal
VariantTypeDescription
1 response Sysconfig_Read_Response
2 err zx/status

WriteFirmwareResult strict

Defined in fuchsia.paver/paver.fidl

Ordinal
VariantTypeDescription
1 status zx/status

The result status if a write was attempted.

2 unsupported bool

True if a write was not attempted due to unsupported firmware. This could be either unsupported content type or unsupported A/B configuration.

Callers must not treat this as a fatal error, but instead ignore it and continue to update the device. This is important to be able to add new items to an update package without breaking updates on older devices.