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

Usage Example

CLI

  ftl.c @ 120

  qos-domain.c @ 281

  sef-unit.c @ 89

  shell.c @ 1426

  virtual-device.c @ 228

---

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

Usage Example

CLI

  ftl.c @ 140

  qos-domain.c @ 305

  sef-unit.c @ 137

  sef-unit.c @ 183

  shell.c @ 227

  virtual-device.c @ 252

FTL

  die-stats.c @ 203

  sef-block-module.c @ 404

  sef-utils.c @ 48

---

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

Usage Example

CLI

  ftl.c @ 190

  qos-domain.c @ 331

  sef-unit.c @ 115

  shell.c @ 1525

  virtual-device.c @ 278

---

SEFGetInformation

const struct SEFInfo* SEFGetInformation(SEFHandle sefHandle) NONNULL(1)

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.

Parameters of SEFGetInformation

Type	Name	Direction	Description
SEFHandle	sefHandle	In	Handle to the SEF Unit

Return value of SEFGetInformation

Type	Description
const struct SEFInfo *	SEFInfo struct or NULL if sefHandle is NULL.

Usage Example

CLI

  ftl.c @ 165

  ftl.c @ 165

  qos-domain.c @ 313

  sef-unit.c @ 146

  sef-unit.c @ 191

  shell.c @ 489

  virtual-device.c @ 260

  virtual-device.c @ 1148

  virtual-device.c @ 1226

FTL

  die-stats.c @ 204

  sef-block-module.c @ 410

  sef-utils.c @ 55

  sef-utils.c @ 113

  sef-utils.c @ 244

---

SEFListVirtualDevices

struct SEFStatus SEFListVirtualDevices(SEFHandle sefHandle, struct SEFVirtualDeviceList *list, size_t bufferSize) NONNULL(1)

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
size_t	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

Usage Example

CLI

  virtual-device.c @ 780

  virtual-device.c @ 875

  sef-helper.c @ 135

---

SEFListQoSDomains

struct SEFStatus SEFListQoSDomains(SEFHandle sefHandle, struct SEFQoSDomainList *list, size_t bufferSize) NONNULL(1)

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
size_t	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

Usage Example

CLI

  qos-domain.c @ 506

  shell.c @ 494

  sef-helper.c @ 81

FTL

  sef-utils.c @ 172

---

SEFGetUserAddressMeta

static uint32_t SEFGetUserAddressMeta(struct SEFUserAddress userAddress)

Parameters of SEFGetUserAddressMeta

Type	Name	Direction	Description
struct SEFUserAddress	userAddress	In	User address to be parsed

Return value of SEFGetUserAddressMeta

Type	Description
uint32_t	Returns meta value from a user address

Usage Example

FTL

  data-tree-object.c @ 582

  data-tree-object.c @ 666

  flash-translation.c @ 564

  manual-copy.c @ 324

  sef-block-module.c @ 1971

  sef-notification.c @ 94

---

SEFGetUserAddressLba

static uint64_t SEFGetUserAddressLba(struct SEFUserAddress userAddress)

Parameters of SEFGetUserAddressLba

Type	Name	Direction	Description
struct SEFUserAddress	userAddress	In	User address to be parsed

Return value of SEFGetUserAddressLba

Type	Description
uint64_t	Returns LBA value from a user address

Usage Example

FTL

  data-tree-object.c @ 581

  data-tree-object.c @ 665

  flash-translation.c @ 325

  manual-copy.c @ 323

  sef-block-module.c @ 1933

  sef-block-module.c @ 1962

  sef-notification.c @ 102

---

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

Usage Example

FTL

  flash-translation.c @ 715

---

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

Usage Example

FTL

  data-tree-object.c @ 250

  data-tree-object.c @ 313

  data-tree-object.c @ 396

  data-tree-object.c @ 581

  data-tree-object.c @ 665

  manual-copy.c @ 322

  sef-block-module.c @ 1574

  sef-block-module.c @ 1844

  sef-block-module.c @ 1970

---

SEFCreateVirtualDevices

struct SEFStatus SEFCreateVirtualDevices(SEFHandle sefHandle, uint16_t numVirtualDevices, struct SEFVirtualDeviceConfig *const virtualDeviceConfigs[]) NONNULL(1)

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 + BNK*SEFInfo::numChannels. 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 cannot 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

