Skip to main content
Version: 1.13

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

TypeNameDirectionDescription
SEFQoSHandleqosHandleInHandle to the QoS Domain
struct SEFFlashAddressflashAddressInFlash address of the super block. SEFAutoAllocate if auto allocate.
struct SEFPlacementIDplacementIDInOnly 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 SEFUserAddressuserAddressInFTL 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_tnumADUInTotal amount of write data size calculated in QoS Domain ADUs.
const struct iovec*iovInA pointer to the scatter gather list
uint16_tiovcntInThe number of elements in the scatter gather list
const void *metadataInPointer to metadata to write with the data; The number of bytes per ADU required is SEFQoSDomainInfo::ADUsize.meta. May be NULL.
struct SEFFlashAddress*permanentAddressesOutMust allocate space for returned permanent physical addresses equal to 8length (i.e. 8number of ADUs)
uint32_t *distanceToEndOfSuperBlockOutIndicates 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*overridesInOverrides to scheduler parameters; pointer can be null for none required.

Return value of SEFWriteWithoutPhysicalAddress

TypeDescription
struct SEFStatusStatus and info summarizing result. When .error is non-zero, .info is the number of ADUs written.

Return values of SEFWriteWithoutPhysicalAddress

Error ValueDescription
-ENODEVThe QoS Domain handle is not valid
-EPERMThe QoS Domain Handle is not open
-EINVALThe function parameter is not valid; info returns the parameter index that is not valid
-ENOSPCThe 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

TypeNameDirectionDescription
SEFQoSHandleqosHandleInHandle to the QoS Domain
struct SEFFlashAddressflashAddressInPhysical 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_tnumADUInLength of data to read (in ADUs). Maximum allowed is superBlockCapacity.
const struct iovec*iovInA pointer to the scatter gather list
uint16_tiovcntInThe number of elements in the scatter gather list
uint32_tiovOffsetInStarting byte offset into iov array
struct SEFUserAddressuserAddressInStored data by the FTL. It will be validated with what was stored when the data was written except when SEFUserAddressIgnore is supplied
void *metadataInBuffer to receive metadata stored with the data; The number of bytes per ADU required is SEFQoSDomainInfo::ADUsize.meta. May be NULL
const struct SEFReadOverrides*overridesInOverrides to scheduler parameters; pointer can be null for none required.

Return value of SEFReadWithPhysicalAddress

TypeDescription
struct SEFStatusStatus and info summarizing result.

Return values of SEFReadWithPhysicalAddress

Error ValueDescription
-ENODEVThe QoS Domain handle is not valid
-EPERMThe QoS Domain Handle is not open
-EINVALThe 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

TypeNameDirectionDescription
SEFQoSHandlesrcQosHandleInHandle to the source QoS Domain
struct SEFCopySourcecopySourceInPhysical addresses to copy
SEFQoSHandledstQosHandleInHandle to the destination QoS Domain
struct SEFFlashAddresscopyDestinationInFlash address of destination super block
const struct SEFUserAddressFilter*filterInPointer to user address filter parameters, null indicates no filtering
const struct SEFCopyOverrides*overridesInPointer to overrides to scheduler parameters; pointer can be null for none required.
uint32_tnumAddressChangeRecordsInMaximum number of ADUs to copy (size of SEFAddressChangeRequest userAddress array)
struct SEFAddressChangeRequest*addressChangeInfoInFilled with changed addresses

Return value of SEFNamelessCopy

TypeDescription
struct SEFStatusStatus and info summarizing result

Return values of SEFNamelessCopy

Error ValueDescription
0the 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)
-ENODEVThe QoS Domain handle is not valid
-EPERMThe QoS Domain Handle is not open
-EINVALThe 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

TypeNameDirectionDescription
SEFQoSHandleqosHandleInHandle to the QoS Domain
struct SEFWriteWithoutPhysicalAddressIOCB*iocbIn/OutFor asynchronous response from SEF Library. Unused fields should be set to 0.

SEFReadWithPhysicalAddressAsync

void SEFReadWithPhysicalAddressAsync(SEFQoSHandle qosHandle, struct SEFReadWithPhysicalAddressIOCB *iocb)

This function is the asynchronous version of SEFReadWithPhysicalAddress().

See Also: SEFReadWithPhysicalAddress()

Parameters of SEFReadWithPhysicalAddressAsync

TypeNameDirectionDescription
SEFQoSHandleqosHandleInHandle to the QoS Domain
struct SEFReadWithPhysicalAddressIOCB*iocbIn/OutFor 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

TypeNameDirectionDescription
SEFQoSHandleqosHandleInHandle to the source QoS Domain
struct SEFNamelessCopyIOCB*iocbIn/OutFor asynchronous response from SEF Library Unused fields should be set to 0.