NVIDIA DRIVE OS Linux API Reference

5.1.3.0 Release

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Partition Manager

Detailed Description

QbPartMgr is an NVIDIA interface for accessing information about data partitions on storage devices.

A single physical storage device may be treated as multiple smaller logical volumes. Each such logical volume is referred to as a partition. The Partition Manager maintains information on the size, location, and other attributes of the various partitions that exist on the system. Collectively, this information is referred to as the Partition Table (PT). Note that there is exactly one PT on the system and it contains information on all the partitions on all the non-removable storage devices on the system.

The Partition Manager supports the following major operations:

In the PT creation scenario, a client calls QbPartMgrInit() to initialize the Partition Manager. Then QbPartMgrCreateTableStart() is invoked to signal that definition of the various partitions is ready to begin. Next, the partitions are defined one by one using the QbPartMgrAddTableEntry() routine. Once all the partitions have been defined, QbPartMgrCreateTableFinish() is called to signal the end of the partition table. Finally, the PT is written to a storage device via QbPartMgrSaveTable() and the Partition Manager can be shut down by calling QbPartMgrDeinit().

For the normal use case, the Partition Manager is initialized via QbPartMgrInit(), after which the pre-existing PT is loaded from a storage device using QbPartMgrLoadTable(). Thereafter, information from the PT can be accessed via the QbPartMgrGet*() and NvPartMgrQuery*() API's. When the PT information is no longer needed, call QbPartMgrDeinit() to shut down the Partition Manager.

Note
The partition ID value of zero (0) is reserved. Each partition must have a unique ID and a unique name. All strings are in UTF-8 format and have a maximum length of QB_PARTITION_NAME_LENGTH.

Data Structures

struct  QbAllocPartArgsRec
 

Macros

#define MAX_PARTITIONS_INDEX   41
 
#define MAX_NUM_PARTITIONS   (MAX_PARTITIONS_INDEX - 1)
 
#define GPT_SIZE_IN_SECTORS   33
 
#define GUEST_BOOT_PARTITION_FLAG   0x80000000
 
#define PT_LEVEL_1   (1)
 
#define PT_LEVEL_2   (2)
 

Typedefs

typedef struct QbAllocPartArgsRec QbAllocPartArgs
 

Functions

NvError QbLoadAndInitPartMgr (void)
 Loads and initializes partitions. More...
 
NvBool QbQueryThreeLevelPtInfo (void)
 Query information about 3-level PT. More...
 
NvError QbPartMgrInit (void)
 Initializes the partition manager. More...
 
void QbPartMgrDeinit (void)
 Shuts down the partition manager. More...
 
NvError QbPartMgrLoadTable (QbDriver DeviceId, NvU32 DeviceInstance, NvU64 StartLogicalByte, NvU64 NumLogicalBytes, NvBool IsSigned, NvBool IsEncrypted)
 Reads the Partition Table from specified storage device. More...
 
NvError QbPrependBootChainPrefix (NvS8 *pPartName, NvU32 Size, NvBool IsActiveChain)
 
NvError QbGetPartNameFromType (QbPartitionType PartType, NvBool IsActiveChain, NvS8 *pPartName, NvS32 PartNameBufferSize)
 
NvError QbPartMgrQueryIvcChannelInfo (NvU32 PartId, NvU32 *pIvc)
 This API is used by update library to query IVC channel info for a partition specified by partition id. More...
 
NvError QbPartMgrLoadAllPt (QbDriver DeviceId, NvU32 DeviceInstance)
 This API is used by update library to load partition table. More...
 
NvError QbPartMgrLoadSecondLevelPt (QbDriver DeviceId, NvU32 DeviceInstance)
 This API is used by the update library for loading second level PT. More...
 
void QbPartMgrLoadAllGuestPt (void)
 Iterates over the global PT for guest blobs found. More...
 
