SEF FTL Public API
SEFBlockIOType
Type of i/o in a SEFMultiContext.
Members of SEFBlockIOType
| Member | Description |
|---|
| kSEFRead | Performs a read operation |
| kSEFWrite | Performs a write operation |
SEFBlockIOFlags
I/O flags in a SEFMultiContext.
Members of SEFBlockIOFlags
| Member | Description |
|---|
| kSEFBlockIOFlagNotifyBufferRelease | Buffer lifetime is controlled by caller |
SEFBlockNotifyType
Event types for SEFBlockNotify.
Members of SEFBlockNotifyType
| Member | Description |
|---|
| kSefBlockNotifyGCDown | GC can no longer make progress, write I/O will fail |
| kSefBlockNotifyBufferRelease | A portion of an I/O buffer can be released |
SEFBlockConfig
struct SEFStatus SEFBlockConfig(uint16_t SEFUnitIndex, struct SEFQoSDomainID QoSDomainID, struct SEFBlockConfig *config)
This function is used to configure the SEF Block Module.
It configures freshly created QoS domains so they can used as a SEF Block Module domain. It sets the number of QoS domains and the amount of over provisioning to use. Once these values are set, they cannot be changed without erasing or recreating the QoS domains.
A QoS domain must be configured as a SEF Block Module domain before calling SEFBlockModuleInit().
See Also: SEFBlockInit()
Parameters of SEFBlockConfig
| Type | Name | Direction | Description |
|---|
| uint16_t | SEFUnitIndex | In | The index of the SEF Unit; the index is zero-based |
| struct SEFQoSDomainID | QoSDomainID | In | QoS Domain ID |
| struct SEFBlockConfig* | config | In | A pointer to an instance of SEFBlockConfig, for config settings |
Return value of SEFBlockConfig
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFBlockConfig
| Error Value | Description |
|---|
| -EINVAL | Invalid over provisioning percentage |
| -EEXIST | The device is already configured, can not reconfigure a pre-configured device |
| -EBADF | The block module was not shutdown cleanly; Consider running Check Disk |
SEFBlockInit
struct SEFStatus SEFBlockInit(uint16_t SEFUnitIndex, struct SEFQoSDomainID QoSDomainID, struct SEFBlockOption *options, SEFBlockHandle *blockHandle)
This function is used to get a SEFBlockModuleHandle for issuing I/O.
The QoS domain must be configured as a SEF Block Module domain using SEFBlockConfig() before calling SEFBlockInit(). Configuration only needs to be done once.
See Also: SEFBlockConfig()
Parameters of SEFBlockInit
| Type | Name | Direction | Description |
|---|
| uint16_t | SEFUnitIndex | In | The index of the SEF Unit; the index is zero-based |
| struct SEFQoSDomainID | QoSDomainID | In | QoS Domain ID |
| struct SEFBlockOption* | options | In | A pointer to an instance of SEFBlockOption, for runtime options |
| SEFBlockHandle * | blockHandle | In | A pointer to the SEF Block handle to be used for access to the block instance |
Return value of SEFBlockInit
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFBlockInit
| Error Value | Description |
|---|
| -EINVAL | Invalid log level |
| -EBADF | The block module was not shutdown cleanly; Consider running Check Disk |
| -ENOENT | Block layer has not been configured with SEFBlockConfig() |
SEFBlockMount
struct SEFStatus SEFBlockMount(SEFBlockHandle blockHandle)
This function mounts the FTL configured domain if not already mounted.
It's required to be called before calling SEFBlockIO() when SEFBlockInit() was called with the option delayMount set to true. Calling it when it's not required has no effect.
See Also: SEFBlockInit(), SEFBlockIO()
Parameters of SEFBlockMount
| Type | Name | Direction | Description |
|---|
| SEFBlockHandle | blockHandle | In | SEF Block handle to be used for access to the block instance |
Return value of SEFBlockMount
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
SEFBlockGetInfo
void SEFBlockGetInfo(SEFBlockHandle blockHandle, struct SEFBlockInfo *info)
This function returns size information about a block device.
The function requires the block layer to be initialized before it is called.
Parameters of SEFBlockGetInfo
| Type | Name | Direction | Description |
|---|
| SEFBlockHandle | blockHandle | In | SEF Block handle to be used for access to the block instance |
| struct SEFBlockInfo* | info | Out | SEFBlockInfo struct to fill with data |
SEFBlockIO
struct SEFStatus SEFBlockIO(struct SEFMultiContext *context)
This function is used to perform I/O commands.
Parameters of SEFBlockIO
Return value of SEFBlockIO
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFBlockIO
| Error Value | Description |
|---|
| -EINVAL | The input parameters are invalid; either Scatter gather list is too small or I/O exceeds the device capacity |
| -ENOPROTOOPT | FTL is either not initialized or shutting down, failing I/O |
| -EBUSY | I/o context p appears to be in use |
| -ECANCELED | GC shutdown, inflight writes canceled |
SEFBlockTrim
struct SEFStatus SEFBlockTrim(SEFBlockHandle blockHandle, int64_t lba, int32_t lbc)
This function is used to discard or TRIM LBAs that are no longer needed by the application.
Parameters of SEFBlockTrim
| Type | Name | Direction | Description |
|---|
| SEFBlockHandle | blockHandle | In | SEF Block handle to be used for access to the block instance |
| int64_t | lba | In | Logical block address |
| int32_t | lbc | In | Logical block count |
Return value of SEFBlockTrim
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFBlockTrim
| Error Value | Description |
|---|
| -ENOTBLK | The Block context is not valid |
| -EINVAL | The LBA or LBC is not valid |
| -EIO | Was unable to trim; the Info would indicate LBC that wasn't completed |
SEFBlockCancel
struct SEFStatus SEFBlockCancel(struct SEFMultiContext *context)
Requests the passed in I/O be canceled.
It's the caller's responsibility to ensure that the context is valid for the duration of the call. Because of internal race conditions, the call may fail and yet still cancel the I/O. Also possible is the function returns success, yet the I/O completes without error instead of a canceled I/O error.
Parameters of SEFBlockCancel
Return value of SEFBlockCancel
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFBlockCancel
| Error Value | Description |
|---|
| -ENOENT | The I/O was not found in the any queues |
SEFBlockCheck
struct SEFStatus SEFBlockCheck(SEFBlockHandle blockHandle, int shouldRepair)
This function is used to check if the stored data and metadata match.
Moreover, it is capable of repairing the device. To create a blockHandle for a device that won't mount, call SEFBlockInit() with the delayMount option set to true.
Parameters of SEFBlockCheck
| Type | Name | Direction | Description |
|---|
| SEFBlockHandle | blockHandle | In | A pointer to the SEF Block handle to be used for access to the block instance. |
| int | shouldRepair | In | Should the block module be repaired if it is faulty? 1 denotes true |
Return value of SEFBlockCheck
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. An error is returned if the device is faulty. |
SEFBlockCleanup
struct SEFStatus SEFBlockCleanup(SEFBlockHandle *blockHandle)
This function is used to clean up the SEF Block Module by freeing up memory and stopping all related functionality.
Parameters of SEFBlockCleanup
| Type | Name | Direction | Description |
|---|
| SEFBlockHandle * | blockHandle | In | A pointer to the SEF Block handle to be used for access to the block instance |
Return value of SEFBlockCleanup
| Type | Description |
|---|
| struct SEFStatus | Status and info summarizing result. |
Return values of SEFBlockCleanup
| Error Value | Description |
|---|
| -ENODATA | The input block handle is not valid |
SEFMultiContext
I/O request for SEFBlockIO()
Members of SEFMultiContext
| Type | Name | Description |
|---|
| SEFBlockHandle | blockHandle | SEF Block handle to be used for access to the block instance |
| struct SEFMultiContext* | parent | A pointer to an instance of SEFMultiContext used for compound operations |
| void(*)(struct SEFMultiContext *) | completion | The function that is called when the transaction is completed |
| void * | arg | A pointer that can be used by caller for any reason |
| uint64_t | lba | Logical block address |
| uint32_t | lbc | Logical block count |
| uint8_t | ioType | enum SEFBlockIOType that needs to be performed |
| uint8_t | flags | I/O flags enum SEFBlockIOFlags |
| uint8_t | readQueue | kSEFRead queue override when valid |
| uint16_t | ioWeight | I/O weight to override when non-zero |
| struct iovec* | iov | A pointer to the scatter/gather list |
| size_t | iovOffset | Starting byte offset into iov array |
| int | iovcnt | The number of elements in the scatter/gather list |
| uint16_t | qosIndex | 0 based, used for multi-domain FTL |
| struct SEFPlacementID | placementID | Placement ID for writes |
| uint32_t | numLbl | Num logical blocks left in the super block |
| atomic_int | transferred | Counter denoting number of bytes transferred for the transaction |
| atomic_int | count | Reference count, I/O is completed -> 0 |
| atomic_int | error | First error for the transaction |
| int | cancel | Set to indicate cancel in progress |
SEFBlockNotify
Event data sent to a client's notification function.
The notification function is set when SEFBlockInit() is called.
Members of SEFBlockNotify
| Type | Name | Description |
|---|
| enum SEFBlockNotifyType | type | Type of notification |
| const struct iovec* | iov | Vector of buffers to release |
| int16_t | iovcnt | Count of buffers in iov |
SEFBlockOption
Init time options.
Initialization time options supplied to SEFBlockInit()
Members of SEFBlockOption
| Type | Name | Description |
|---|
| int | logLevel | Initial log level (Trace = 0 , Debug = 1, Info = 2, Error = 3, Fatal = 4) |
| LogHandle | logHandle | Use an external logger |
| const char * | instrumentationPath | The location for the Unix Domain Socket. Will replace the first two format specifier with UnitIndex and QoSDomainId. Defaults to /tmp/SEFFTLDomain.[UnitIndex].[QoSDomainId] |
| void * | notifyContext | User context passed to notifyFunc() |
| void(*)(struct SEFBlockNotify event, void *notifyContext) | notifyFunc | Set to receive notifications |
| bool | delayMount | When true, SEFBlockInit() delays mounting until SEFBlockMount() is called |
SEFBlockConfig
Configuration when calling SEFBlockConfig()
Members of SEFBlockConfig
| Type | Name | Description |
|---|
| int | overprovisioning | Percentage of over-provisioning (e.g., 20 for 20 percent) |
| int | unused0 | Unused member |
| int | numDomains | Number of domains to use for a block-device. 0 indicates all defined domains |
| struct SEFBlockOption | blockOption | Run time options while configuring |
SEFBlockInfo
Information about a block-module device.
Members of SEFBlockInfo
| Type | Name | Description |
|---|
| struct SEFADUsize | aduSize | Size of ADU and Meta |
| int16_t | numPlacementIDs | Number of Placement IDs |
| int | superBlockSize | Maximum number of ADUs in a super block |
| int | superPageSize | Number of ADUs in a super page |
| int | flashWriteSize | Number of ADUs to write to avoid padding (e.g., sync write) |
| uint64_t | capacity | Capacity in ADUs |
| int | overprovisioning | Percentage of over-provisioning (e.g., 20 for 20 percent) |
| int | numDomains | Number of domains the FTL covers |