Usage Example

CLI

  virtual-device.c @ 1368

---

SEFSetNumberOfPSLCSuperBlocks

struct SEFStatus SEFSetNumberOfPSLCSuperBlocks(SEFVDHandle vdHandle, uint32_t numPSLCSuperBlocks) NONNULL(1)

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.

Usage Example

CLI

  virtual-device.c @ 1563

---

SEFGetVirtualDeviceUsage

struct SEFStatus SEFGetVirtualDeviceUsage(SEFVDHandle vdHandle, struct SEFVirtualDeviceUsage *usage) NONNULL(1

Returns Virtual Device usage.

Parameters of SEFGetVirtualDeviceUsage

Type	Name	Direction	Description
SEFVDHandle	vdHandle	In	Handle to the Virtual Device
struct SEFVirtualDeviceUsage*	usage	Out	Buffer for storing VD usage

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

Usage Example

CLI

  virtual-device.c @ 966

---

SEFGetDieList

struct SEFStatus SEFGetDieList(SEFHandle sefHandle, struct SEFVirtualDeviceID virtualDeviceID, struct SEFDieList *list, size_t bufferSize) NONNULL(1)

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

Type	Name	Direction	Description
SEFHandle	sefHandle	In	Handle to the SEF Unit
struct SEFVirtualDeviceID	virtualDeviceID	In	Virtual Device ID
struct SEFDieList*	list	Out	Buffer for storing VD information
size_t	bufferSize	In	Buffer size

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

Usage Example

CLI

  virtual-device.c @ 646

  virtual-device.c @ 920

  virtual-device.c @ 1067

FTL

  sef-utils.c @ 90

---

SEFGetVirtualDeviceInformation

struct SEFStatus SEFGetVirtualDeviceInformation(SEFHandle sefHandle, struct SEFVirtualDeviceID virtualDeviceID, struct SEFVirtualDeviceInfo *info, size_t bufferSize) NONNULL(1)

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.

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
size_t	bufferSize	In	Buffer size

Return value of SEFGetVirtualDeviceInformation

Type	Description
struct SEFStatus	Status and info summarizing result.

Return values of SEFGetVirtualDeviceInformation

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

Usage Example

CLI

  qos-domain.c @ 876

  qos-domain.c @ 1546

  virtual-device.c @ 810

  virtual-device.c @ 1038

  virtual-device.c @ 1455

  virtual-device.c @ 1581

FTL

  sef-utils.c @ 67

---

SEFSetVirtualDeviceSuspendConfig

struct SEFStatus SEFSetVirtualDeviceSuspendConfig(SEFVDHandle vdHandle, const struct SEFVirtualDeviceSuspendConfig *config) NONNULL(1)

Sets the suspend configuration for a Virtual Device.

Parameters of SEFSetVirtualDeviceSuspendConfig

Type	Name	Direction	Description
SEFVDHandle	vdHandle	In	Handle to the SEF Unit
const struct SEFVirtualDeviceSuspendConfig*	config	In	Suspend configuration to set

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.

Usage Example

CLI

  virtual-device.c @ 1480

---

SEFCreateQoSDomain

struct SEFStatus SEFCreateQoSDomain(SEFVDHandle vdHandle, struct SEFQoSDomainID *QoSDomainID, struct SEFQoSDomainCapacity *flashCapacity, struct SEFQoSDomainCapacity *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) NONNULL(1

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	Out	Assigned QoS Domain ID.
struct SEFQoSDomainCapacity*	flashCapacity	In	Number of required/reserved/maximum ADUs regular flash
struct SEFQoSDomainCapacity*	pSLCFlashCapacity	In	Number of required/reserved/maximum ADUs pSLC flash
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 (0 for kForWrite, 1 for kForPSLCWrite, 2 for QoSD max)

Usage Example

CLI

  qos-domain.c @ 1791

---

SEFSetQoSDomainCapacity

struct SEFStatus SEFSetQoSDomainCapacity(SEFVDHandle vdHandle, struct SEFQoSDomainID QoSDomainID, enum SEFSuperBlockType type, struct SEFQoSDomainCapacity *capacity) NONNULL(1)

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 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
struct SEFQoSDomainCapacity*	capacity	In	Number of required/reserved/maximum ADUs the flash type

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

Usage Example

CLI

  qos-domain.c @ 2109

---

SEFSetRootPointer

struct SEFStatus SEFSetRootPointer(SEFQoSHandle qosHandle, int index, struct SEFFlashAddress value) NONNULL(1)

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 offset 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

Usage Example

CLI

  qos-domain.c @ 1923

  shell.c @ 905

  shell.c @ 952

FTL

  persistence.c @ 536

  persistence.c @ 547

  persistence.c @ 791

  persistence.c @ 901

  persistence.c @ 928

  sef-utils.c @ 264

  sef-utils.c @ 270

---

SEFSetReadDeadline

struct SEFStatus SEFSetReadDeadline(SEFQoSHandle qosHandle, enum SEFDeadlineType deadline) NONNULL(1)

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

---

SEFSetWeights

struct SEFStatus SEFSetWeights(SEFQoSHandle qosHandle, struct SEFWeights weights) NONNULL(1)

Sets target QoS Domain's default program and erase weights.

See Also: struct SEFQoSDomainInfo

Parameters of SEFSetWeights

Type	Name	Direction	Description
SEFQoSHandle	qosHandle	In	Handle to the QoS Domain
struct SEFWeights	weights	In	Default program and erase weights for this QoS Domain

Return value of SEFSetWeights

Type	Description
struct SEFStatus	Status and info summarizing result.

Return values of SEFSetWeights

Error Value	Description
-ENODEV	The QoS Domain handle is not valid
-EPERM	The QoS Domain Handle is not open

Usage Example

FTL

  sef-block-module.c @ 714

---

SEFGetSuperBlockList

struct SEFStatus SEFGetSuperBlockList(SEFQoSHandle qosHandle, struct SEFSuperBlockList *list, size_t bufferSize) NONNULL(1)

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
size_t	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

Usage Example

CLI

  qos-domain.c @ 909

  qos-domain.c @ 1950

  shell.c @ 676

  shell.c @ 1000

FTL

  flash-translation.c @ 661

  superblock.c @ 1363

---

SEFGetQoSDomainInformation

struct SEFStatus SEFGetQoSDomainInformation(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID, struct SEFQoSDomainInfo *info) NONNULL(1

Returns QoS Domain information, including the list of super blocks assigned to the QoS Domain.

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

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.

Usage Example

CLI

  qos-domain.c @ 535

  qos-domain.c @ 868

  qos-domain.c @ 1265

  qos-domain.c @ 1341

  qos-domain.c @ 1901

  qos-domain.c @ 2076

  shell.c @ 854

  shell.c @ 890

  shell.c @ 936

  shell.c @ 1104

  shell.c @ 1192

FTL

  garbage-collection.c @ 232

  manual-copy.c @ 245

  sef-block-module.c @ 415

  sef-utils.c @ 125

---

SEFGetReuseList

struct SEFStatus SEFGetReuseList(SEFQoSHandle qosHandle, struct SEFWearInfo *info, size_t bufferSize) NONNULL(1)

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
size_t	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, size_t bufferSize) NONNULL(1)

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
size_t	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, size_t bufferSize) NONNULL(1)

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
size_t	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

Usage Example

FTL

  garbage-collection.c @ 1182

---

SEFGetUserAddressList

struct SEFStatus SEFGetUserAddressList(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, struct SEFUserAddressList *list, size_t bufferSize) NONNULL(1)

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
size_t	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

Usage Example

CLI

  qos-domain.c @ 730

  shell.c @ 1042

FTL

  flash-translation.c @ 510

  manual-copy.c @ 275

---

SEFGetSuperBlockInfo

struct SEFStatus SEFGetSuperBlockInfo(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, int getDefectMap, struct SEFSuperBlockInfo *info) NONNULL(1)

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

Usage Example

CLI

  qos-domain.c @ 935

  shell.c @ 809

  shell.c @ 1031

  shell.c @ 1122

FTL

  data-tree-object.c @ 171

  flash-translation.c @ 616

  flash-translation.c @ 684

  flash-translation.c @ 777

  manual-copy.c @ 254

  manual-copy.c @ 263

  manual-copy.c @ 433

---

SEFCheckSuperBlock

struct SEFStatus SEFCheckSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress) NONNULL(1)

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

