Data Access Commands
SEFWriteWithoutPhysicalAddress
struct SEFStatus SEFWriteWithoutPhysicalAddress(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, struct SEFPlacementID placementID, struct SEFUserAddress userAddress, uint32_t numADU, const struct iovec *iov, uint16_t iovcnt, const void *metadata, struct SEFFlashAddress *permanentAddresses, uint32_t *distanceToEndOfSuperBlock, const struct SEFWriteOverrides *overrides)
Writes data to the specified user address to an underlying physical flash page that is assigned for the QoS Domain.
If auto-allocate is enabled for the super block, when the assigned super block is filled and closed, the SEF Unit assigns a new super block for the remaining writes. If auto-allocate is not enabled, host software will know about the super block size as part of the allocation, and can use this information to construct appropriately-sized write commands. This call will not return until the data has been persisted, and will automatically pad the user data with dummy data if required to complete flash memory programming.
The userAddress supplied here will be checked when reading the data back with SEFReadWithPhysicalAddress(). If storing a user address is not required, a userAddress of SEFUserAddressIgnore may be used. The check can optionally be disabled when reading and must be disabled to read data written with a user address of SEFUserAddressIgnore. In kSuperBlock mode and writing multiple ADUs, the LBA portion of the user address is incremented for each ADU. The write will fail if the userAddress is incremented to a value equal to SEFUserAddressIgnore. The userAddresses in a super block can be read using SEFGetUserAddressList.
Note: The synchronous and asynchronous versions differ in how data is committed to flash. As described above, the synchronous version flushes data to flash returning permanent flash addresses.
In contrast, the asynchronous version lazily flushes data to flash. The flash addresses returned are tentative instead. Once the SEF Unit eventually flushes a tentative address to flash, the original address may be discovered to be bad. When this happens, a kAddressUpdate QoS Domain notification is sent indicating the data has moved to a new permanent flash address. When the IOCB flag kSefIoFlagNotifyBufferRelease is set, the domain notification kBufferRelease will be sent for each piece of the IOCB iov as it becomes committed to flash. It is then the responsibility of the caller to maintain the lifetime of the iov buffers until the release notifications are sent. When not set, the commit state can be inferred instead by the kSuperBlockStateChanged QoS notification for the owning super block. Buffer lifetime is managed by library in this case by copying write data into library managed buffers.
Parameters of SEFWriteWithoutPhysicalAddress
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFFlashAddress | flashAddress | In | Flash address of the super block. SEFAutoAllocate if auto allocate. |
| struct SEFPlacementID | placementID | In | Only valid if the flashAddress is auto allocated. A value from 0 to numPlacementIds–1 indicating what logical data group to place this data in. |
| struct SEFUserAddress | userAddress | In | FTL can store meta-data related to this operation by this field. For example, storing LBA address to bind to this write operation such as data tags. |
| uint32_t | numADU | In | Total amount of write data size calculated in QoS Domain ADUs. |
| const struct iovec* | iov | In | A pointer to the scatter gather list |
| uint16_t | iovcnt | In | The number of elements in the scatter gather list |
| const void * | metadata | In | Pointer to metadata to write with the data; The number of bytes per ADU required is SEFQoSDomainInfo::ADUsize.meta. May be NULL. |
| struct SEFFlashAddress* | permanentAddresses | Out | Must allocate space for returned permanent physical addresses equal to 8length (i.e. 8number of ADUs) |
| uint32_t * | distanceToEndOfSuperBlock | Out | Indicates remaining size in ADU after this write operation. May be NULL. This is not a guarantee as the block may be forced closed if too many super blocks are open. When this returns 0, the block was closed. |
| const struct SEFWriteOverrides* | overrides | In | Overrides to scheduler parameters; pointer can be null for none required. |
Return value of SEFWriteWithoutPhysicalAddress
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. When .error is non-zero, .info is the number of ADUs written. |
Return values of SEFWriteWithoutPhysicalAddress
| Error Value | Description |
|---|
| -ENODEV | The QoS Domain handle is not valid |
| -EPERM | The QoS Domain Handle is not open |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| -ENOSPC | The QoS Domain is out of space |
SEFReadWithPhysicalAddress
struct SEFStatus SEFReadWithPhysicalAddress(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, uint32_t numADU, const struct iovec *iov, uint16_t iovcnt, uint32_t iovOffset, struct SEFUserAddress userAddress, void *metadata, const struct SEFReadOverrides *overrides)
Reads data from a specified physical address.
While writes are expressed in terms of a placement ID or super block flash addresses, reads are expressed in terms of physical flash addresses. Read commands may interrupt other types of commands. When there is an in-flight flash memory command to the same flash die other than a read command, the in-flight command may be suspended in order to maintain deterministic read latency. If the target physical address is currently in the process of being programmed, data will instead be returned from the write buffer.
The userAddress must either match what was stored when the data was written or be SEFUserAddressIgnore to disable checking. In kSuperBlock mode, the LBA portion of the user address is incremented for each ADU in a multi-ADU write.
Note: When reading data that was just written, a read error will be returned when the data's original flash address has been updated but the notification has yet to be processed by the client. In this case, the caller must retry the read after the flash address change notification has been processed.
See Also: SEFSetRootPointer()
Parameters of SEFReadWithPhysicalAddress
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFFlashAddress | flashAddress | In | Physical address for the read command; When the QoS Domain ID and block number are 0, the ADU offset is the root pointer index for the flash address to read. |
| uint32_t | numADU | In | Length of data to read (in ADUs). Maximum allowed is superBlockCapacity. |
| const struct iovec* | iov | In | A pointer to the scatter gather list |
| uint16_t | iovcnt | In | The number of elements in the scatter gather list |
| uint32_t | iovOffset | In | Starting byte offset into iov array |
| struct SEFUserAddress | userAddress | In | Stored data by the FTL. It will be validated with what was stored when the data was written except when SEFUserAddressIgnore is supplied |
| void * | metadata | In | Buffer to receive metadata stored with the data; The number of bytes per ADU required is SEFQoSDomainInfo::ADUsize.meta. May be NULL |
| const struct SEFReadOverrides* | overrides | In | Overrides to scheduler parameters; pointer can be null for none required. |
Return value of SEFReadWithPhysicalAddress
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFReadWithPhysicalAddress
| Error Value | Description |
|---|
| -ENODEV | The QoS Domain handle is not valid |
| -EPERM | The QoS Domain Handle is not open |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
SEFNamelessCopy
struct SEFStatus SEFNamelessCopy(SEFQoSHandle srcQosHandle, struct SEFCopySource copySource, SEFQoSHandle dstQosHandle, struct SEFFlashAddress copyDestination, const struct SEFUserAddressFilter *filter, const struct SEFCopyOverrides *overrides, uint32_t numAddressChangeRecords, struct SEFAddressChangeRequest *addressChangeInfo)
Performs Nameless Copy with map or list; optional user address filtering.
Copies ADUs as described by copySource to the copyDestination. Source addresses can only reference closed superblocks.
Parameters of SEFNamelessCopy
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | srcQosHandle | In | Handle to the source QoS Domain |
| struct SEFCopySource | copySource | In | Physical addresses to copy |
| SEFQoSHandle | dstQosHandle | In | Handle to the destination QoS Domain |
| struct SEFFlashAddress | copyDestination | In | Flash address of destination super block |
| const struct SEFUserAddressFilter* | filter | In | Pointer to user address filter parameters, null indicates no filtering |
| const struct SEFCopyOverrides* | overrides | In | Pointer to overrides to scheduler parameters; pointer can be null for none required. |
| uint32_t | numAddressChangeRecords | In | Maximum number of ADUs to copy (size of SEFAddressChangeRequest userAddress array) |
| struct SEFAddressChangeRequest* | addressChangeInfo | In | Filled with changed addresses |
Return value of SEFNamelessCopy
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result |
Return values of SEFNamelessCopy
| Error Value | Description |
|---|
| 0 | the info member contains: Destination super block has defective planes (kCopyDesinationDefectivePlanes), Read error was detected on source (kCopyReadErrorOnSource), Data that is out of User Address range is detected (kCopyFilteredUserAddresses), Destination super block was filled/closed (kCopyClosedDestination), Consumed entire source bitmap or list (kCopyConsumedSource) |
| -ENODEV | The QoS Domain handle is not valid |
| -EPERM | The QoS Domain Handle is not open |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
SEFWriteWithoutPhysicalAddressAsync
void SEFWriteWithoutPhysicalAddressAsync(SEFQoSHandle qosHandle, struct SEFWriteWithoutPhysicalAddressIOCB *iocb)
This function is the asynchronous version of SEFWriteWithoutPhysicalAddress().
Note: When the kSefIoFlagCommit flag is set in the IOCB's flag field, the returned tentative addresses will be permanent, potentially adding padding.
Note: Any kAddressUpdate and kSuperBlockStateChange QoS notifications for the returned tentative addresses will occur after the iocb completion routine has returned. When no completion routine is set, the caller must handle the race condition of acting on done being set and the notifications being sent.
See Also: SEFWriteWithoutPhysicalAddress()
Parameters of SEFWriteWithoutPhysicalAddressAsync
SEFReadWithPhysicalAddressAsync
void SEFReadWithPhysicalAddressAsync(SEFQoSHandle qosHandle, struct SEFReadWithPhysicalAddressIOCB *iocb)
This function is the asynchronous version of SEFReadWithPhysicalAddress().
See Also: SEFReadWithPhysicalAddress()
Parameters of SEFReadWithPhysicalAddressAsync
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFReadWithPhysicalAddressIOCB* | iocb | In/Out | For asynchronous response from SEF Library Unused fields should be set to 0. |
SEFNamelessCopyAsync
void SEFNamelessCopyAsync(SEFQoSHandle qosHandle, struct SEFNamelessCopyIOCB *iocb)
This function is the asynchronous version of SEFNamelessCopy().
See Also: SEFNamelessCopy()
Parameters of SEFNamelessCopyAsync
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the source QoS Domain |
| struct SEFNamelessCopyIOCB* | iocb | In/Out | For asynchronous response from SEF Library Unused fields should be set to 0. |