Common Structures

SEFUserAddressLbaBits

Number of bits in a user address lba value.

Name	Definition
SEFUserAddressLbaBits	40

---

SEFUserAddressMetaBits

Number of bits in a user address meta value.

Name	Definition
SEFUserAddressMetaBits	(64-SEFUserAddressLbaBits)

---

SEFAutoAllocate

Flash address value to indicate device should allocate the super block from standard FLASH while doing a write.

See Also: SEFWriteWithoutPhysicalAddress()

Name	Definition
SEFAutoAllocate	((struct SEFFlashAddress) {UINT64_C(0xffffffffffffffff)})

---

SEFAutoAllocatePSLC

Flash address value to indicate device should allocate the super block from pSLC while doing a write.

See Also: SEFWriteWithoutPhysicalAddress()

Name	Definition
SEFAutoAllocatePSLC	((struct SEFFlashAddress) { \
htole64(UINT64_C(0xfffffffffffffffe))})

---

SEFUserAddressIgnore

User address value to indicate it should not be validated by the SEF device.

See Also: SEFReadWithPhysicalAddress()

Name	Definition
SEFUserAddressIgnore	((struct SEFUserAddress) {UINT64_C(0xffffffffffffffff)})

---

SEFNullFlashAddress

Flash address value indicating empty.

Name	Definition
SEFNullFlashAddress	((struct SEFFlashAddress){(int64_t)0x0})

---

SEFIsNullFlashAddress

static int SEFIsNullFlashAddress(struct SEFFlashAddress flashAddress)

Checks whether the flash address is null.

Parameters of SEFIsNullFlashAddress

Type	Name	Direction	Description
struct SEFFlashAddress	flashAddress	In	The opaque address to be checked

Return value of SEFIsNullFlashAddress

Type	Description
int	Returns 1 if the flashAddress is null

Usage Example

CLI

  qos-domain.c @ 1921

FTL

  data-tree-object.c @ 148

  data-tree-object.c @ 186

  data-tree-object.c @ 681

  flash-translation.c @ 186

  flash-translation.c @ 720

  persistence.c @ 165

  persistence.c @ 196

  persistence.c @ 408

  persistence.c @ 513

  persistence.c @ 865

  persistence.c @ 944

  sef-block-module.c @ 463

  sef-block-module.c @ 467

  sef-block-module.c @ 1402

  sef-block-module.c @ 1554

  sef-block-module.c @ 1583

---

SEFIsEqualFlashAddress

static int SEFIsEqualFlashAddress(struct SEFFlashAddress flashAddress1, struct SEFFlashAddress flashAddress2)

Checks whether two flash addresses are equal.

Parameters of SEFIsEqualFlashAddress

Type	Name	Direction	Description
struct SEFFlashAddress	flashAddress1	In	The opaque address to be compared
struct SEFFlashAddress	flashAddress2	In	The opaque address to be compared

Return value of SEFIsEqualFlashAddress

Type	Description
int	Returns 1 if the flashAddress1 equals flashAddress2

Usage Example

CLI

  qos-domain.c @ 1197

  shell.c @ 1016

  shell.c @ 1120

FTL

  flash-translation.c @ 291

  garbage-collection.c @ 511

  garbage-collection.c @ 935

  garbage-collection.c @ 941

  persistence.c @ 130

  persistence.c @ 876

---

SEFNextFlashAddress

struct SEFFlashAddress SEFNextFlashAddress(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress) NONNULL(1)

Returns the next flash address by incrementing the ADU Offset.

Doesn't guarantee that the returned flash address is valid

Parameters of SEFNextFlashAddress

Type	Name	Direction	Description
SEFQoSHandle	qosHandle	In	Handle to a QoS Domain to interpret/parse the flash address.
struct SEFFlashAddress	flashAddress	In	The opaque address to be incremented

Return value of SEFNextFlashAddress

Type	Description
struct SEFFlashAddress	Returns the next flash address if the qosHandle is valid, otherwise it returns SEFNullFlashAddress.

Usage Example

CLI

  qos-domain.c @ 798

  shell.c @ 742

FTL

  flash-translation.c @ 342

  flash-translation.c @ 734

---

SEFStatus

Members of SEFStatus

Type	Name	Description
int32_t	error	Status information
int32_t	info	Additional context-based descriptive information

---

SEFVirtualDeviceID

Members of SEFVirtualDeviceID

Type	Name
uint16_t	id

---

SEFQoSDomainID

Members of SEFQoSDomainID

Type	Name
uint16_t	id

---

SEFPlacementID

