Skip to main content
Version: 1.13

Common Structures

SEFUserAddressLbaBits

Number of bits in a user address lba value.

NameDefinition
SEFUserAddressLbaBits40

SEFUserAddressMetaBits

Number of bits in a user address meta value.

NameDefinition
SEFUserAddressMetaBits(64-SEFUserAddressLbaBits)

SEFAutoAllocate

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

See Also: SEFWriteWithoutPhysicalAddress()

NameDefinition
SEFAutoAllocate((struct SEFFlashAddress) {UINT64_C(0xffffffffffffffff)})

SEFUserAddressIgnore

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

See Also: SEFReadWithPhysicalAddress()

NameDefinition
SEFUserAddressIgnore((struct SEFUserAddress) {UINT64_C(0xffffffffffffffff)})

SEFNullFlashAddress

Flash address value indicating empty.

NameDefinition
SEFNullFlashAddress((struct SEFFlashAddress){(int64_t)0x0})

SEFIsNullFlashAddress

static int SEFIsNullFlashAddress(struct SEFFlashAddress flashAddress)

Checks whether the flash address is null.

Parameters of SEFIsNullFlashAddress

TypeNameDirectionDescription
struct SEFFlashAddressflashAddressInThe opaque address to be checked

Return value of SEFIsNullFlashAddress

TypeDescription
intReturns 1 if the flashAddress is null

SEFIsEqualFlashAddress

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

Checks whether two flash addresses are equal.

Parameters of SEFIsEqualFlashAddress

TypeNameDirectionDescription
struct SEFFlashAddressflashAddress1InThe opaque address to be compared
struct SEFFlashAddressflashAddress2InThe opaque address to be compared

Return value of SEFIsEqualFlashAddress

TypeDescription
intReturns 1 if the flashAddress1 equals flashAddress2

SEFNextFlashAddress

struct SEFFlashAddress SEFNextFlashAddress(SEFQoSHandle qosHandle, struct SEFFlashAddress flashAddress)

Returns the next flash address by incrementing the ADU Offset. Doesn't guarantee that the returned flash address is valid

Parameters of SEFNextFlashAddress

TypeNameDirectionDescription
SEFQoSHandleqosHandleInHandle to a QoS Domain to interpret/parse the flash address.
struct SEFFlashAddressflashAddressInThe opaque address to be incremented

Return value of SEFNextFlashAddress

TypeDescription
struct SEFFlashAddressReturns the next flash address if the qosHandle is valid, otherwise it returns SEFNullFlashAddress.

SEFStatus

Members of SEFStatus

TypeNameDescription
int32_terrorStatus information
int32_tinfoAdditional context-based descriptive information

SEFVirtualDeviceID

Members of SEFVirtualDeviceID

TypeName
uint16_tid

SEFQoSDomainID

Members of SEFQoSDomainID

TypeName
uint16_tid

SEFPlacementID

Members of SEFPlacementID

TypeName
uint16_tid

SEFADUsize

Members of SEFADUsize

TypeNameDescription
uint32_tdataADU data size in bytes
uint16_tmetaADU meta data size in bytes
uint16_treservedReserved/unused

SEFInfo

Members of SEFInfo

TypeNameDescription
const char *nameDevice Name from O/S
char[8]vendorVendor field
char[20]serialNumberDevice serial number
char[8]FWVersionDevice firmware version
char[8]HWVersionDevice hardware version
uint16_tunitNumberUnit number of the SEFInfo struct
uint16_tAPIVersionAPI Version
uint64_tsupportedOptionsSupported features - see kSupported defines
uint16_tmaxQoSDomainsHardware version specific, may be less than 65535 defined by architecture
uint16_tmaxRootPointersFirmware version specific, may be less than 8 defined by architecture
uint16_tmaxPlacementIDsFirmware version specific, max number of auto opened super blocks per QoS Domain
uint16_tmaxOpenSuperBlocksFirmware version specific, max number of open super blocks for the device. When 0, the limit is per Virtual Device instead. SEFVirtualDeviceInfo
uint16_tnumReadQueuesFirmware version specific, max number of read queues total
uint16_tnumVirtualDevicesNumber of currently defined virtual devices
uint16_tnumQoSDomainsNumber of currently defined QoS Domains
uint16_tnumBanksNumber of banks per channel
uint16_tnumChannelsNumber of channels per SEF Unit
uint16_tnumPlanesNumber of planes per die
uint32_tpageSizePhysical page size
uint32_tnumPagesNumber of pages per block
uint32_tnumBlocksNumber of blocks per die
uint32_ttotalBandWidthTotal bandwidth in MiBs corresponding to the underlying flash component on this device
uint32_treadTimeRead time in microseconds corresponding to the underlying flash components on this device
uint32_tprogramTimeProgram time in microseconds corresponding to the underlying flash components on this device
uint32_teraseTimeErase time in microseconds corresponding to the underlying flash components on this device
uint16_tminReadWeightAdvisory minimum read weight to allow timely house keeping internal I/O
uint16_tminWriteWeightAdvisory minimum write weight to allow timely house keeping internal I/O
uint32_topenExpirationPeriodGranularity in seconds for entire block
uint16_treserved_0Reserved/unused
uint16_tnumADUSizesSize of ADUsize array that follows at end of structure
struct SEFADUsize[]ADUsizeArray of supported ADU sizes