NvError QbUpdateGuestPartInfo (void)
 Updates the guest-related partition information in the Partition Table. More...
 
NvError QbUpdateGuestPartTableWithSysInfo (void)
 Updates the PT with information in SysInfo. More...
 
NvError QbPartMgrCreateTableStart (NvU32 NumPartitions)
 Allocates memory for partition table and fills the default PT header. More...
 
NvError QbPartMgrCreateTableFinish (void)
 Returns with a success indication if a Partition Table has been created. More...
 
NvError QbPartMgrAddTableEntry (NvU32 PartId, char *pPartName, char *pGuestPartName, QbPartInfo PartInfo, QbAllocPartArgs PartArgs)
 Adds an entry to the Partition Table. More...
 
NvError QbPartMgrSaveTable (QbDriver DeviceId, NvU32 DevInstance, NvBool SignTable, NvBool EncryptTable, NvS8 *FileName)
 Writes the Partition Table to the storage device. More...
 
NvError QbPartMgrGetIdByName (const char *PartitionName, NvU32 *PartitionId)
 Returns the partition ID for the named partition. More...
 
NvError QbPartMgrGetIdByType (QbPartitionType PartitionType, NvU32 *PartitionId)
 Returns the partition ID for the partition type. More...
 
NvError QbPartMgrGetNameById (NvU32 PartitionId, char *PartitionName)
 Returns the name of the specified partition ID. More...
 
NvError QbPartMgrGetNameByIdFromBuffer (NvU32 PartitionId, char *PartitionName, QbPartitionTable QbPartTable)
 Returns the name of the specified partition ID for the input PT buffer. More...
 
NvError QbPartMgrGetBootCompHdrPartId (NvU32 PartitionId, NvU32 *BootCompHdrPartId)
 Returns the Partition ID of the partition that has the BCH for the given partition. More...
 
NvError QbPartMgrGetPartInfo (NvU32 PartitionId, QbPartInfo *pPartInfo)
 Gets information about the location, size, and other attributes for the specified partition. More...
 
NvError QbPartMgrGetPartInfoFromBuffer (NvU32 PartitionId, QbPartInfo *pPartInfo, QbPartitionTable QbPartTable)
 Gets information about the location, size, and other attributes for the specified partition for the input PT buffer. More...
 
NvU32 QbPartMgrGetNextId (NvU32 PartitionId)
 Iterates over the partition IDs in the Partition Table. More...
 
NvU32 QbPartMgrGetNextIdFromBuffer (NvU32 PartitionId, QbPartitionTable QbPartTable)
 Iterates over the partition IDs in the input PT buffer. More...
 
NvU32 QbPartMgrGetNextIdForDeviceInstance (NvU32 DeviceId, NvU32 DeviceInstance, NvU32 PartitionId)
 Iterates over partition IDs in the Partition Table, where only certain IDs are considered. More...
 
NvError QbPartMgrGetNextDeviceInstance (NvU32 DeviceId, NvU32 DeviceInstance, NvU32 *NextDeviceId, NvU32 *NextDeviceInstance)
 Finds the next device ID and device Instance in the PT relative to the given device ID and device Instance. More...
 
NvU32 QbPartMgrGetNumPartition (void)
 Gets the number of the partition. More...
 
NvError QbPartMgrShowPT (void)
 Prints the partition table. More...
 
NvError QbDeviceGetPartitionIdByOffset (QbDriver DriverType, NvU32 Instance, NvU64 Offset, NvU32 *PartitionId)
 Finds the partition in which the given offset lies. More...
 
NvError NvLoadPtFromFile (NvS8 *pPtImagePath)
 Loads partition table from specified file. More...
 
NvError NvLoadPtFromFileToBuffer (NvS8 *pPtImagePath, NvBool IsSigned, QbPartitionTable **ppQbPartTable)
 Loads partition table from specified file to a PT buffer provided back to caller. More...
 

Macro Definition Documentation