Members of SEFPlacementID

Type	Name
uint16_t	id

---

SEFADUsize

Members of SEFADUsize

Type	Name	Description
uint32_t	data	ADU data size in bytes
uint16_t	meta	ADU meta data size in bytes
uint16_t	reserved	Reserved/unused

---

SEFInfo

Members of SEFInfo

Type	Name	Description
const char *	name	Device Name from O/S
char[8]	vendor	Vendor field
char[20]	serialNumber	Device serial number
char[8]	FWVersion	Device firmware version
char[8]	HWVersion	Device hardware version
uint16_t	unitNumber	Unit number of the SEFInfo struct
uint16_t	APIVersion	API Version
uint64_t	supportedOptions	Supported features - see kSupported defines
uint32_t	maxOpenSuperBlocks	Firmware version specific, max number of open super blocks for the device. When 0, the limit is per Virtual Device instead. SEFVirtualDeviceInfo
uint16_t	maxQoSDomains	Hardware version specific, may be less than 65535 defined by architecture
uint16_t	maxRootPointers	Firmware version specific, may be less than 8 defined by architecture
uint16_t	maxPlacementIDs	Firmware version specific, max number of auto opened super blocks per QoS Domain
uint16_t	reserved_0	Reserved/unused
uint16_t	numReadQueues	Firmware version specific, max number of read queues total
uint16_t	numVirtualDevices	Number of currently defined virtual devices
uint16_t	numQoSDomains	Number of currently defined QoS Domains
uint16_t	numBanks	Number of banks per channel
uint16_t	numChannels	Number of channels per SEF Unit
uint16_t	numPlanes	Number of planes per die
uint32_t	pageSize	Physical page size
uint32_t	numPages	Number of pages per block
uint32_t	numBlocks	Number of blocks per die
uint32_t	totalBandWidth	Total bandwidth in MiBs corresponding to the underlying flash component on this device
uint32_t	readTime	Read time in microseconds corresponding to the underlying flash components on this device
uint32_t	programTime	Program time in microseconds corresponding to the underlying flash components on this device
uint32_t	eraseTime	Erase time in microseconds corresponding to the underlying flash components on this device
uint16_t	minReadWeight	Advisory minimum read weight to allow timely house keeping internal I/O
uint16_t	minWriteWeight	Advisory minimum write weight to allow timely house keeping internal I/O
uint32_t	openExpirationPeriod	Granularity in seconds for entire block
uint16_t	reserved_1	Reserved/unused
uint16_t	numADUSizes	Size of ADUsize array that follows at end of structure
struct SEFADUsize[]	ADUsize	Array of supported ADU sizes

---

SEFVirtualDeviceList

Members of SEFVirtualDeviceList

Type	Name	Description
uint16_t	numVirtualDevices	Number of virtual devices
struct SEFVirtualDeviceID[]	virtualDeviceID	An Array of all Virtual device IDs

---

SEFQoSDomainList

Members of SEFQoSDomainList

Type	Name	Description
uint16_t	numQoSDomains	Number of QoS domains
struct SEFQoSDomainID[]	QoSDomainID	An Array of all QoS Domain IDs

---

SEFUserAddress

Structure of SEFUserAddress may be redefined by user.

The limitations for redefining the structure are:

• size must be 8 bytes
• multi-adu writes will auto increment the LBA value and must not equal SEFUserAddressIgnore. However SEFUserAddressIgnore is supported as a starting user address.

For kSuperBlock, the LBA is limited to 40 bits and the meta to 24. The unformatted member is in little endian format.

Members of SEFUserAddress

Type	Name
uint64_t	unformatted

---

SEFFlashAddress

Opaque flash address value parsable by SEFParseFlashAddress()

Members of SEFFlashAddress

Type	Name
uint64_t	bits

---

SEFDieList

Members of SEFDieList

Type	Name	Description
uint16_t	numDies	Number of dies in dieIDs
uint16_t[]	dieIDs	List of dies by ID

---

SEFWeights

Relative die time weights for write type of I/O operations.

Members of SEFWeights

Type	Name	Description
uint16_t	programWeight	Default weight for a program operation by the Nameless Write and Nameless Copy commands
uint16_t	eraseWeight	Default weight for an erase operation by SEFAllocateSuperBlock, SEFFlushSuperBlock and SEFCloseSuperBlock

---

SEFVirtualDeviceConfig

Members of SEFVirtualDeviceConfig

