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

fuchsia.hardware.nand

NandOperation's are submitted for processing via the queue() method of the Nand Protocol. Once submitted, the contents of the NandOperation may be modified while it's being processed.

The completion_cb() must eventually be called upon success or failure and at that point the cookie field must contain whatever value was in it when the NandOperation was originally queued.

corrected_bit_flips are always related to nand_info.ecc_bits, so it is possible to obtain a value that is larger than what is being read (in the oob case). On the other hand, if errors cannot be corrected, the operation will fail, and corrected_bit_flips will be undefined.

PROTOCOLS

Nand

Defined in fuchsia.hardware.nand/nand.fidl

GetFactoryBadBlockList

Gets the list of bad erase blocks, as reported by the nand manufacturer. This should only be called before writing any data to the nand, and the returned data should be saved somewhere else, along blocks that become bad after they've been in use.

Request

NameType

Response

NameType
status zx/status
bad_blocks vector<uint32>

Query

Obtains the parameters of the nand device and the required size of |NandOperation|. The |NandOperation| submitted via Queue() must have nand_op_size - sizeof(NandOperation) bytes available at the end of the structure for the use of the driver.

Request

NameType

Response

NameType
info fuchsia.hardware.nandinfo/NandInfo
nand_op_size uint64

Queue

Submits an IO request for processing. Success or failure will be reported via the callback. The callback may be called before the Queue() method returns. Should return ZX_ERR_IO only when error ocurred due to underlying hardware. When the hardware is not able to correct all bitflips for a page, the driver should return ZX_ERR_IO_DATA_INTEGRITY.

Request

NameType
op NandOperation

Response

NameType
status zx/status
op NandOperation

RamNand

Defined in fuchsia.hardware.nand/ram-nand.fidl

Removes the device.

NameType
NameType
status zx/status

RamNandCtl

Defined in fuchsia.hardware.nand/ram-nand.fidl

CreateDevice

Creates a new ram-nand device. On success, returns the device's name (not the full topological name, just the last component).

Request

NameType
info RamNandInfo

Response

NameType
status zx/status
name string[32]

STRUCTS

Info

Defined in fuchsia.hardware.nand/nand.fidl

NameTypeDescriptionDefault
page_size uint32 No default
pages_per_block uint32 No default
num_blocks uint32 No default
ecc_bits uint32 No default
oob_size uint32 No default
nand_class Class No default
partition_guid uint8[16] No default

NandErase

Defined in fuchsia.hardware.nand/nand.fidl

NameTypeDescriptionDefault
command NandOp

Command.

No default
first_block uint32

Offset into nand, in erase blocks.

No default
num_blocks uint32

Number of blocks to erase. (0 is invalid).

No default

NandReadWrite resource

Defined in fuchsia.hardware.nand/nand.fidl

A single operation can read or write an arbitrary number of pages, including out of band (OOB) data for each page. If either regular data or OOB is not required, the relevant VMO handle should be set to ZX_HANDLE_INVALID.

Note that length dictates the number of pages to access, regardless of the type of data requested: regular data, OOB or both.

The OOB data will be copied to (and from) a contiguous memory range starting at the given offset. Note that said offset is given in nand pages even though OOB is just a handful of bytes per page. In other words, after said offset, the OOB data for each page is located nand_info.oob_size bytes apart.

For example, to read 5 pages worth of data + OOB, with page size of 2 kB and 16 bytes of OOB per page, setting:

 data_vmo = oob_vmo = vmo_handle
 length = 5
 offset_nand = 20
 offset_data_vmo = 0
 offset_oob_vmo = 5

will transfer pages [20, 24] to the first 2048 * 5 bytes of the vmo, followed by 16 * 5 bytes of OOB data starting at offset 2048 * 5.

NameTypeDescriptionDefault
command NandOp

Command.

No default
data_vmo handle<vmo>

vmo of data to read or write.

No default
oob_vmo handle<vmo>

vmo of OOB data to read or write.

No default
length uint32

Number of pages to access. (0 is invalid).

No default
offset_nand uint32

Offset into nand, in pages.

No default
offset_data_vmo uint64

Data vmo offset in (nand) pages.

No default
offset_oob_vmo uint64

OOB vmo offset in (nand) pages.

No default
corrected_bit_flips uint32

Return value from READ_DATA, max corrected bit flips in any underlying ECC chunk read. The caller can compare this value against ecc_bits to decide whether the nand erase block needs to be recycled.

No default

Partition

Defined in fuchsia.hardware.nand/ram-nand.fidl

NameTypeDescriptionDefault
type_guid uint8[16]

GUID specifying the format and use of data stored in the partition.

No default
unique_guid uint8[16]

GUID unique to this partition.

No default
first_block uint32

First and last block occupied by this partition.

No default
last_block uint32 No default
copy_count uint32

The number of data copies and offset between each data copy (if relevant).

No default
copy_byte_offset uint32 No default
name uint8[32] No default
hidden bool

Not a user-visible partition.

No default
bbt bool

Contains a legacy bad block table.

No default

PartitionMap

Defined in fuchsia.hardware.nand/ram-nand.fidl

NameTypeDescriptionDefault
device_guid uint8[16] No default
partition_count uint32

Number of partitions in the map.

No default
partitions [10] No default

RamNandInfo resource

Defined in fuchsia.hardware.nand/ram-nand.fidl

Defines how a newly created ram-nand volume should operate.

NameTypeDescriptionDefault
vmo handle<vmo>?

VMO to use as backing store for nand device. Size should match size of nand_info. If a vmo is not provided, the device will create its own buffer and initialize it to be empty (all 1s).

No default
nand_info Info

The desired "chip" configuration.

No default
partition_map PartitionMap

Partition map for the device. This can be left fully empty (as in default-initialized), as long as no metadata has to be exported by the device. If any metadata is required, it will be extracted from this map.

No default
export_nand_config bool

If true, export "extra" partition configuration as metadata.

No default
export_partition_map bool

if true, export a boot partition map as metadata.

No default
fail_after uint32

If non-zero, fail after fail_after writes.

No default

ENUMS

Class strict

Type: uint32

Defined in fuchsia.hardware.nand/nand.fidl

NameValueDescription
UNKNOWN 0
PARTMAP 1
FTL 2
BBS 3
TEST 4
INTEL_FLASH_DESCRIPTOR 5

NAND device contains an Intel flash descriptor.

NandOp strict

Type: uint32

Defined in fuchsia.hardware.nand/nand.fidl

NOTE: The protocol can be extended with barriers to support controllers that may issue multiple simultaneous request to the IO chips.

NameValueDescription
READ 1
WRITE 2
ERASE 3

UNIONS

NandOperation strict resource

Defined in fuchsia.hardware.nand/nand.fidl

NameTypeDescription
command NandOp

All Commands.

rw NandReadWrite

NAND_OP_READ, NAND_OP_WRITE.

erase NandErase

NAND_OP_ERASE.

CONSTANTS

NameValueTypeDescription
GUID_LEN 16 uint32
MAX_PARTITIONS 10 uint32
NAME_LEN 32 uint32