#define GPT_SIZE_IN_SECTORS   33

Definition at line 76 of file qbpartmgr.h.

#define GUEST_BOOT_PARTITION_FLAG   0x80000000

Definition at line 77 of file qbpartmgr.h.

#define MAX_NUM_PARTITIONS   (MAX_PARTITIONS_INDEX - 1)

Definition at line 75 of file qbpartmgr.h.

#define MAX_PARTITIONS_INDEX   41

Definition at line 74 of file qbpartmgr.h.

#define PT_LEVEL_1   (1)

Definition at line 79 of file qbpartmgr.h.

#define PT_LEVEL_2   (2)

Definition at line 80 of file qbpartmgr.h.

Typedef Documentation

Function Documentation

NvError NvLoadPtFromFile ( NvS8 *  pPtImagePath)

Loads partition table from specified file.

Parameters
pPtImagePathA pointer to the input file containing blob of PT.
Returns
NvSuccess if successful, or the appropriate error code.
NvError NvLoadPtFromFileToBuffer ( NvS8 *  pPtImagePath,
NvBool  IsSigned,
QbPartitionTable **  ppQbPartTable 
)

Loads partition table from specified file to a PT buffer provided back to caller.

Parameters
pPtImagePathA pointer to the input file containing blob of PT.
IsSignedflag to indicate if PT is signed
ppQbPartTableA pointer to a pointer to the output PT buffer
Returns
NvSuccess if successful, or the appropriate error code.
NvError QbDeviceGetPartitionIdByOffset ( QbDriver  DriverType,
NvU32  Instance,
NvU64  Offset,
NvU32 *  PartitionId 
)

Finds the partition in which the given offset lies.

Parameters
[in]DriverTypeDriver type as defined in the QbDriver enumeration.
[in]InstanceDevice instance for which this information is required.
[in]OffsetAbsolute address in the device.
[out]PartitionIdA pointer where the function returns the partition to which the offset belongs.
Returns
NvSuccess if successful, or the appropriate error code.
NvError QbGetPartNameFromType ( QbPartitionType  PartType,
NvBool  IsActiveChain,
NvS8 *  pPartName,
NvS32  PartNameBufferSize 
)
NvError QbLoadAndInitPartMgr ( void  )

Loads and initializes partitions.

This function does the following:

  • Finds the location of the PT in the storage.
  • Loads the PT into the memory.
  • Invokes the PT APIs to initialize the PT.

Depending on whether booting native or virtual systems, this function differs on where it finds the location of the PT.

Returns
NvSuccess in case of no Error. Error code otherwise
NvError QbPartMgrAddTableEntry ( NvU32  PartId,
char *  pPartName,
char *  pGuestPartName,
QbPartInfo  PartInfo,
QbAllocPartArgs  PartArgs 
)

Adds an entry to the Partition Table.

Details related to mounting a file system on the partition can be found in the description of QbFsMountInfo.

Warning
Current implementation requires PartitionName and MountPath (from QbFsMountInfo) to be identical. To ensure this constraint is met, the value of MountPath is overridden and forced to the value of the PartitionName.
Parameters
PartIdID of the partition to add.
pPartNameA pointer to the partition name.
pGuestPartNameA pointer to the Guest partition name.
PartInfoBasic information specifying partition properties like logical/physical address, size, etc.
PartArgsAdditional information for deriving properties of the partition.
Returns
NvSuccess Partition creation is successful.
NvError QbPartMgrCreateTableFinish ( void  )

Returns with a success indication if a Partition Table has been created.

Returns
NvError_NotSupported Function not yet supported.
NvError QbPartMgrCreateTableStart ( NvU32  NumPartitions)

Allocates memory for partition table and fills the default PT header.

Parameters
NumPartitionsThe number of partitions to be added.
Return values
NvError_SuccessNo Error.
NvError_BadParameterInvalid value for NumPartitions.
NvError_InsufficientMemoryNo free memory available.
void QbPartMgrDeinit ( void  )