Usage Example

FTL

  garbage-collection.c @ 1198

---

SEFDeleteVirtualDevices

struct SEFStatus SEFDeleteVirtualDevices(SEFHandle sefHandle) NONNULL(1)

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

Usage Example

CLI

  virtual-device.c @ 1172

---

SEFDeleteQoSDomain

struct SEFStatus SEFDeleteQoSDomain(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID) NONNULL(1)

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

Usage Example

CLI

  qos-domain.c @ 1487

---

SEFResetEncryptionKey

struct SEFStatus SEFResetEncryptionKey(SEFVDHandle vdHandle, struct SEFQoSDomainID QoSDomainID) NONNULL(1)

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) NONNULL(1)

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

Usage Example

CLI

  qos-domain.c @ 1764

  qos-domain.c @ 2088

  virtual-device.c @ 957

  virtual-device.c @ 1445

  virtual-device.c @ 1553

---

SEFCloseVirtualDevice

struct SEFStatus SEFCloseVirtualDevice(SEFVDHandle vdHandle) NONNULL(1)

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

Usage Example

CLI

  qos-domain.c @ 1798

  qos-domain.c @ 1828

  qos-domain.c @ 1844

  qos-domain.c @ 2114

  qos-domain.c @ 2119

  virtual-device.c @ 984

  virtual-device.c @ 1462

  virtual-device.c @ 1486

  virtual-device.c @ 1496

  virtual-device.c @ 1566

  virtual-device.c @ 1588

  virtual-device.c @ 1602

