Data Access Commands
SEFWriteWithoutPhysicalAddress1
struct SEFStatus SEFWriteWithoutPhysicalAddress1(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, struct SEFPlacementID placementID, struct SEFUserAddress userAddress, uint32_t numADU, const struct iovec *iov, uint16_t iovcnt, 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 was enabled on the superblock, when the assigned superblock is filled and closed, SEF assigns a new super-block for following writes. If auto-allocate is not enabled, host software will know about the superblock size as part of the allocation, and can use this information to construct appropriately-sized write commands. Manually allocated superblocks for writes MUST be of type kForWrite. 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 SEFReadWithPhysicalAddress1(). In kSuperblock mode, the LBA portion of the user address is incremented for each ADU when writing multiple ADUs. The user address value 0xFFFFFFFFFFFFFFFF is reserved and is invalid. 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 device eventually flushes a tentative address to flash it may be discovered to be bad. When this happens, a kAddressUpdate QoS notification is sent indicating the data has moved to a new permanent flash address. There is no notification for addresses that have successfully flushed and are now permanent. It can be inferred instead by the kSuperblockStateChanged QoS notification for the owning superblock.
See Also: struct SEFStatus
Parameters of SEFWriteWithoutPhysicalAddress1
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFFlashAddress | flashAddress | In | Physical address of the superblock. 0xFFFFFFFFFFFFFFFF 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 ADU. Maximum allowed is 64k 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 |
| struct SEFFlashAddress * | permanentAddresses | Out | Must allocate space for returned permanent addresses equal to 8length (e.g. 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 superblocks are open. |
| const struct SEFWriteOverrides * | overrides | In | Overrides to scheduler parameters; pointer can be null for none required. |
Return value of SEFWriteWithoutPhysicalAddress1
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. When .error is non-zero, .info is the number of ADUs written. |
SEFReadWithPhysicalAddress1
struct SEFStatus SEFReadWithPhysicalAddress1(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, uint32_t numADU, const struct iovec *iov, uint16_t iovcnt, uint32_t iovOffset, struct SEFUserAddress userAddress, const struct SEFReadOverrides *overrides)
Reads data from a specified physical address. While writes are expressed in terms of logical addresses, reads are expressed in terms of physical 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 will 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 ~0 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 changed flash address notification has been processed.
See Also: struct SEFStatus, SEFSetRootPointer()
Parameters of SEFReadWithPhysicalAddress1
| 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 | 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 |
| const struct SEFReadOverrides * | overrides | In | Overrides to scheduler parameters; pointer can be null for none required. |
Return value of SEFReadWithPhysicalAddress1
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
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, void *copyContext)
Performs Nameless Copy with map or list; optional user address filtering. Copies ADUs as described by copySource to the copyDestination. If the destination superblock was allocated by SEFAllocateSuperBlock() the type must be kForCopy.
See Also: struct SEFStatus, SEFProcessAddressChangeRequests(), SEFPrepareBufferForNamelessCopy()
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 | Physical address of destination superblock |
| 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 addressChangeRequest userAddress array) |
| struct SEFAddressChangeRequest * | addressChangeInfo | Out | Information to record changed addresses |
| void * | copyContext | In | Pointer to working buffer returned by SEFPrepareBufferForNamelessCopy() |
Return value of SEFNamelessCopy
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result, .info contains:Destination super block has defective planes (1bit)Read error was detected on source (1bit)Data that is out of User Address range is detected (1bit)Destination superblock was filled/closed (1bit)Consumed entire source bitmap or list (1bit) |
SEFProcessAddressChangeRequests
struct SEFStatus SEFProcessAddressChangeRequests(SEFQoSHandle srcQosHandle, struct SEFCopySource copySource, SEFQoSHandle dstQosHandle, uint32_t copyInfo, const struct SEFAddressChangeRequest *addressChangeInfo)
Performs post processing of address change records for Nameless Copy.
See Also: struct SEFStatus, SEFNamelessCopy()
Parameters of SEFProcessAddressChangeRequests
| 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 |
| uint32_t | copyInfo | In | Information returned from namelessCopy in status.info field. copyInfo contains:Destination super block has defective planes (1bit)Read error was detected on source (1bit)Data that is out of User Address range is detected (1bit)Destination superblock was filled/closed (1bit)Consumed entire source bitmap or list (1bit) |
| const struct SEFAddressChangeRequest * | addressChangeInfo | In | Information to record changed addresses |
Return value of SEFProcessAddressChangeRequests
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFWriteWithoutPhysicalAddress1Async
void SEFWriteWithoutPhysicalAddress1Async(SEFQoSHandle qosHandle, struct SEFWriteWithoutPhysicalAddressIOCB *iocb)
This function is the asynchronous version of SEFWriteWithoutPhysicalAddress1(). 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: SEFWriteWithoutPhysicalAddress1()
Parameters of SEFWriteWithoutPhysicalAddress1Async
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFWriteWithoutPhysicalAddressIOCB * | iocb | In/Out | For asynchronous response from SEF Library. Unused fields should be set to 0. |
SEFReadWithPhysicalAddress1Async
void SEFReadWithPhysicalAddress1Async(SEFQoSHandle qosHandle, struct SEFReadWithPhysicalAddressIOCB *iocb)
This function is the asynchronous version of SEFReadWithPhysicalAddress1().
See Also: SEFReadWithPhysicalAddress1()
Parameters of SEFReadWithPhysicalAddress1Async
| 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. |