Shuts down the partition manager.

NvError QbPartMgrGetBootCompHdrPartId ( NvU32  PartitionId,
NvU32 *  BootCompHdrPartId 
)

Returns the Partition ID of the partition that has the BCH for the given partition.

Parameters
[in]PartitionIdA partition ID to look up.
[out]BootCompHdrPartIdPartition ID for the boot component header for the specified partition.
Return values
NvSuccessPartition ID lookup was successful.
NvError_PartitionNotExistThe partition ID does not exist.
NvError_BadValueThe boot component header partition ID for the given partition ID was invalid.
NvError_NotInitializedThe Partition Table was not initialized.
NvError QbPartMgrGetIdByName ( const char *  PartitionName,
NvU32 *  PartitionId 
)

Returns the partition ID for the named partition.

Parameters
[in]PartitionNameName of the partition.
[out]PartitionIdPointer to the partition's ID.
Return values
NvSuccessPartition name lookup is successful.
NvError_BadValuePartition name not found.
NvError QbPartMgrGetIdByType ( QbPartitionType  PartitionType,
NvU32 *  PartitionId 
)

Returns the partition ID for the partition type.

Parameters
[in]PartitionTypePartition type.
[out]PartitionIdPointer to the partition's ID.
Return values
NvSuccessPartition type lookup is successful.
NvError_PartitionNotExistPartition type not found.
NvError QbPartMgrGetNameById ( NvU32  PartitionId,
char *  PartitionName 
)

Returns the name of the specified partition ID.

Parameters
[in]PartitionIdPartition ID to look up.
[out]PartitionNameName of the corresponding partition.
Return values
NvSuccessPartition ID lookup is successful.
NvError_BadValuePartition ID not found.
NvError QbPartMgrGetNameByIdFromBuffer ( NvU32  PartitionId,
char *  PartitionName,
QbPartitionTable  QbPartTable 
)

Returns the name of the specified partition ID for the input PT buffer.

Parameters
[in]PartitionIdPartition ID to look up.
[in]QbPartTablePT buffer
[out]PartitionNameName of the corresponding partition.
Return values
NvSuccessPartition ID lookup is successful.
NvError_BadValuePartition ID not found.
NvError QbPartMgrGetNextDeviceInstance ( NvU32  DeviceId,
NvU32  DeviceInstance,
NvU32 *  NextDeviceId,
NvU32 *  NextDeviceInstance 
)

Finds the next device ID and device Instance in the PT relative to the given device ID and device Instance.

The function returns zero when either of the following occurs:

  • The end of the device list is encountered or
  • The specified device ID or device instance was not found.
Parameters
[in]DeviceIdDevice ID for the current partition.
[in]DeviceInstanceDevice instance for the current partition.
[out]*NextDeviceIdA pointer where the function returns the next deviceId value.
[out]*NextDeviceInstanceA pointer where the function returns the next deviceInstance value.
Returns
NvSuccess
NvU32 QbPartMgrGetNextId ( NvU32  PartitionId)

Iterates over the partition IDs in the Partition Table.

This iterator returns the ID of the next partition following the partition with the specified ID.

  • To obtain the ID of the first partition in the Partition Table, set PartitionId to zero (0).
  • To walk through all partition IDs, call QbPartMgrGetNextId() multiple times, each time passing in the output from the previous invocation.
Parameters
PartitionIdPartition ID for the current partition. Specify zero to look up the ID of the first partition in the Partition Table.
Returns
Partition ID for the next partition.
The function returns zero (0) when either of the following occurs:
  • End of the Partition Table is encountered.
  • Specified partition ID was not found.
NvU32 QbPartMgrGetNextIdForDeviceInstance ( NvU32  DeviceId,
NvU32  DeviceInstance,
NvU32  PartitionId 
)

Iterates over partition IDs in the Partition Table, where only certain IDs are considered.