---

SEFOpenQoSDomain

struct SEFStatus SEFOpenQoSDomain(SEFHandle sefHandle, struct SEFQoSDomainID QoSDomainID, void(*notifyFunc)(void *, struct SEFQoSNotification), void *context, const void *encryptionKey, SEFQoSHandle *qosHandle) NONNULL(1

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 multi-tenant 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

Usage Example

CLI

  qos-domain.c @ 887

  qos-domain.c @ 1257

  qos-domain.c @ 1813

  qos-domain.c @ 1910

  qos-domain.c @ 2182

  shell.c @ 349

FTL

  sef-block-module.c @ 527

---

SEFCloseQoSDomain

struct SEFStatus struct SEFStatus SEFCloseQoSDomain(SEFQoSHandle qosHandle) NONNULL()

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 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

Usage Example

CLI

  qos-domain.c @ 916

  qos-domain.c @ 946

  qos-domain.c @ 962

  qos-domain.c @ 974

  qos-domain.c @ 985

  qos-domain.c @ 1271

  qos-domain.c @ 1278

  qos-domain.c @ 1288

  qos-domain.c @ 1295

  qos-domain.c @ 1827

  qos-domain.c @ 1833

  qos-domain.c @ 1930

  qos-domain.c @ 1957

  qos-domain.c @ 1973

  qos-domain.c @ 1984

  qos-domain.c @ 2011

  qos-domain.c @ 2202

  shell.c @ 394

  shell.c @ 1511

FTL

  sef-block-module.c @ 500

---

SEFGetQoSHandleProperty

struct SEFProperty SEFGetQoSHandleProperty(SEFQoSHandle qos, enum SEFPropertyID propID) NONNULL()

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.

Usage Example

FTL

  data-tree-object.c @ 73

  die-stats.c @ 203

  garbage-collection.c @ 231

  garbage-collection.c @ 787

  garbage-collection.c @ 794

  manual-copy.c @ 228

  persistence.c @ 389

  persistence.c @ 709

  sef-block-module.c @ 506

  sef-utils.c @ 46

  sef-utils.c @ 66

  sef-utils.c @ 234

  superblock.c @ 337

  superblock.c @ 338

---

SEFSetQoSHandleProperty

struct SEFStatus SEFSetQoSHandleProperty(SEFQoSHandle qos, enum SEFPropertyID propID, struct SEFProperty value) NONNULL(1)

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

Usage Example

FTL

  sef-block-module.c @ 535

---

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.

Usage Example

FTL

  data-tree-object.c @ 626

  data-tree-object.c @ 635

  data-tree-object.c @ 688

  die-stats.c @ 288

  die-stats.c @ 310

  garbage-collection.c @ 542

  garbage-collection.c @ 940

  manual-copy.c @ 293

  persistence.c @ 137

  persistence.c @ 172

  persistence.c @ 421

  persistence.c @ 881

  sef-block-module.c @ 1587

  sef-utils.c @ 286

---

SEFCreateFlashAddress

struct SEFFlashAddress SEFCreateFlashAddress(SEFQoSHandle qosHandle, struct SEFQoSDomainID QoSDomainID, uint32_t blockNumber, uint32_t ADUOffset) NONNULL(1)

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.

Usage Example

FTL

  persistence.c @ 142

  persistence.c @ 177

  sef-utils.c @ 287

  superblock.c @ 425

  superblock.c @ 738

---

SEFReleaseSuperBlock

struct SEFStatus SEFReleaseSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress) NONNULL()

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