SEFVirtualDeviceList

Members of SEFVirtualDeviceList

TypeNameDescription
uint16_tnumVirtualDevicesNumber of virtual devices
struct SEFVirtualDeviceID[]virtualDeviceIDAn Array of all Virtual device IDs

SEFQoSDomainList

Members of SEFQoSDomainList

TypeNameDescription
uint16_tnumQoSDomainsNumber of QoS domains
struct SEFQoSDomainID[]QoSDomainIDAn 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

TypeName
uint64_tunformatted

SEFFlashAddress

Opaque flash address value parsable by SEFParseFlashAddress()

Members of SEFFlashAddress

TypeName
uint64_tbits

SEFDieList

Members of SEFDieList

TypeNameDescription
uint16_tnumDiesNumber of dies in dieIDs
uint16_t[]dieIDsList of dies by ID

SEFWeights

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

Members of SEFWeights

TypeNameDescription
uint16_teraseWeightDefault weight for an erase operation by SEFAllocateSuperBlock, SEFFlushSuperBlock and SEFCloseSuperBlock
uint16_tprogramWeightDefault weight for a program operation by the Nameless Write and Nameless Copy commands

SEFVirtualDeviceConfig

Members of SEFVirtualDeviceConfig

TypeNameDescription
struct SEFVirtualDeviceIDvirtualDeviceIDVirtual Device ID
uint8_tnumReadQueuesNumber of read queues to define for this Virtual Device
uint8_treservedReserved, must be initialized to zero
uint16_t[SEFMaxReadQueues]readWeightsDefault weight for read operations for each possible read queue
uint16_tsuperBlockDiesNumber of dies in a super block, 0 uses dieList.numDies
struct SEFDieListdieListList of dies in ascending order for the Virtual Device

SEFVirtualDeviceUsage

Members of SEFVirtualDeviceUsage

TypeNameDescription
uint32_teraseCountCount of super blocks erased. Used to populate eraseOrder in SEFSuperBlockInfo
uint32_tnumUnallocatedSuperBlocksNumber of unallocated super blocks
uint32_tnumSuperBlocksNumber of allocated super blocks
uint32_tnumUnallocatedPSLCSuperBlocksNumber of unallocated pSLC super blocks
uint32_tnumPSLCSuperBlocksNumber of allocated pSLC super blocks
struct SEFVirtualDeviceIDvdIDVirtual device ID of the handle
uint8_taveragePEcountAverage program/erase count
uint8_tmaxPEcountMax program/erase count
uint16_tpatrolCycleTimeRecommended Patrol Cycle in minutes
uint16_treservedReserved, 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

TypeName
uint32_tmaxTimePerSuspend
uint32_tminTimeUntilSuspend
uint32_tmaxSuspendInterval

SEFVirtualDeviceInfo

Members of SEFVirtualDeviceInfo