This iterator returns the ID of the next partition following the partition with the specified ID with condition that deviceId and Instance should match as requested.

  • To obtain the ID of the first partition in the Partition Table, set PartitionId to zero (0).
  • To walk through all partition IDs, call QbPartMgrGetNextIdForDeviceInstance() multiple times, each time passing in the output from the previous invocation.
Parameters
[in]DeviceIdDeviceId for the current partition.
[in]DeviceInstanceDeviceInstance for the current partition.
[in]PartitionIdPartition ID for the current partition. Specify zero to look up the ID of first partition in the Partition Table.
Returns
Partition ID for the next partition.
The function returns zero (0) when either of the following occurs:
  • End of the Partition Table is encountered.
  • Specified partition ID was not found.
NvU32 QbPartMgrGetNextIdFromBuffer ( NvU32  PartitionId,
QbPartitionTable  QbPartTable 
)

Iterates over the partition IDs in the input PT buffer.

This iterator returns the ID of the next partition following the partition with the specified ID.

  • To obtain the ID of the first partition in the Partition Table, set PartitionId to zero (0).
  • To walk through all partition IDs, call QbPartMgrGetNextId() multiple times, each time passing in the output from the previous invocation.
Parameters
PartitionIdPartition ID for the current partition. Specify zero to look up the ID of the first partition in the Partition Table.
QbPartTablePT buffer
Returns
Partition ID for the next partition.
The function returns zero (0) when either of the following occurs:
  • End of the Partition Table is encountered.
  • Specified partition ID was not found.
NvU32 QbPartMgrGetNumPartition ( void  )

Gets the number of the partition.

Returns
Number of partition
NvError QbPartMgrGetPartInfo ( NvU32  PartitionId,
QbPartInfo *  pPartInfo 
)

Gets information about the location, size, and other attributes for the specified partition.

Parameters
[in]PartitionIdPartition ID to look up.
[out]pPartInfoPointer to the QbPartInfo structure for the specified partition.
Return values
NvSuccessPartition information retrieved successfully.
NvError_BadValuePartition ID not found.
NvError QbPartMgrGetPartInfoFromBuffer ( NvU32  PartitionId,
QbPartInfo *  pPartInfo,
QbPartitionTable  QbPartTable 
)

Gets information about the location, size, and other attributes for the specified partition for the input PT buffer.

Parameters
[in]PartitionIdPartition ID to look up.
[out]pPartInfoPointer to the QbPartInfo structure for the specified partition.
[in]QbPartTablePT buffer
Return values
NvSuccessPartition information retrieved successfully.
NvError_BadValuePartition ID not found.
NvError QbPartMgrInit ( void  )

Initializes the partition manager.

Returns
NvError_Success No Error
void QbPartMgrLoadAllGuestPt ( void  )

Iterates over the global PT for guest blobs found.

For each guest blob it finds, this function:

  1. Loads partition table for the guest.
  2. Updates offsets of partitions in that table to make them absolute.
  3. Updates partition names and adds guest ID at the beginning.
  4. Appends the updated entries of the guest PT to the global PT.

If guest PT is not found for some guest, this function prints a warning and continues.

NvError QbPartMgrLoadAllPt ( QbDriver  DeviceId,
NvU32  DeviceInstance 
)

This API is used by update library to load partition table.

It loads partition tables for inactive chain at all the three levels.

Parameters
DeviceIdDevice ID of the device where the BR BCT resides.
DeviceInstanceDevice Instance of the device where the BR BCT resides.
Returns
NvSuccess in case of no Error. Error code otherwise
NvError QbPartMgrLoadSecondLevelPt ( QbDriver  DeviceId,
NvU32  DeviceInstance 
)

This API is used by the update library for loading second level PT.

Iterates over the partitions in first level PT to check if second level PT is present. It looks for a partition:

  1. which is a boot-chain blob containing boot-firmware partitions.
  2. Belongs to inactive chain.
  3. Belongs to boot (device, instance).

