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.banjo
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
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
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
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
op |
NandOperation
|
Response
| Name | Type |
|---|---|
status |
zx/status
|
op |
NandOperation
|
RamNand
Defined in fuchsia.hardware.nand/ram-nand.fidl
Unlink
Removes the device.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
info |
RamNandInfo
|
Response
| Name | Type |
|---|---|
status |
zx/status
|
name |
string[32]
|
STRUCTS
Info
Defined in fuchsia.hardware.nand/nand.fidl
| Name | Type | Description | Default |
|---|---|---|---|
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.banjo
| Name | Type | Description | Default |
|---|---|---|---|
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
Defined in fuchsia.hardware.nand/nand.banjo
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.
| Name | Type | Description | Default |
|---|---|---|---|
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
| Name | Type | Description | Default |
|---|---|---|---|
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 | |
bbt |
bool
|
Contains a legacy bad block table. |
No default |
PartitionMap
Defined in fuchsia.hardware.nand/ram-nand.fidl
| Name | Type | Description | Default |
|---|---|---|---|
device_guid |
uint8[16]
|
No default | |
partition_count |
uint32
|
Number of partitions in the map. |
No default |
partitions |
[10]
|
No default |
RamNandInfo
Defined in fuchsia.hardware.nand/ram-nand.fidl
Defines how a newly created ram-nand volume should operate.
| Name | Type | Description | Default |
|---|---|---|---|
vmo |
handle<vmo>?
|
VMO to use as backing store for nand device. Size should match size of |
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 |
ENUMS
Class
Type: uint32
Defined in fuchsia.hardware.nand/nand.fidl
| Name | Value | Description |
|---|---|---|
UNKNOWN |
0 |
|
PARTMAP |
1 |
|
FTL |
2 |
|
BBS |
3 |
|
TEST |
4 |
NandOp
Type: uint32
Defined in fuchsia.hardware.nand/nand.banjo
NOTE: The protocol can be extended with barriers to support controllers that may issue multiple simultaneous request to the IO chips.
| Name | Value | Description |
|---|---|---|
READ |
1 |
|
WRITE |
2 |
|
ERASE |
3 |
UNIONS
NandOperation
Defined in fuchsia.hardware.nand/nand.banjo
| Name | Type | Description |
|---|---|---|
command |
NandOp
|
All Commands. |
rw |
NandReadWrite
|
NAND_OP_READ, NAND_OP_WRITE. |
erase |
NandErase
|
NAND_OP_ERASE. |
CONSTANTS
| Name | Value | Type | Description |
|---|---|---|---|
| GUID_LEN |
16
|
uint32 |
|
| MAX_PARTITIONS |
10
|
uint32 |
|
| NAME_LEN |
32
|
uint32 |