TypeNameDescription
uint64_tflashCapacityFlash capacity in 4k ADUs
uint64_tflashAvailableAvailable flash capacity in 4k ADUs
uint64_tpSLCFlashCapacitypSLC Flash capacity in 4k ADUs
uint64_tpSLCFlashAvailablepSLC Available flash capacity in 4k ADUs
uint32_tsuperBlockCapacitySuper block capacity in 4k ADUs
uint32_tpSLCSuperBlockCapacitypSLC super block capacity in 4k ADUs
uint32_tmaxOpenSuperBlocksMaximum number of open super blocks per Virtual Device. When 0, the limit is per device instead. See SEFInfo
uint32_tnumPSLCSuperBLocksNumber of pSLC super blocks
struct SEFVirtualDeviceSuspendConfigsuspendConfig
uint16_tsuperBlockDiesNumber of dies used for a super block
uint8_taduOffsetBitWidthNumber of bits that make up the adu offset in a flash address
uint8_tsuperBlockIdBitWidthNumber of bits that make up the super block id in a flash address
uint16_t[SEFMaxReadQueues]readWeightsDefault weight for read operations for each possible read queue
uint8_tnumReadQueuesNumber of read queues defined for the Virtual Device
uint8_t[5]reservedReserved, must be initialized to zero
struct SEFQoSDomainListQoSDomainsList of domains

SEFSuperBlockInfo

Members of SEFSuperBlockInfo

TypeNameDescription
struct SEFFlashAddressflashAddressFlash address where this super block resides
uint32_teraseOrderIndication 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_twritableADUsFor 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_twrittenADUsThis 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 SEFPlacementIDplacementIDWhen auto-allocated, indicates the placement id supplied to SEFWriteWithoutPhysicalAddress(). Otherwise it will be SEFPlacementIdUnused
uint16_tnumDefectsNumber of defective planes per super page. This may increase as the super block is written
uint16_ttimeLeftTime in minutes left to handle an integrity that is not kIntegrityGood before risking data loss
uint8_tPEIndexThis is the block's erase count normalized to be between 0 and 255
enum SEFSuperBlockTypetypeThis is the type of the super block, normal or pSLC
enum SEFSuperBlockStatestateThis is the block's current state
enum SEFDataIntegrityintegrityThis is the integrity of the super block, If not kIntegrityGood, the super block requires a SEFCheckSuperBlock to patrol or refresh
uint8_t[]defectsThis is a bitmap indicating which planes are dective. SEFQoSDomainInfo::defectMapSize is the size of this field.

SEFSuperBlockRecord

Entry in a SEFSuperBlockList.

Members of SEFSuperBlockRecord

TypeNameDescription
struct SEFFlashAddressflashAddressFlash address where this super block resides
uint8_t[6]reservedReserved
uint8_tPEIndexThis is the block's erase count normalized to be between 0 and 255
enum SEFSuperBlockStatestateThis is the block's current state

SEFSuperBlockList

Members of SEFSuperBlockList

TypeNameDescription
uint32_tnumSuperBlocksNumber of super blocks in use by the QoS Domain
uint32_treservedReserved
struct SEFSuperBlockRecord[]superBlockRecordsList of super block records

SEFQoSDomainInfo

Members of SEFQoSDomainInfo

TypeNameDescription
struct SEFVirtualDeviceIDvirtualDeviceIDVirtual device ID
uint16_tnumPlacementIDsSpecifies the number of Placement IDs corresponding to this QoS Domain
uint8_tencryption0 for disabled, non-zero for enabled
enum SEFErrorRecoveryModerecoveryModeSpecifies the recovery mode for this QoS Domain
enum SEFDefectManagementMethoddefectStrategyDefect management strategy for the QoS Domain
enum SEFAPIIdentifierapiSpecifies the API Identifier for this QoS Domain
uint64_tflashCapacityReserved capacity of the QoS Domain in QoS Domain ADUs
uint64_tflashQuotaNumber of QoS Domain ADUs that can be allocated by the QoS Domain
uint64_tpSLCFlashCapacityReserved pSLC capacity of the QoS Domain in QoS Domain ADUs
uint64_tpSLCFlashQuotaNumber of pSLC QoS Domain ADUs that can be allocated by the QoS Domain
struct SEFFlashAddress[SEFMaxRootPointer]rootPointersList of root pointers
struct SEFADUsizeADUsizeSize of QoS Domain ADUs, data and metadata in bytes
uint32_tsuperBlockCapacitySuper block capacity in QoS Domain ADUs
uint32_tpSLCSuperBlockCapacitypSLC super block capacity in QoS Domain ADUs
uint16_tmaxOpenSuperBlocksMaximum number of open super blocks for the QoS Domain
uint16_tdefectMapSizeSize of a super block defect map
struct SEFWeightsweightsDefault i/o weights for erase and program
enum SEFDeadlineTypedeadlineDeadline type for the QoS Domain
uint8_tdefaultReadQueueDefault read queue assignment
uint8_tnumReadQueuesNumber of read queues as defined by the Virtual Device
uint8_t[5]reservedReserved