Once such a partition is found, this function:

  1. loads partition table from the beginning of the blob from storage.
  2. Updates offsets of the partitions in that table to make them absolute.
  3. Updates partition ids to make them unique.
  4. Appends the entries of this updated PT to global in-memoery PT.

If second level PT is expected, but not found, this function prints a warning and continues. This is to support "--updatept" feature.

Parameters
DeviceIdStorage device type.
DeviceInstanceThe instance of the storage device.
Returns
NvSuccess in case of no Error. Error code otherwise
NvError QbPartMgrLoadTable ( QbDriver  DeviceId,
NvU32  DeviceInstance,
NvU64  StartLogicalByte,
NvU64  NumLogicalBytes,
NvBool  IsSigned,
NvBool  IsEncrypted 
)

Reads the Partition Table from specified storage device.

Up to NumLogicalSectors are searched in an effort to find a valid Partition Table.

Parameters
DeviceIdStorage device type.
DeviceInstanceThe instance of the storage device.
StartLogicalByteFirst Byte to read when searching for Partition Table.
NumLogicalBytesMaximum Byte to read when searching for Partition Table.
IsSignedIf NV_TRUE, check signature on partition table image loaded from storage device; if NV_FALSE, don't check signature.
IsEncryptedIf NV_TRUE, decrypt partition table image loaded from storage device; if NV_FALSE, don't perform decryption.
Returns
NvSuccess if the partition table load was successful, or an error. Errors include:
  • NvError_NotInitialized
  • NvError_ReadFailed Partition Table if the load operation failed.
  • NvError_InsufficientMemory
  • NvError_BadParameter
NvError QbPartMgrQueryIvcChannelInfo ( NvU32  PartId,
NvU32 *  pIvc 
)

This API is used by update library to query IVC channel info for a partition specified by partition id.

It will look into the partition table and return corresponding IVC channel info.

Parameters
PartIdpartition id of the required partition
pIvcPointer to the buffer where this function stores IVC info.
Returns
NvSuccess in case of no Error. Error code otherwise
NvError QbPartMgrSaveTable ( QbDriver  DeviceId,
NvU32  DevInstance,
NvBool  SignTable,
NvBool  EncryptTable,
NvS8 *  FileName 
)

Writes the Partition Table to the storage device.

The caller specifies the partition in which the Partition Table is to be stored. Multiple copies of the Partition Table are written, as many as will fit in the partition.

The Partition Table can optionally be signed and/or encrypted with the Secure Storage Key (SSK) before being written to the storage device.

Parameters
DeviceIdID of device.
DevInstanceDevice Instance of device.
SignTableNV_TRUE if Partition Table is to be signed, else NV_FALSE.
EncryptTableNV_TRUE if Partition Table is to be encrypted, else NV_FALSE.
[in]FileNameA pointer to the filename where the partition table is saved. NULL saves the PT to the device.
Returns
NvSuccess if Partition Table save is successful.
NvError QbPartMgrShowPT ( void  )

Prints the partition table.

Returns
NvSuccess if successful, or NvError_NotInitialized if the partition table is not initialized.
NvError QbPrependBootChainPrefix ( NvS8 *  pPartName,
NvU32  Size,
NvBool  IsActiveChain 
)
NvBool QbQueryThreeLevelPtInfo ( void  )

Query information about 3-level PT.

This function returns a flag telling whether the system is booted with new 3-level PT layout or old 2-level PT layout.

Returns
NV_FALSE if system is booted with 2-level PT.
NV_TRUE if system is booted with 3-level PT.
NvError QbUpdateGuestPartInfo ( void  )

Updates the guest-related partition information in the Partition Table.

For use with the OS loader, as opposed to the partition loader.

NvError QbUpdateGuestPartTableWithSysInfo ( void  )

Updates the PT with information in SysInfo.