Type	Name	Description
struct SEFVirtualDeviceID	virtualDeviceID	Virtual Device ID
uint8_t	numReadQueues	Number of read queues to define for this Virtual Device
uint8_t	reserved	Reserved, must be initialized to zero
uint16_t[SEFMaxReadQueues]	readWeights	Default weight for read operations for each possible read queue
uint16_t	superBlockDies	Number of dies in a super block, 0 uses dieList.numDies
struct SEFDieList	dieList	List of dies in ascending order for the Virtual Device

---

SEFVirtualDeviceUsage

Members of SEFVirtualDeviceUsage

Type	Name	Description
uint32_t	eraseCount	Count of super blocks erased. Used to populate eraseOrder in SEFSuperBlockInfo
uint32_t	numUnallocatedSuperBlocks	Number of unallocated super blocks
uint32_t	numSuperBlocks	Number of allocated super blocks
uint32_t	numUnallocatedPSLCSuperBlocks	Number of unallocated pSLC super blocks
uint32_t	numPSLCSuperBlocks	Number of allocated pSLC super blocks
struct SEFVirtualDeviceID	vdID	Virtual device ID of the handle
uint8_t	averagePEcount	Average program/erase count
uint8_t	maxPEcount	Max program/erase count
uint16_t	patrolCycleTime	Recommended Patrol Cycle in minutes
uint16_t	reserved	Reserved, must be initialized to zero

---

SEFVirtualDeviceSuspendConfig

Configuration for Erase/Program suspend.

The weights supplied with i/o represents virtual time. These parameters control how often, and for how long an erase/program can be interrupted by reads.

Members of SEFVirtualDeviceSuspendConfig

Type	Name
uint32_t	maxTimePerSuspend
uint32_t	minTimeUntilSuspend
uint32_t	maxSuspendInterval

---

SEFVirtualDeviceInfo

Members of SEFVirtualDeviceInfo

Type	Name	Description
uint64_t	flashCapacity	Flash capacity in 4k ADUs
uint64_t	flashAvailable	Available flash capacity in 4k ADUs
uint64_t	pSLCFlashCapacity	pSLC Flash capacity in 4k ADUs
uint64_t	pSLCFlashAvailable	pSLC Available flash capacity in 4k ADUs
uint32_t	superBlockCapacity	Super block capacity in 4k ADUs
uint32_t	pSLCSuperBlockCapacity	pSLC super block capacity in 4k ADUs
uint32_t	maxOpenSuperBlocks	Maximum number of open super blocks per Virtual Device. When 0, the limit is per device instead. See SEFInfo
uint32_t	numPSLCSuperBLocks	Number of pSLC super blocks
struct SEFVirtualDeviceSuspendConfig	suspendConfig
uint16_t	superBlockDies	Number of dies used for a super block
uint8_t	aduOffsetBitWidth	Number of bits that make up the adu offset in a flash address
uint8_t	superBlockIdBitWidth	Number of bits that make up the super block id in a flash address
uint16_t[SEFMaxReadQueues]	readWeights	Default weight for read operations for each possible read queue
uint8_t	numReadQueues	Number of read queues defined for the Virtual Device
uint8_t[5]	reserved	Reserved, must be initialized to zero
struct SEFQoSDomainList	QoSDomains	List of domains

---

SEFQoSDomainCapacity

Members of SEFQoSDomainCapacity

Type	Name	Description
uint64_t	flashCapacity	Number of ADUs to assign to a QoS Domain
uint64_t	flashQuota	Maximum number of ADUs allowed for a QoS Domain

---

SEFSuperBlockInfo

Members of SEFSuperBlockInfo

Type	Name	Description
struct SEFFlashAddress	flashAddress	Flash address where this super block resides
uint32_t	eraseOrder	Indication of when a super block was erased. Can be used to determine the order blocks were allocated or to version a super block. Values only increase over time and are unique at the Virtual Device level
uint32_t	writableADUs	For a fresh, unwritten, open super block, this how much QoS Domain quota is being used by the super block. It will decrease if defects are encountered while writing
uint32_t	writtenADUs	This field increases as ADUs in the super block are written. For kPerfect and kPacked, it will equal writableADUs when the block is closed. For kFragmented, it will equal super block capacity because it includes defective portions of the flash
struct SEFPlacementID	placementID	When auto-allocated, indicates the placement id supplied to SEFWriteWithoutPhysicalAddress(). Otherwise it will be SEFPlacementIdUnused
uint16_t	numDefects	Number of defective planes per super page. This may increase as the super block is written
uint16_t	timeLeft	Time in minutes left to handle an integrity that is not kIntegrityGood before risking data loss
uint8_t	PEIndex	This is the block's erase count normalized to be between 0 and 255
enum SEFSuperBlockType	type	This is the type of the super block, normal or pSLC
enum SEFSuperBlockState	state	This is the block's current state
enum SEFDataIntegrity	integrity	This is the integrity of the super block, If not kIntegrityGood, the super block requires a SEFCheckSuperBlock to patrol or refresh
uint8_t[]	defects	This is a bitmap indicating which planes are defective. SEFQoSDomainInfo::defectMapSize is the size of this field.

