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: SEFLibraryCleanup()
Return value of SEFLibraryInit
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFLibraryInit
| Error Value | Description |
|---|
| 0 | The info member returns the number of units |
SEFGetHandle
SEFHandle SEFGetHandle(uint16_t index)
Returns a handle to the SEF Unit at the specified index (zero based)
Parameters of SEFGetHandle
| Type | Name | Direction | Description |
|---|
| uint16_t | 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.
Every successful call to SEFLibraryInit() must be balanced with a call to SEFLibraryCleanup().
Note: When the returned status error and info fields are zero, all open handles are closed, invalidated and are unusable.
See Also: SEFLibraryInit()
Return value of SEFLibraryCleanup
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFLibraryCleanup
| Error Value | Description |
|---|
| 0 | The info field is the library's reference count. |
| -ENODEV | The SEF Library was not initialized |
| -EWOULDBLOCK | This function cannot be called on a callback thread |
const struct SEFInfo* SEFGetInformation(SEFHandle sefHandle)
Gets device information.
Returns ADU size(s), number of channels, number of dies, and other associated information. Dynamic values are refreshed just before the structure is returned.
| Type | Name | Direction | Description |
|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| Type | Description |
|---|
| const struct SEFInfo * | SEFInfo struct or NULL if sefHandle is NULL. |
SEFListVirtualDevices
struct SEFStatus SEFListVirtualDevices(SEFHandle sefHandle, struct SEFVirtualDeviceList *list, int bufferSize)
Returns a list of the defined Virtual Devices.
When list is NULL or insufficiently sized or bufferSize is 0, status.info returns the minimum buffer size for the complete list. The data that fits in an insufficiently sized buffer is valid but incomplete. The buffer must be at least the size of the list structure.
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. |
Return values of SEFListVirtualDevices
| Error Value | Description |
|---|
| -ENODEV | The SEF Handle is not valid |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| 0 | info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 |
SEFListQoSDomains
struct SEFStatus SEFListQoSDomains(SEFHandle sefHandle, struct SEFQoSDomainList *list, int bufferSize)
Returns a list of the defined QoS Domains.
When list is NULL or insufficiently sized or bufferSize is 0, status.info returns the minimum buffer size for the complete list. The data that fits in an insufficiently sized buffer is valid but incomplete. The buffer must be at least the size of the list structure.
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. |
Return values of SEFListQoSDomains
| Error Value | Description |
|---|
| -ENODEV | The SEF Handle is not valid |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| 0 | info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 |
static uint32_t SEFGetUserAddressMeta(struct SEFUserAddress userAddress)
| Type | Description |
|---|
| uint32_t | Returns meta value from a user address |
SEFGetUserAddressLba
static uint64_t SEFGetUserAddressLba(struct SEFUserAddress userAddress)
Parameters of SEFGetUserAddressLba
Return value of SEFGetUserAddressLba
| Type | Description |
|---|
| uint64_t | Returns LBA value from a user address |
SEFParseUserAddress
static void SEFParseUserAddress(struct SEFUserAddress userAddress, uint64_t *lba, uint32_t *meta)
Return LBA and meta values from a user address.
Parameters of SEFParseUserAddress
| Type | Name | Direction | Description |
|---|
| struct SEFUserAddress | userAddress | In | User address to be parsed |
| uint64_t * | lba | Out | Lba parsed from the user address |
| uint32_t * | meta | Out | Meta parsed from the user address |
SEFCreateUserAddress
static struct SEFUserAddress SEFCreateUserAddress(uint64_t lba, uint32_t meta)
Creates a user address from lba and meta values.
Parameters of SEFCreateUserAddress
| Type | Name | Direction | Description |
|---|
| uint64_t | lba | In | lba to be used to generate user address (40 bits) |
| uint32_t | meta | In | meta to be used to generate user address (24 bits) |
Return value of SEFCreateUserAddress
| Type | Description |
|---|
| struct SEFUserAddress | Returns the user address created from lba and meta values |
SEFCreateVirtualDevices
struct SEFStatus SEFCreateVirtualDevices(SEFHandle sefHandle, uint16_t numVirtualDevices, struct SEFVirtualDeviceConfig *const virtualDeviceConfigs[])
Creates the Virtual Devices and allocates physical resources.
Configuring the virtual devices for a SEF Unit is only done during pre-production. Once the flash of a SEF Unit has been written to, it is not possible to change the Virtual Device configuration.
Configuration is accomplished by supplying a array of pointers to virtualDeviceConfigs. Each Virtual Device being configured will have a single array entry. Each of those entries contains a list of die IDs that will define a specific Virtual Device. The superBlockDies in the config must be 0 or evenly divide into the number of dies specified by the die list.
Valid die IDs start at 0 and are less than the total number of dies in a SEF Unit. The total number of dies is equal to SEFInfo::numBanks SEFInfo::numChannels. The die ID of a die at channel CH, bank BNK, is equal to CH + BNKSEFInfo::numChannels. The die IDs in the dieList in a virtual device configuration must be in ascending order. A die ID can only be used in at most one Virtual Device configuration. If a die is not included in any Virtual Device configuration, it will be lost capacity that can never be used.
See Also: SEFGetInformation()
Parameters of SEFCreateVirtualDevices
| Type | Name | Direction | Description |
|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
| uint16_t | numVirtualDevices | In | Number of entries in virtualDeviceConfigs |
| const struct SEFVirtualDeviceConfig[]* | virtualDeviceConfigs | In | Pointers to configurations describing how to create the virtual devices |
Return value of SEFCreateVirtualDevices
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. Returns 0 on success and negative value on error. |
Return values of SEFCreateVirtualDevices
| Error Value | Description |
|---|
| -ENODEV | The SEF Handle is not valid |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| -EACCES | You don't have the needed permission to perform this operation |
SEFSetNumberOfPSLCSuperBlocks
struct SEFStatus SEFSetNumberOfPSLCSuperBlocks(SEFVDHandle vdHandle, uint32_t numPSLCSuperBlocks)
Sets the number of pSLC super blocks.
This defines the number of regular super blocks which are transformed to use as pSLC super blocks. Because it applies to all the dies in the Virtual Device, the value must be a multiple of the ratio of the number of dies in the Virtual Device to the number of configured dies per super block.
Once super blocks have been allocated from the Virtual Device, it may not be possible to modify the number of pSLC super blocks and the call will fail with -ENOSPC.
Parameters of SEFSetNumberOfPSLCSuperBlocks
| Type | Name | Direction | Description |
|---|
| SEFVDHandle | vdHandle | In | Handle to the SEF Unit |
| uint32_t | numPSLCSuperBlocks | In | The number of pSLC super blocks to set |
Return values of SEFSetNumberOfPSLCSuperBlocks
| Error Value | Description |
|---|
| 0 | The number of pSLC super blocks has been set |
| -ENODEV | The SEF Handle is not valid |
| -ENOSPC | No space is available for pSLC super blocks |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid. |
SEFGetVirtualDeviceUsage
struct SEFStatus SEFGetVirtualDeviceUsage(SEFVDHandle vdHandle, struct SEFVirtualDeviceUsage *usage)
Returns Virtual Device usage.
Parameters of SEFGetVirtualDeviceUsage
Return value of SEFGetVirtualDeviceUsage
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFGetVirtualDeviceUsage
| Error Value | Description |
|---|
| -ENODEV | The Virtual Device Handle is not valid |
| -EPERM | The Virtual Device Handle is not open |
SEFGetDieList
struct SEFStatus SEFGetDieList(SEFHandle sefHandle, struct SEFVirtualDeviceID virtualDeviceID, struct SEFDieList *list, int bufferSize)
Returns Virtual Device die list.
When list is NULL or insufficiently sized or bufferSize is 0, status.info returns the minimum buffer size for the complete list. The data that fits in an insufficiently sized buffer is valid but incomplete. The buffer must be at least the size of the list structure.
Parameters of SEFGetDieList
Return value of SEFGetDieList
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFGetDieList
| Error Value | Description |
|---|
| -ENODEV | The SEF Handle is not valid |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| 0 | info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 |
struct SEFStatus SEFGetVirtualDeviceInformation(SEFHandle sefHandle, struct SEFVirtualDeviceID virtualDeviceID, struct SEFVirtualDeviceInfo *info, int bufferSize)
Returns Virtual Device information.
When info is NULL or insufficiently sized or bufferSize is 0, status.info returns the minimum buffer size for the complete set of information. The data that fits in an insufficiently sized buffer is valid but incomplete. The buffer must be at least the size of the info structure.
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
| Error Value | Description |
|---|
| -ENODEV | The SEF Handle is not valid |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| 0 | info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 |
SEFSetVirtualDeviceSuspendConfig
struct SEFStatus SEFSetVirtualDeviceSuspendConfig(SEFVDHandle vdHandle, const struct SEFVirtualDeviceSuspendConfig *config)
Sets the suspend configuration for a Virtual Device.
Parameters of SEFSetVirtualDeviceSuspendConfig
Return values of SEFSetVirtualDeviceSuspendConfig
| Error Value | Description |
|---|
| 0 | The suspend configuration has been set |
| -ENODEV | The SEF Handle is not valid |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid. |
SEFCreateQoSDomain
struct SEFStatus SEFCreateQoSDomain(SEFVDHandle vdHandle, struct SEFQoSDomainID QoSDomainID, uint64_t flashCapacity, uint64_t pSLCFlashCapacity, int ADUindex, enum SEFAPIIdentifier api, enum SEFDefectManagementMethod defectStrategy, enum SEFErrorRecoveryMode recovery, const char *encryptionKey, uint16_t numPlacementIDs, uint16_t maxOpenSuperBlocks, uint8_t defaultReadQueue, struct SEFWeights weights)
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. The actual flash capacity reserved in the Virtual Device is typically larger than what was requested by 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 | pSLCFlashCapacity | In | Number of required/reserved pSLC adus |
| int | ADUindex | In | Index into the ADUSize[] array in SEFInfo returned by SEFGetInformation() to select the data and metadata sizes of an ADU. |
| enum SEFAPIIdentifier | api | In | Specifies the API Identifier for this QoS Domain |
| enum SEFDefectManagementMethod | defectStrategy | In | Specifies the defect management strategy for the QoS Domain |
| enum SEFErrorRecoveryMode | recovery | In | Specifies the recovery mode for this QoS Domain |
| const char * | encryptionKey | In | NULL for disabled. |
| uint16_t | numPlacementIDs | In | The maximum number of Placement IDs that can be placed on the QoS Domain. |
| uint16_t | maxOpenSuperBlocks | In | The maximum number super blocks that can be open in a QoS Domain. If less than numPlacementIDs it will be set to numPlacementIDs+2. This affects resource/memory usage in the device. |
| uint8_t | defaultReadQueue | In | The default read queue assignment, 0 through numReadQueues-1 defined for the Virtual Device. |
| struct SEFWeights | weights | In | Weight values for each type of write I/O operations. |
Return value of SEFCreateQoSDomain
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFCreateQoSDomain
| Error Value | Description |
|---|
| -ENODEV | The Virtual Device Handle is not valid |
| -EPERM | The Virtual Device Handle is not open |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| -ENOMEM | The library was unable to allocate needed structures. status.info is set to the type of capacity that caused the failure (kForWrite or kForPSLCWrite) |
SEFSetQoSDomainCapacity
struct SEFStatus SEFSetQoSDomainCapacity(SEFVDHandle vdHandle, struct SEFQoSDomainID QoSDomainID, enum SEFSuperBlockType type, uint64_t flashCapacity, uint64_t flashQuota)
Resets the capacity of a QoS Domain.
Sets a new capacity and quota for the QoS Domain. When the flashQuota is less the flashCapacity or the used flashedCapacity, it will be set to the larger of the two.
Parameters of SEFSetQoSDomainCapacity
| Type | Name | Direction | Description |
|---|
| SEFVDHandle | vdHandle | In | Handle to the Virtual Device |
| struct SEFQoSDomainID | QoSDomainID | In | QoS Domain ID |
| enum SEFSuperBlockType | type | In | Type of super block |
| uint64_t | flashCapacity | In | Number of required/reserved ADUs for the specified type of super block |
| uint64_t | flashQuota | In | Number of ADUs that can be allocated for the specified type of super block |
Return value of SEFSetQoSDomainCapacity
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFSetQoSDomainCapacity
| Error Value | Description |
|---|
| -ENODEV | The Virtual Device Handle is not valid |
| -EPERM | The Virtual Device Handle is not open |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| -ENOSPC | The Virtual Device does not have enough space |
SEFSetRootPointer
struct SEFStatus SEFSetRootPointer(SEFQoSHandle qosHandle, int index, struct SEFFlashAddress value)
Sets the value of a QoSDomain root 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 SEFReadWithPhysicalAddress() using a flash address of just the root pointer index as the ADU oftset with zeros for the QoS DomainId and super block index.
See Also: SEFReadWithPhysicalAddress()
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. |
Return values of SEFSetRootPointer
| 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 |
SEFSetReadDeadline
struct SEFStatus SEFSetReadDeadline(SEFQoSHandle qosHandle, enum SEFDeadlineType deadline)
Sets target QoS Domain's read deadline policy.
See Also: 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. |
Return values of SEFSetReadDeadline
| Error Value | Description |
|---|
| -ENODEV | The QoS Domain handle is not valid |
| -EPERM | The QoS Domain Handle is not open |
SEFGetSuperBlockList
struct SEFStatus SEFGetSuperBlockList(SEFQoSHandle qosHandle, struct SEFSuperBlockList *list, int bufferSize)
Returns a list of super blocks assigned to the QoS Domain.
When list is NULL or insufficiently sized or bufferSize is 0, status.info returns the minimum buffer size for the complete list. The data that fits in an insufficiently sized buffer is valid but incomplete. The buffer must be at least the size of the list structure.
Parameters of SEFGetSuperBlockList
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFSuperBlockList* | list | Out | List of super block records |
| int | bufferSize | In | Buffer size |
Return value of SEFGetSuperBlockList
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFGetSuperBlockList
| 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 |
| 0 | info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 |
SEFGetQoSDomainInformation
struct SEFStatus SEFGetQoSDomainInformation(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID, struct SEFQoSDomainInfo *info)
Returns QoS Domain information, including the list of super blocks assigned to the QoS Domain.
Parameters of SEFGetQoSDomainInformation
Return value of SEFGetQoSDomainInformation
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFGetQoSDomainInformation
| Error Value | Description |
|---|
| -ENODEV | The SEF handle is not valid |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| 0 | SEFQoSDomainInfo was successfully returned. |
SEFGetReuseList
struct SEFStatus SEFGetReuseList(SEFQoSHandle qosHandle, struct SEFWearInfo *info, int bufferSize)
Returns list of super blocks to process for wear-leveling.
Used in support of the implementation of a host-specified wear leveling policy. The SEF Unit has a built in wear-leveling mechanism. It returns closed blocks in the order they should be released if subject to the host-specified wear leveling policy.
When info is NULL or insufficiently sized or bufferSize is 0, status.info returns the minimum buffer size for the complete set of information. The data that fits in an insufficiently sized buffer is valid but incomplete. The buffer must be at least the size of the info structure.
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. |
Return values of SEFGetReuseList
| 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 |
| 0 | info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 |
SEFGetRefreshList
struct SEFStatus SEFGetRefreshList(SEFQoSHandle qosHandle, struct SEFRefreshInfo *info, int bufferSize)
Returns a list of blocks that have encountered ECC corrections.
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.
When info is NULL or insufficiently sized or bufferSize is 0, status.info returns the minimum buffer size for the complete set of information. The data that fits in an insufficiently sized buffer is valid but incomplete. The buffer must be at least the size of the info structure.
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. |
Return values of SEFGetRefreshList
| 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 |
| 0 | info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 |
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 (SEFCheckSuperBlock) 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.
When info is NULL or insufficiently sized or bufferSize is 0, status.info returns the minimum buffer size for the complete set of information. The data that fits in an insufficiently sized buffer is valid but incomplete. The buffer must be at least the size of the info structure.
See Also: SEFCheckSuperBlock()
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. |
Return values of SEFGetCheckList
| 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 |
| 0 | info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 |
SEFGetUserAddressList
struct SEFStatus SEFGetUserAddressList(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, struct SEFUserAddressList *list, int bufferSize)
Returns the user address list in terms of its underlying super blocks.
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.
ADUs that have not been written return a user address equal to SEFUserAddressIgnore.
When list is NULL or insufficiently sized or bufferSize is 0, status.info returns the minimum buffer size for the complete list. The data that fits in an insufficiently sized buffer is valid but incomplete. The buffer must be at least the size of the list structure.
Parameters of SEFGetUserAddressList
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFFlashAddress | flashAddress | In | Flash address of the super block |
| struct SEFUserAddressList* | 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. |
Return values of SEFGetUserAddressList
| 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 |
| 0 | info field returns the minimum buffer size if the buffer is insufficient or NULL; otherwise, 0 |
SEFGetSuperBlockInfo
struct SEFStatus SEFGetSuperBlockInfo(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, int getDefectMap, struct SEFSuperBlockInfo *info)
Returns information corresponding to the super block.
Parameters of SEFGetSuperBlockInfo
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFFlashAddress | flashAddress | In | Flash address of the super block |
| int | getDefectMap | In | When non-zero populates the defectBitmap member of SEFSuperBlockInfo. See SEFSuperBlockInfo for information on the size of defectBitmap |
| struct SEFSuperBlockInfo* | info | Out | Buffer for storing super block information |
Return value of SEFGetSuperBlockInfo
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFGetSuperBlockInfo
| 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 |
SEFCheckSuperBlock
struct SEFStatus SEFCheckSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress)
This is a read patrol operation which is used in conjunction with SEFGetCheckList and the kRequirePatrol QoS Notification.
Patrol reads don't use the scheduling queues and are issued as soon as possible. Any actions required by the result of the patrol will generate the appropriate QoS Notification.
See Also: SEFGetCheckList()
Parameters of SEFCheckSuperBlock
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| struct SEFFlashAddress | flashAddress | In | Flash address of the super block to be checked |
Return value of SEFCheckSuperBlock
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFCheckSuperBlock
| Error Value | Description |
|---|
| 0 | The super block is checked |
| -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 |
SEFDeleteVirtualDevices
struct SEFStatus SEFDeleteVirtualDevices(SEFHandle sefHandle)
Deletes the Virtual Devices and allocated physical resources.
Deleting virtual devices for a SEF Unit can only be done during pre-production. Once the flash of a SEF Unit has been written to, it is not possible to delete the Virtual Device configuration.
Parameters of SEFDeleteVirtualDevices
| Type | Name | Direction | Description |
|---|
| SEFHandle | sefHandle | In | Handle to the SEF Unit |
Return value of SEFDeleteVirtualDevices
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. Returns 0 on success and negative value on error. |
Return values of SEFDeleteVirtualDevices
| Error Value | Description |
|---|
| -ENODEV | The SEF Handle is not valid |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| -EACCES | You don't have the needed permission to perform this operation |
| -ENOTEMPTY | At least one QoS Domain exists |
| -EBUSY | The Virtual Device is in use and not all the handles are closed |
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 super blocks are returned to the Virtual Device's free pool.
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. |
Return values of SEFDeleteQoSDomain
| Error Value | Description |
|---|
| -ENODEV | The SEF handle is not valid |
| -EINVAL | The QoS Domain ID is not valid |
| -EACCES | You don't have the needed permission to perform this operation |
| -EBUSY | The QoS Domain is in use and not all the handles are closed |
SEFResetEncryptionKey
struct SEFStatus SEFResetEncryptionKey(SEFVDHandle vdHandle, struct SEFQoSDomainID QoSDomainID)
Resets the encryption key for a QoS Domain.
Parameters of SEFResetEncryptionKey
| Type | Name | Direction | Description |
|---|
| SEFVDHandle | vdHandle | In | Handle to the Virtual Drive |
| struct SEFQoSDomainID | QoSDomainID | In | QoS Domain ID |
Return value of SEFResetEncryptionKey
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFResetEncryptionKey
| Error Value | Description |
|---|
| -ENODEV | The Virtual Device handle is not valid |
| -EPERM | The Virtual Device handle is not open |
| -EINVAL | The QoS Domain Id is not valid |
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.
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. |
Return values of SEFOpenVirtualDevice
| Error Value | Description |
|---|
| -ENODEV | The SEF handle is not valid |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| -EACCES | You don't have the needed permission to perform this operation |
| -ENOMEM | The library was unable to allocate needed structures |
| -EALREADY | The Virtual Device is already open |
SEFCloseVirtualDevice
struct SEFStatus SEFCloseVirtualDevice(SEFVDHandle vdHandle)
Closes an open Virtual Device and shuts down associated event notification.
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. |
Return values of SEFCloseVirtualDevice
| Error Value | Description |
|---|
| -ENODEV | The Virtual Device handle is not valid |
| -EPERM | The Virtual Device Handle is not open |
| -EWOULDBLOCK | This function cannot be called on a callback thread |
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.
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. |
Return values of SEFOpenQoSDomain
| Error Value | Description |
|---|
| -ENODEV | The SEF handle is not valid |
| -EINVAL | The function parameter is not valid; info returns the parameter index that is not valid |
| -EACCES | You don't have the needed permission to perform this operation |
| -ENOMEM | The library was unable to allocate needed structures |
| -EALREADY | The QoS Domain is already open |
SEFCloseQoSDomain
struct SEFStatus SEFCloseQoSDomain(SEFQoSHandle qosHandle)
Closes an open QoS Domain.
This will close any open super blocks 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.
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. |
Return values of SEFCloseQoSDomain
| Error Value | Description |
|---|
| -ENODEV | The QoS Domain handle is not valid |
| -EPERM | The QoS Domain Handle is not open |
| -EWOULDBLOCK | This function cannot be called on a callback thread |
SEFGetQoSHandleProperty
struct SEFProperty SEFGetQoSHandleProperty(SEFQoSHandle qos, enum SEFPropertyID propID)
This function gets a property given a SEFQoSHandle.
Parameters of SEFGetQoSHandleProperty
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| enum SEFPropertyID | propID | In | The Property ID requested |
Return value of SEFGetQoSHandleProperty
| Type | Description |
|---|
| struct SEFProperty | Returns the property stored given the property ID; If an unknown property ID is passed in, the returned type of the property will be kSefPropertyTypeNull. If kSefPropertyPrivateData is not set, the returned type of the property will be kSefPropertyTypeNull. |
SEFSetQoSHandleProperty
struct SEFStatus SEFSetQoSHandleProperty(SEFQoSHandle qos, enum SEFPropertyID propID, struct SEFProperty value)
This function sets a property given a SEFQoSHandle.
The only settable property is kSefPropertyPrivateData.
Parameters of SEFSetQoSHandleProperty
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain |
| enum SEFPropertyID | propID | In | The Property ID being stored |
| struct SEFProperty | value | In | The value of the property being stored |
Return value of SEFSetQoSHandleProperty
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFSetQoSHandleProperty
| 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 |
SEFParseFlashAddress
struct SEFStatus SEFParseFlashAddress(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, struct SEFQoSDomainID *QoSDomainID, uint32_t *blockNumber, uint32_t *ADUOffset)
This function is used to extract info needed by FTL from an opaque flash address.
The QoS Domain ID of the passed in qosHandle does not have to match the QoS Domain ID of the passed in flash address. No validation is performed and the address is parsed as if it came from the QoS Domain of the passed in qosHandle. When they differ, it's up to the client to ensure the two different QoS Domain IDs are compatible. That is, the virtual devices they live in have the same value for superBlockDies.
Parameters of SEFParseFlashAddress
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to a QoS Domain to interpret/parse the flash address. May be NULL if only the QoSDomainID is being returned. |
| 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 |
| uint32_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(SEFQoSHandle qosHandle, struct SEFQoSDomainID QoSDomainID, uint32_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 super 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 |
|---|
| SEFQoSHandle | qosHandle | In | Handle of a QoS Domain to create a flash address for. |
| struct SEFQoSDomainID | QoSDomainID | In | The desired QoS Domain ID. It is not validated against the QoS Domain ID of the qosHandle. |
| uint32_t | blockNumber | In | The desired super block number. |
| uint32_t | ADUOffset | In | The desired ADU Offset. |
Return value of SEFCreateFlashAddress
| Type | Description |
|---|
| struct SEFFlashAddress | The generated flash address or the NULL flashAddress if the qosHandle is invalid. |
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 super block must have been assigned by a previous call to SEFAllocateSuperBlock() or as part of SEFWriteWithoutPhysicalAddress(). The super block may be in an open or closed state.
Parameters of SEFReleaseSuperBlock
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain of the super block |
| struct SEFFlashAddress | flashAddress | In | Flash address of the super block to release |
Return value of SEFReleaseSuperBlock
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFReleaseSuperBlock
| Error Value | Description |
|---|
| -ENODEV | The QoS Domain handle is not valid |
| -EPERM | The QoS Domain Handle is not open |
| -EFAULT | The Flash Address is not valid |
SEFAllocateSuperBlock
struct SEFStatus SEFAllocateSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress *flashAddress, enum SEFSuperBlockType type, const struct SEFAllocateOverrides *overrides)
Allocates a super block that will be assigned to the specified QoS Domain and returns the flash address of this super block.
The returned super block will be in the open state. These super blocks in turn can be used as part of the parameter set for the SEFNamlessCopy and SEFWriteWithoutPhysicalAddress functions. When allocating a super block, The SEF Unit intelligently selects a location in a manner designed to optimize the lifetime of flash memory and will return the flash address that was selected. Note that each open super block will allocate a write buffer and therefore consume memory, so there is a tradeoff in the number of open super blocks and the amount of memory consumed.
It's required that the total ADUs in the QoS Domain be less than its flash quota and its Virtual Device have an available super block. The ADUs in use by a QoS Domain can be known by summing the writableADUs of each super block in the QoS Domain.
See Also: SEFGetQoSDomainInformation()
Parameters of SEFAllocateSuperBlock
Return value of SEFAllocateSuperBlock
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFAllocateSuperBlock
| Error Value | Description |
|---|
| 0 | The info member contains number of ADUs in allocated super block |
| -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 |
SEFFlushSuperBlock
struct SEFStatus SEFFlushSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, uint32_t *distanceToEndOfSuperBlock)
Flushes the target super block.
This command causes all written data for the super block 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 all the data is persistent and all kAddressUpdate change notifications generated by the flush have been processed.
When a flush causes a super block to have no more writable ADUs, the super block will be closed and a QoS Domain notification of the close will be sent.
Parameters of SEFFlushSuperBlock
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain of the super block |
| struct SEFFlashAddress | flashAddress | In | Flash 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. |
Return values of SEFFlushSuperBlock
| 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 |
SEFCloseSuperBlock
struct SEFStatus SEFCloseSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress)
Closes the target super block.
If there is remaining unwritten space in the super block, that space will be padded with dummy data. This can be used by the FTL as a means of closing a super block without invoking a Write command.
This command will not return until all the data is persistent and all kAddressUpdate change notifications generated by the close have been processed ensuring that all addresses have either transitioned from tentative to permanent or have been updated.
Parameters of SEFCloseSuperBlock
| Type | Name | Direction | Description |
|---|
| SEFQoSHandle | qosHandle | In | Handle to the QoS Domain of the super block |
| struct SEFFlashAddress | flashAddress | In | Flash 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. |
Return values of SEFCloseSuperBlock
| Error Value | Description |
|---|
| 0 | The super block is was closed or was already closed |
| -ENODEV | The QoS Domain handle is not valid |
| -EPERM | The QoS Domain Handle is not open |
| -EFAULT | The Flash Address is not valid |
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 |