Usage Example

CLI

  qos-domain.c @ 1978

  shell.c @ 767

FTL

  persistence.c @ 722

  sef-notification.c @ 81

  superblock.c @ 1418

---

SEFAllocateSuperBlock

struct SEFStatus SEFAllocateSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress *flashAddress, enum SEFSuperBlockType type, uint8_t *defectMap, const struct SEFAllocateOverrides *overrides) NONNULL(1

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 SEFNamelessCopy 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

Type	Name	Direction	Description
SEFQoSHandle	qosHandle	In	Handle to the QoS Domain
struct SEFFlashAddress*	flashAddress	Out	The flash address of the allocated block
enum SEFSuperBlockType	type	In	kForWrite or kForPSLCWrite
uint8_t *	defectMap	Out	Optional buffer to receive the block's defect map. Used for kFragmented QoS Domains. When supplied, the buffer must be at least as large as SEFQoSDomainInfo::defectMapSize.
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.

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

Usage Example

CLI

  qos-domain.c @ 1139

  shell.c @ 592

FTL

  data-tree-object.c @ 103

  garbage-collection.c @ 883

---

SEFFlushSuperBlock

struct SEFStatus struct SEFStatus SEFFlushSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress, uint32_t *distanceToEndOfSuperBlock) NONNULL(1)

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 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

Usage Example

FTL

  garbage-collection.c @ 982

---

SEFCloseSuperBlock

struct SEFStatus SEFCloseSuperBlock(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress) NONNULL(1)

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. When .error is zero, .info is the size of the super block.

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

Usage Example

CLI

  qos-domain.c @ 1199

  shell.c @ 627

  shell.c @ 1497

FTL

  garbage-collection.c @ 1001

  garbage-collection.c @ 1009

  manual-copy.c @ 458

  persistence.c @ 525

  superblock.c @ 574

  superblock.c @ 599

  superblock.c @ 1405

  superblock.c @ 1416

---

SEFReleaseSuperBlockAsync

void SEFReleaseSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFReleaseSuperBlockIOCB *iocb) NONNULL(1

This function is the asynchronous version of SEFReleaseSuperBlock().

A caller allocated IOCB is supplied to initiate the release. The caller can free the IOCB once the kSefIoFlagDone bit is set in common.flags or the common.callback_func has been called. When the IOCB is malformed, the callback_func may be called on the submitters thread.

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.

Usage Example

FTL

  superblock.c @ 1003

---

SEFAllocateSuperBlockAsync

void SEFAllocateSuperBlockAsync(SEFQoSHandle qosHandle, struct SEFAllocateSuperBlockIOCB *iocb) NONNULL(1

This function is the asynchronous version of SEFAllocateSuperBlock().

A caller allocated IOCB is supplied to initiate the allocation. The caller can free the IOCB once the kSefIoFlagDone bit is set in common.flags or the common.callback_func has been called. When the IOCB is malformed, the callback_func may be called on the submitters thread.

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) NONNULL(1

This function is the asynchronous version of SEFCloseSuperBlock().

A caller allocated IOCB is supplied to initiate the close. The caller can free the IOCB once the kSefIoFlagDone bit is set in common.flags or the common.callback_func has been called. When the IOCB is malformed, the callback_func may be called on the submitters thread.

Note: kSuperBlockStateChanged will have been sent and processed 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

---