---

SEFSuperBlockRecord

Entry in a SEFSuperBlockList.

Members of SEFSuperBlockRecord

Type	Name	Description
struct SEFFlashAddress	flashAddress	Flash address where this super block resides
uint8_t[6]	reserved	Reserved
uint8_t	PEIndex	This is the block's erase count normalized to be between 0 and 255
enum SEFSuperBlockState	state	This is the block's current state

---

SEFSuperBlockList

Members of SEFSuperBlockList

Type	Name	Description
uint32_t	numSuperBlocks	Number of super blocks in use by the QoS Domain
uint32_t	reserved	Reserved
struct SEFSuperBlockRecord[]	superBlockRecords	List of super block records

---

SEFQoSDomainInfo

Members of SEFQoSDomainInfo

Type	Name	Description
struct SEFVirtualDeviceID	virtualDeviceID	Virtual device ID
uint16_t	numPlacementIDs	Specifies the number of Placement IDs corresponding to this QoS Domain
uint8_t	encryption	0 for disabled, non-zero for enabled
enum SEFErrorRecoveryMode	recoveryMode	Specifies the recovery mode for this QoS Domain
enum SEFDefectManagementMethod	defectStrategy	Defect management strategy for the QoS Domain
enum SEFAPIIdentifier	api	Specifies the API Identifier for this QoS Domain
uint64_t	flashCapacity	Reserved capacity of the QoS Domain in QoS Domain ADUs
uint64_t	flashQuota	Number of QoS Domain ADUs that can be allocated by the QoS Domain
uint64_t	flashUsage	Number of QoS Domain ADUs allocated by the QoS Domain
uint64_t	pSLCFlashCapacity	Reserved pSLC capacity of the QoS Domain in QoS Domain ADUs
uint64_t	pSLCFlashQuota	Number of pSLC QoS Domain ADUs that can be allocated by the QoS Domain
uint64_t	pSLCFlashUsage	Number of pSLC QoS Domain ADUs allocated by the QoS Domain
struct SEFFlashAddress[SEFMaxRootPointer]	rootPointers	List of root pointers
struct SEFADUsize	ADUsize	Size of QoS Domain ADUs, data and metadata in bytes
uint32_t	superBlockCapacity	Super block capacity in QoS Domain ADUs
uint32_t	pSLCSuperBlockCapacity	pSLC super block capacity in QoS Domain ADUs
uint16_t	maxOpenSuperBlocks	Maximum number of open super blocks for the QoS Domain
uint16_t	defectMapSize	Size of a super block defect map
struct SEFWeights	weights	Default i/o weights for erase and program
enum SEFDeadlineType	deadline	Deadline type for the QoS Domain
uint8_t	defaultReadQueue	Default read queue assignment
uint8_t	numReadQueues	Number of read queues as defined by the Virtual Device
uint8_t[5]	reserved	Reserved

---

SEFWearInfo

Members of SEFWearInfo

Type	Name	Description
uint32_t	numSuperBlocks	Number of super blocks
uint32_t	reserved_0	Reserved, must be initialized to zero
struct SEFSuperBlockRecord[]	superBlockRecords	List of super block records

---

SEFRefreshInfo

Members of SEFRefreshInfo

Type	Name	Description
uint32_t	numSuperBlocks	Number of super blocks
uint32_t	reserved_0	Reserved, must be initialized to zero
struct SEFSuperBlockRecord[]	superBlockRecords	List of super block records

---

SEFCheckInfo

SuperBlocks returned by SEFGetCheckList()

Members of SEFCheckInfo

Type	Name	Description
uint32_t	numSuperBlocks	Number of super blocks
uint32_t	reserved_0	Reserved, must be initialized to zero
struct SEFSuperBlockRecord[]	superBlockRecords	List of super block records

---

SEFUserAddressList

Members of SEFUserAddressList

Type	Name	Description
uint32_t	numADUs	Number of ADUs
uint32_t	reserved_0	Reserved, must be initialized to zero
struct SEFUserAddress[]	userAddressesRecovery	User addresses