SEFWearInfo

Members of SEFWearInfo

TypeNameDescription
uint32_tnumSuperBlocksNumber of super blocks
uint32_treserved_0Reserved, must be initialized to zero
struct SEFSuperBlockRecord[]superBlockRecordsList of super block records

SEFRefreshInfo

Members of SEFRefreshInfo

TypeNameDescription
uint32_tnumSuperBlocksNumber of super blocks
uint32_treserved_0Reserved, must be initialized to zero
struct SEFSuperBlockRecord[]superBlockRecordsList of super block records

SEFCheckInfo

SuperBlocks returned by SEFGetCheckList()

Members of SEFCheckInfo

TypeNameDescription
uint32_tnumSuperBlocksNumber of super blocks
uint32_treserved_0Reserved, must be initialized to zero
struct SEFSuperBlockRecord[]superBlockRecordsList of super block records

SEFUserAddressList

Members of SEFUserAddressList

TypeNameDescription
uint32_tnumADUsNumber of ADUs
uint32_treserved_0Reserved, must be initialized to zero
struct SEFUserAddress[]userAddressesRecoveryUser addresses

SEFProperty

Members of SEFProperty

TypeNameDescription
union5 Members
→ intintValValid when type is kSefPropertyTypeInt
→ void *ptrValid when type is kSefPropertyTypePtr
struct SEFQoSDomainIDqosIDValid when type is kSefPropertyTypeQoSDomainID
struct SEFVirtualDeviceIDvdIDValid when type is kSefPropertyTypeVirtualDeviceID
→ void()(void , struct SEFQoSNotification)qosNotifyValid when type is kSefPropertyTypeQoSNotify
enum SEFPropertyTypetypeDenotes the property type

SEFWriteOverrides

Supplied to override default write weights. May be used when calling SEFWriteWithoutPhysicalAddress() or SEFWriteWithoutPhysicalAddressAsync().

Members of SEFWriteOverrides

TypeNameDescription
uint16_tprogramWeightWeight to use for program 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

TypeNameDescription
uint16_treadWeightWeight to use for read instead of the read queue's default. 0 will use the read queue's default.
uint8_treadQueueRead queue to use for read instead of QoS Domain's default. A value of 0 or greater than number of read queues defined for the QoS Domain will use the default read queue for the QoS Domain.
uint8_treservedReserved, 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

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

TypeNameDescription
enum SEFCopySourceTypeformatSpecifies the format to use
uint8_t[3]reserved_0Reserved, must be initialized to zero
uint32_tarraySizeNumber of items in bitmap array or Flash Address List (QWORD count)
union2 Members
const struct SEFFlashAddress*flashAddressListpointer to flash address list
→ struct2 Members
→ → struct SEFFlashAddresssrcFlashAddressflash 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 *validBitmappointer to COPY of valid bitmap array (little endian)

SEFUserAddressFilter

Optional filtering on user address data during copy.

Members of SEFUserAddressFilter

TypeNameDescription
struct SEFUserAddressuserAddressStartStarting user address of filter
uint64_tuserAddressRangeLengthLength of filter range (0 indicates no filtering)
uint32_tuserAddressRangeTypeZero to copy data in range; non-zero to copy outside of range

SEFAddressChangeRequest

Detailed information about results of the SEFNamelessCopy() request.

Members of SEFAddressChangeRequest

TypeNameDescription
uint32_tnumProcessedADUsThe number of processed ADUs including errors
uint32_tnextADUOffsetGiven 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_tnumReadErrorADUsThe number of ADUs that couldn't be processed due to errors
uint32_tnumADUsLeftThe number of remaining ADUs in the destination super block
uint8_tcopyStatusA bit array denoting the results of the request
uint8_t[7]reservedReserved, must be initialized to zero
struct []addressUpdate3 Members; An array of information about copied ADUs
struct SEFUserAddressuserAddressThe user address
struct SEFFlashAddressoldFlashAddressThe old flash address
struct SEFFlashAddressnewFlashAddressThe new flash address

SEFCopyOverrides

Scheduling Queue overrides for SEFNamelessCopy()

Members of SEFCopyOverrides

TypeNameDescription
uint16_tprogramWeightWeight to use for program instead of the QoS domain default. 0 will use the QoS Domain default