API Management Commands
SEFLibraryInit
struct SEFStatus SEFLibraryInit(void)
Initializes the SEF Library, enumerates the SEF Units present, and returns the number of units found. Every successful call to SEFLibraryInit() must be balanced with a call to SEFLibraryCleanup().
See Also: struct SEFStatus, SEFLibraryCleanup()
Return value of SEFLibraryInit
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. The 'info' member contains number of units. |
SEFGetHandle
SEFHandle SEFGetHandle(int index)
Returns a handle to the SEF device at the specified index (zero based)
Parameters of SEFGetHandle
| Type | Name | Direction | Description |
|---|---|---|---|
| int | index | In | Index of the SEF Unit |
Return value of SEFGetHandle
| Type | Description |
|---|---|
| SEFHandle | Handle to the SEF Unit |
SEFLibraryCleanup
struct SEFStatus SEFLibraryCleanup(void)
Performs cleanup of the SEF Library and releases resources.
See Also: struct SEFStatus, SEFLibraryInit()
Return value of SEFLibraryCleanup
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFGetInformation
const struct SEFInfo* SEFGetInformation(SEFHandle sefHandle)
Gets device information. Returns ADU size(s), number of channels, number of dies, and other associated information.
See Also: struct SEFStatus
Parameters of SEFGetInformation
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
Return value of SEFGetInformation
| Type | Description |
|---|---|
| const struct SEFInfo * | Status and info summarizing result. |
SEFListVirtualDevices
struct SEFStatus SEFListVirtualDevices(SEFHandle sefHandle, struct SEFVirtualDeviceList *list, int bufferSize)
Returns a list of the defined Virtual Devices.
See Also: struct SEFStatus
Parameters of SEFListVirtualDevices
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFVirtualDeviceList * | list | Out | Buffer for storing list of Virtual Devices |
| int | bufferSize | In | Buffer size |
Return value of SEFListVirtualDevices
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFListQoSDomains
struct SEFStatus SEFListQoSDomains(SEFHandle sefHandle, struct SEFQoSDomainList *list, int bufferSize)
Returns a list of the defined QoS Domains.
See Also: struct SEFStatus
Parameters of SEFListQoSDomains
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFQoSDomainList * | list | Out | Buffer for storing list of QoS Domains |
| int | bufferSize | In | Buffer size |
Return value of SEFListQoSDomains
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFCreateVirtualDevice
struct SEFStatus SEFCreateVirtualDevice(SEFHandle sefHandle, struct SEFVirtualDeviceID virtualDeviceID, struct SEFDieMap dieMap, enum SEFDefectManagementMethod defectStrategy, uint8_t numFMQueues, const struct SEFWeights weights[])
Creates a Virtual Device and allocates physical resources.
See Also: struct SEFStatus, SEFGetInformation()
Parameters of SEFCreateVirtualDevice
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFVirtualDeviceID | virtualDeviceID | In | Virtual Device ID |
| struct SEFDieMap | dieMap | In | Dies requested for virtual device |
| enum SEFDefectManagementMethod | defectStrategy | In | Defect management strategy for the Virtual Device |
| uint8_t | numFMQueues | In | Number of Flash Media Queues per die in the Virtual Device |
| const struct SEFWeights[] | weights | In | Weight values for each Flash Media Queue |
Return value of SEFCreateVirtualDevice
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. Returns 0 on success and negative value on error. |
SEFGetVirtualDeviceInformation
struct SEFStatus SEFGetVirtualDeviceInformation(SEFHandle sefHandle, struct SEFVirtualDeviceID virtualDeviceID, struct SEFVirtualDeviceInfo *info, int bufferSize)
Returns Virtual Device information.
See Also: struct SEFStatus
Parameters of SEFGetVirtualDeviceInformation
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFVirtualDeviceID | virtualDeviceID | In | Virtual Device ID |
| struct SEFVirtualDeviceInfo * | info | Out | Buffer for storing VD information |
| int | bufferSize | In | Buffer size |
Return value of SEFGetVirtualDeviceInformation
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFCreateQoSDomain
struct SEFStatus SEFCreateQoSDomain(SEFVDHandle vdHandle, struct SEFQoSDomainID QoSDomainID, uint64_t flashCapacity, uint64_t flashQuota, uint32_t ADUsize, enum SEFAPIIdentifier api, enum SEFErrorRecoveryMode recovery, int encryption, uint16_t numRootPointers, uint16_t numPlacementIDs, struct SEFFMQAssignments FMQDefaults)
Attempts to create a QoS Domain in the specified Virtual Device. Returns an error when the target virtual device doesn’t have enough flash memory space. When the flashQuota is less than the flashCapacity, it will be set to the flashCapacity.
See Also: SEFGetInformation()
Parameters of SEFCreateQoSDomain
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFVDHandle | vdHandle | In | Handle to the Virtual Device |
| struct SEFQoSDomainID | QoSDomainID | In | QoS Domain ID. Unique across all QoS Domains |
| uint64_t | flashCapacity | In | Number of required/reserved ADUs |
| uint64_t | flashQuota | In | Number of ADUs that can be allocated |
| uint32_t | ADUsize | In | Size of ADU in this QoS domain in bytes. Must be one of the values in ADUSize[] in SEFInfo returned by SEFGetInformation(). SEF Unit should support 4kiB. |
| enum SEFAPIIdentifier | api | In | Specifies the API Identifier for this QoS domain |
| enum SEFErrorRecoveryMode | recovery | In | Specifies the recovery mode for this QoS domain |
| int | encryption | In | 0 for disabled, non-zero for enabled |
| uint16_t | numRootPointers | In | Specifies the number of root pointers corresponding to this QoS domain |
| uint16_t | numPlacementIDs | In | The maximum number of Placement IDs that can be placed on the QoS domain. (The number of Placement IDs would affect memory usage) |
| struct SEFFMQAssignments | FMQDefaults | In | The default die FMQ assignments for I/O commands |
Return value of SEFCreateQoSDomain
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFSetQoSDomainCapacity
struct SEFStatus SEFSetQoSDomainCapacity(SEFQoSHandle qosHandle, uint64_t flashCapacity, uint64_t flashQutoa)
Resets the capacity of a QoS Domain. Sets a new capacity and quota for the QoS domain. When the flashQuota is less than the flashCapacity, it is set to the flashCapacity. Returns an error when the total capacity of assigned super blocks exceeds the new capacity.
Parameters of SEFSetQoSDomainCapacity
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| uint64_t | flashCapacity | In | Number of required/reserved ADUs |
| uint64_t | flashQutoa | In | Number of ADUs that can be allocated |
Return value of SEFSetQoSDomainCapacity
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFSetRootPointer
struct SEFStatus SEFSetRootPointer(SEFQoSHandle qosHandle, int index, struct SEFFlashAddress value)
Sets the physical address of the QoSDomain root ADU pointer. A root pointer may be set to any value. Root pointer values are read back using SEFGetQoSDomainInformation(). When a root pointer is set to a flash address that is valid for the QoS domain it's stored in, the ADU it points to can be read by SEFReadWithPhysicalAddress1() using a flash address of just the root pointer index as the ADU.
See Also: struct SEFStatus, SEFReadWithPhysicalAddress1()
Parameters of SEFSetRootPointer
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| int | index | In | The index of the root pointer |
| struct SEFFlashAddress | value | In | Value of the pointer |
Return value of SEFSetRootPointer
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFSetReadDeadline
struct SEFStatus SEFSetReadDeadline(SEFQoSHandle qosHandle, enum SEFDeadlineType deadline)
Sets target QoS Domain's read deadline policy.
See Also: struct SEFStatus, struct SEFVirtualDeviceInfo
Parameters of SEFSetReadDeadline
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| enum SEFDeadlineType | deadline | In | Deadline type for this QoS domain |
Return value of SEFSetReadDeadline
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFGetQoSDomainInformation
struct SEFStatus SEFGetQoSDomainInformation(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID, struct SEFQoSDomainInfo *info, int bufferSize)
Returns QoS Domain information, including the list of super blocks assigned to the QoS Domain.
See Also: struct SEFStatus
Parameters of SEFGetQoSDomainInformation
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFQoSDomainID | QoSDomainID | In | QoS Domain ID |
| struct SEFQoSDomainInfo * | info | Out | Buffer for storing QoS Domain information |
| int | bufferSize | In | Buffer size |
Return value of SEFGetQoSDomainInformation
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFGetReuseList
struct SEFStatus SEFGetReuseList(SEFQoSHandle qosHandle, struct SEFWearInfo *info, int bufferSize)
Returns list of SuperBlocks to process for wear-leveling. Used in support of the implementation of a host-specified wear leveling policy. SEF has a built in wear-leveling mechanism.
See Also: struct SEFStatus
Parameters of SEFGetReuseList
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFWearInfo * | info | Out | Buffer for storing information of blocks to process |
| int | bufferSize | In | Buffer size |
Return value of SEFGetReuseList
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFGetRefreshList
struct SEFStatus SEFGetRefreshList(SEFQoSHandle qosHandle, struct SEFRefreshInfo *info, int bufferSize)
Returns a list of blocks that have encountered ECC errors. These blocks subsequently need to be re-written, or else data loss may occur. This call should be part of a periodic background check to guard against data loss.
See Also: struct SEFStatus
Parameters of SEFGetRefreshList
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFRefreshInfo * | info | Out | Buffer for storing information of blocks to process |
| int | bufferSize | In | Buffer size |
Return value of SEFGetRefreshList
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFGetCheckList
struct SEFStatus SEFGetCheckList(SEFQoSHandle qosHandle, struct SEFCheckInfo *info, int bufferSize)
Returns a list of blocks that have encountered conditions that need to be checked. In the event that this command indicates that blocks need to be checked, a subsequent patrol command (SEFCheckPage) should be issued in response. Detailed error statistics will be returned as part of the patrol, and appropriate corrective actions can be based on the returned information.
See Also: struct SEFStatus, SEFCheckPage()
Parameters of SEFGetCheckList
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFCheckInfo * | info | Out | Buffer for storing information of blocks to process |
| int | bufferSize | In | Buffer size |
Return value of SEFGetCheckList
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFGetUserAddressList
struct SEFStatus SEFGetUserAddressList(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, struct SEFUserAddressRecord *list, int bufferSize)
Returns the user address list in terms of its underlying superblocks. Used as part of an FTL reconstruction activity. This can happen in the event of, for example, ungraceful shutdown. This mechanism can also be used to build custom diagnostic tools. This command is not needed during normal operation.
See Also: struct SEFStatus
Parameters of SEFGetUserAddressList
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFFlashAddress | flashAddress | In | Physical address of the superblock |
| struct SEFUserAddressRecord * | list | Out | Buffer for storing list of user addresses |
| int | bufferSize | In | Buffer size |
Return value of SEFGetUserAddressList
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFGetSuperBlockInfo
struct SEFStatus SEFGetSuperBlockInfo(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, struct SEFSuperBlockRecord *info)
Returns information corresponding to the superblock.
See Also: struct SEFStatus
Parameters of SEFGetSuperBlockInfo
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFFlashAddress | flashAddress | In | Physical address of the superblock |
| struct SEFSuperBlockRecord * | info | Out | Buffer for storing superblock information |
Return value of SEFGetSuperBlockInfo
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFCheckPage
struct SEFStatus SEFCheckPage(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress)
This is a read patrol operation which can be used in conjunction with SEFGetCheckList. Returns detailed information concerning checked pages to allow host software to take appropriate corrective actions.
See Also: struct SEFStatus, SEFGetCheckList()
Parameters of SEFCheckPage
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFFlashAddress | flashAddress | In | Physical address to be checked |
Return value of SEFCheckPage
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFDeleteVirtualDevice
struct SEFStatus SEFDeleteVirtualDevice(SEFHandle sefHandle, struct SEFVirtualDeviceID virtualDeviceID)
Deletes the target virtual device. The Virtual Device must be in the closed state before issuing this command. Moreover, this command will fail if the Virtual Device contains any QoS Domains.
See Also: struct SEFStatus
Parameters of SEFDeleteVirtualDevice
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFVirtualDeviceID | virtualDeviceID | In | Virtual Device ID |
Return value of SEFDeleteVirtualDevice
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFDeleteQoSDomain
struct SEFStatus SEFDeleteQoSDomain(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID)
Deletes the target QoS domain. The QoS domain must be in the closed state before issuing this command. After closing the target QoS domain, its assigned superblocks are returned to the virtual device's free pool.
See Also: struct SEFStatus
Parameters of SEFDeleteQoSDomain
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFQoSDomainID | QoSDomainID | In | QoS Domain ID |
Return value of SEFDeleteQoSDomain
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFResetEncryptionKey
struct SEFStatus SEFResetEncryptionKey(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID)
Resets the encryption key for a QoS Domain.
See Also: struct SEFStatus
Parameters of SEFResetEncryptionKey
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFQoSDomainID | QoSDomainID | In | QoS Domain ID |
Return value of SEFResetEncryptionKey
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFOpenVirtualDevice
struct SEFStatus SEFOpenVirtualDevice(SEFHandle sefHandle, struct SEFVirtualDeviceID virtualDeviceID, void(*notifyFunc)(void *, struct SEFVDNotification), void *context, SEFVDHandle *vdHandle)
Opens the target virtual device. Since Virtual Devices are persistent, this provides the mechanism for opening a preexisting Virtual Device to resume I/O after reboot. This function needs to be called in order to receive notifications about the virtual device, such as in the event that a reduced capacity notification is issued.
See Also: struct SEFStatus
Parameters of SEFOpenVirtualDevice
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFVirtualDeviceID | virtualDeviceID | In | Virtual Device ID |
| void()(void , struct SEFVDNotification) | notifyFunc | In | Callback to be executed upon event generation |
| void * | context | In | A void* pointer passed to the async event notification function (used to pass user context information) |
| SEFVDHandle * | vdHandle | In | Handle to the Virtual Drive |
Return value of SEFOpenVirtualDevice
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFCloseVirtualDevice
struct SEFStatus SEFCloseVirtualDevice(SEFVDHandle vdHandle)
Closes an open Virtual Device and shuts down associated event notification.
See Also: struct SEFStatus
Parameters of SEFCloseVirtualDevice
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFVDHandle | vdHandle | In | Handle to the Virtual Device |
Return value of SEFCloseVirtualDevice
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFOpenQoSDomain
struct SEFStatus SEFOpenQoSDomain(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID, void(*notifyFunc)(void *, struct SEFQoSNotification), void *context, const void *encryptionKey, SEFQoSHandle *qosHandle)
Opens a previously created QoS Domain. Since QoS Domains are persistent, this provides the mechanism for opening a preexisting QoS Domain to resume I/O after reboot. This function also provides a channel to receive notifications regarding this QoS domain.
See Also: struct SEFStatus
Parameters of SEFOpenQoSDomain
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFQoSDomainID | QoSDomainID | In | QoS Domain ID |
| void()(void , struct SEFQoSNotification) | notifyFunc | In | Callback to be executed during event generation |
| void * | context | In | A void* pointer passed to the async event notification function (used to pass user context information) |
| const void * | encryptionKey | In | In a multitenant environment, different tenants will write to separate QoS domains. Provides for individualized encryption keys on a per-domain basis |
| SEFQoSHandle * | qosHandle | Out | Handle to the QoS Domain |
Return value of SEFOpenQoSDomain
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFCloseQoSDomain
struct SEFStatus SEFCloseQoSDomain(SEFQoSHandle qosHandle)
Closes an open QoS Domain. This in turn will close any open superblocks associated with this domain. All outstanding kSuperblockChangeState events will be delivered before this function returns. A QoS Domain must be in the closed state to be deleted.
See Also: struct SEFStatus
Parameters of SEFCloseQoSDomain
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
Return value of SEFCloseQoSDomain
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFParseFlashAddress
struct SEFStatus SEFParseFlashAddress(SEFHandle sefHandle, struct SEFFlashAddress flashAddress, struct SEFQoSDomainID *QoSDomainID, uint16_t *blockNumber, uint32_t *ADUOffset)
This function is used to extract info needed by FTL from an opaque flash address.
See Also: struct SEFStatus
Parameters of SEFParseFlashAddress
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFFlashAddress | flashAddress | In | The opaque address to be parsed |
| struct SEFQoSDomainID * | QoSDomainID | Out | A pointer to where to return the QoS Domain ID. A null pointer indicates that the Qos Domain ID is not to be returned |
| uint16_t * | blockNumber | Out | A pointer to where to return the block number. A null pointer indicates that the block number is not to be returned |
| uint32_t * | ADUOffset | Out | A pointer to where to return the ADU Offset. A null pointer indicates that the ADU Offset is not to be returned |
Return value of SEFParseFlashAddress
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFCreateFlashAddress
struct SEFFlashAddress SEFCreateFlashAddress(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID, uint16_t blockNumber, uint32_t ADUOffset)
This function is used to create an opaque flash address. A generated flash address may be rejected by the device if it specifies an illegal ADUOffset, a block number not owned by the QoSDomainID, or a QoSDomainID that has not been opened by the caller.
Parameters of SEFCreateFlashAddress
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| struct SEFQoSDomainID | QoSDomainID | In | The desired QoS Domain ID. |
| uint16_t | blockNumber | In | The desired block number. |
| uint32_t | ADUOffset | In | The desired ADU Offset. |
Return value of SEFCreateFlashAddress
| Type | Description |
|---|---|
| struct SEFFlashAddress | The generated flash address. |
SEFReleaseSuperBlock
struct SEFStatus SEFReleaseSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress)
Releases the specific Super Block to the free pool owned by the Virtual Device to which the specified QoS Domain belongs. The target superblock must have been assigned by a previous call to SEFAllocateSuperBlock() or as part of SEFWriteWithoutPhysicalAddress1(). The superblock must be closed, otherwise the call will fail.
See Also: struct SEFStatus
Parameters of SEFReleaseSuperBlock
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain of the Super Block |
| struct SEFFlashAddress | flashAddress | In | Physical address of the superblock to release |
Return value of SEFReleaseSuperBlock
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFAllocateSuperBlock
struct SEFStatus SEFAllocateSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress *flashAddress, uint32_t retention, enum SEFSuperBlockType type, const struct SEFAllocateOverrides *overrides)
Allocates a superblock that will be assigned to the specified QoS Domain and returns the physical address of this superblock. Any number of superblocks can be kept open for write for each QoS domain. These superblocks in turn can be used as part of the parameter set for SEFWriteWithoutPhysicalAddress(). When allocating a superblock, SEF intelligently selects a location in a manner designed to optimize the lifetime of flash memory and will return the physical address that was selected. Note that each open superblock will allocate a write buffer and therefore consume memory, so there is a tradeoff in the number of open superblocks and the amount of memory consumed. Required that the total ADUs in the domain be less than its flash quota. This can be known by summing the writableADUs of each superblock in the domain.
See Also: struct SEFStatus, SEFGetQoSDomainInformation()
Parameters of SEFAllocateSuperBlock
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFFlashAddress * | flashAddress | Out | The flash address of the allocated block |
| uint32_t | retention | In | Retention period in hours |
| enum SEFSuperBlockType | type | In | kForWrite, kForCopy or kForDeviceMetadata |
| const struct SEFAllocateOverrides * | overrides | In | Overrides to scheduler parameters; pointer can be null for none required. |
Return value of SEFAllocateSuperBlock
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. .info contains number of ADUs in allocated superblock |
SEFFlushSuperBlock
struct SEFStatus SEFFlushSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, uint32_t *distanceToEndOfSuperBlock)
Flushes the target superblock. This command causes all written data for the superblock that is still in the write buffer and not persisted to flash memory to be persisted to flash memory. The device will automatically append data if necessary to finish programming of all pending user data writes. This command will not return until any address change notifications for the superblock being flushed have been processed, ensuring that all previously tentative addresses are now permanent.
See Also: struct SEFStatus
Parameters of SEFFlushSuperBlock
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain of the Super Block |
| struct SEFFlashAddress | flashAddress | In | Physical address of the Super Block to be flushed. |
| uint32_t * | distanceToEndOfSuperBlock | Out | Indicates remaining size in ADU after this flush operation. May be NULL. |
Return value of SEFFlushSuperBlock
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFCloseSuperBlock
struct SEFStatus SEFCloseSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress)
Closes the target superblock. If there is remaining unwritten space in the superblock, that space will be padded with dummy data. This can be used by the FTL as a means of closing a superblock without invoking a Write command. This command will not return until all address change and superblock state change notifications for the superblock being closed have been processed, ensuring that all previously tentative addresses are now permanent.
See Also: struct SEFStatus
Parameters of SEFCloseSuperBlock
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain of the Super Block |
| struct SEFFlashAddress | flashAddress | In | Physical address of the Super Block to move to Closed state by filling data |
Return value of SEFCloseSuperBlock
| Type | Description |
|---|---|
| struct SEFStatus | Status and info summarizing result. |
SEFPrepareBufferForNamelessCopy
void* SEFPrepareBufferForNamelessCopy(struct SEFCopySource *copySource, const struct SEFUserAddressFilter *filter, uint32_t numAddressChangeRecords, struct SEFAddressChangeRequest **addressChangeInfo)
This function allocates a data buffer SEFNamelessCopy(). It initializes filter parameters and returns pointers into members of copySource and addressChangeInfo.
Parameters of SEFPrepareBufferForNamelessCopy
| Type | Name | Direction | Description |
|---|---|---|---|
| struct SEFCopySource * | copySource | In | Description of copy source; format and arraysize MUST be initialized. The validBitmap pointer or flashAddressList pointer will be set by this function. |
| const struct SEFUserAddressFilter * | filter | In | Pointer to filter parameters, may be null for no filtering. This function will set the filter fields in the buffer. |
| uint32_t | numAddressChangeRecords | In | Size of addressChangeRequest userAddress array |
| struct SEFAddressChangeRequest ** | addressChangeInfo | Out | A pointer to pointer to the address change info within the buffer (set by this function) |
Return value of SEFPrepareBufferForNamelessCopy
| Type | Description |
|---|---|
| void * | Pointer to allocated buffer or NULL if error |
SEFFreeBufferForNamelessCopy
void SEFFreeBufferForNamelessCopy(void *copyContext)
Frees the buffer allocated with SEFPrepareBufferForNamelessCopy().
Parameters of SEFFreeBufferForNamelessCopy
| Type | Name | Direction | Description |
|---|---|---|---|
| void * | copyContext | In | A pointer to the memory to free |
SEFReleaseSuperBlockAsync
void SEFReleaseSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFReleaseSuperBlockIOCB *iocb)
This function is the asynchronous version of SEFReleaseSuperBlock().
See Also: SEFReleaseSuperBlock()
Parameters of SEFReleaseSuperBlockAsync
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFReleaseSuperBlockIOCB * | iocb | In/Out | For asynchronous response from SEF Library Unused fields should be set to 0. |
SEFAllocateSuperBlockAsync
void SEFAllocateSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFAllocateSuperBlockIOCB *iocb)
This function is the asynchronous version of SEFAllocateSuperBlock().
See Also: SEFAllocateSuperBlock()
Parameters of SEFAllocateSuperBlockAsync
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFAllocateSuperBlockIOCB * | iocb | In/Out | For asynchronous response from SEF Library Unused fields should be set to 0. |
SEFCloseSuperBlockAsync
void SEFCloseSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFCloseSuperBlockIOCB *iocb)
This function is the asynchronous version of SEFCloseSuperBlock(). kSuperblockStateChanged will have been sent before the completion routine is called and the iocb is marked as done.
See Also: SEFCloseSuperBlock()
Parameters of SEFCloseSuperBlockAsync
| Type | Name | Direction | Description |
|---|---|---|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFCloseSuperBlockIOCB * | iocb | In/Out | For asynchronous response from SEF Library |