---

SEFProperty

Members of SEFProperty

Type	Name	Description
union		5 Members
→ int	intVal	Valid when type is kSefPropertyTypeInt
→ void *	ptr	Valid when type is kSefPropertyTypePtr
→ struct SEFQoSDomainID	qosID	Valid when type is kSefPropertyTypeQoSDomainID
→ struct SEFVirtualDeviceID	vdID	Valid when type is kSefPropertyTypeVirtualDeviceID
→ void(*)(void *, struct SEFQoSNotification)	qosNotify	Valid when type is kSefPropertyTypeQoSNotify
enum SEFPropertyType	type	Denotes the property type

---

SEFWriteOverrides

Supplied to override default write weights.

May be used when calling SEFWriteWithoutPhysicalAddress() or SEFWriteWithoutPhysicalAddressAsync().

Members of SEFWriteOverrides

Type	Name	Description
uint16_t	programWeight	Weight to use for program instead of the QoS domain default. 0 will use the QoS Domain default.
uint16_t	eraseWeight	Weight to use for erase instead of the QoS domain default. 0 will use the QoS Domain default.

---

SEFReadOverrides

Supplied to override default read weight.

May be used when calling SEFReadWithPhysicalAddress() or SEFReadWithPhysicalAddressAsync().

Members of SEFReadOverrides

Type	Name	Description
uint16_t	readWeight	Weight to use for read instead of the read queue's default. 0 will use the read queue's default.
uint8_t	readQueue	Read queue to use for read instead of QoS Domain's default. A value greater than number of read queues defined for the QoS Domain will use the default read queue for the QoS Domain.
uint8_t	reserved	Reserved, must be initialized to zero.

---

SEFAllocateOverrides

Supplied to override default super block allocation weight.

May be used when calling SEFAllocateSuperBlock() or SEFAllocateSuperBlockAsync().

Members of SEFAllocateOverrides

Type	Name	Description
uint16_t	eraseWeight	Weight to use for erase instead of the QoS Domain default. 0 will use the QoS Domain default.

---

SEFCopySource

Source addresses for SEFNamelessCopy().

The Source addresses format controls if the validBitmap or list of flash addresses is used.SEFNamelessCopy()SEFUserAddressFilter

Members of SEFCopySource

Type	Name	Description
enum SEFCopySourceType	format	Specifies the format to use
uint8_t[3]	reserved_0	Reserved, must be initialized to zero
uint32_t	arraySize	Number of items in bitmap array or Flash Address List (QWORD count)
union		2 Members
→ const struct SEFFlashAddress*	flashAddressList	pointer to flash address list
→ struct		2 Members
→ → struct SEFFlashAddress	srcFlashAddress	flash address of source block. ADU & ~0x3f indicates the ADU of bit 0 of validBitmap and ADU & 0x3f is the starting bit in validBitMap
→ → const uint64_t *	validBitmap	pointer to COPY of valid bitmap array (little endian)

---

SEFUserAddressFilter

Optional filtering on user address data during copy.

Members of SEFUserAddressFilter

Type	Name	Description
struct SEFUserAddress	userAddressStart	Starting user address of filter
uint64_t	userAddressRangeLength	Length of filter range (0 indicates no filtering)
uint32_t	userAddressRangeType	Zero to copy data in range; non-zero to copy outside of range

---

SEFAddressChangeRequest

Detailed information about results of the SEFNamelessCopy() request.

Members of SEFAddressChangeRequest

Type	Name	Description
uint32_t	numProcessedADUs	The number of processed ADUs including errors
uint32_t	nextADUOffset	Given a bitmap source, it indicates the next ADU offset of the source flash address; Given a list source, it indicates the next entry number in the source flash address list
uint32_t	numReadErrorADUs	The number of ADUs that couldn't be processed due to errors
uint32_t	numADUsLeft	The number of remaining ADUs in the destination super block
uint8_t	copyStatus	A bit array denoting the results of the request
uint8_t[7]	reserved	Reserved, must be initialized to zero
struct []	addressUpdate	3 Members; An array of information about copied ADUs
→ struct SEFUserAddress	userAddress	The user address
→ struct SEFFlashAddress	oldFlashAddress	The old flash address
→ struct SEFFlashAddress	newFlashAddress	The new flash address

---

SEFCopyOverrides

Scheduling Queue overrides for SEFNamelessCopy()

Members of SEFCopyOverrides

Type	Name	Description
uint16_t	programWeight	Weight to use for program instead of the QoS domain default. 0 will use the QoS Domain default

---