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:

Creating a partition table and writing it out to a storage device. This happens only once, during system initialization. Thereafter, the PT is never modified for the remainder of the lifetime of the device.
Reading a pre-existing partition table from a storage device and querying it for information about the various partitions. This is the normal use case and happens at least once during each boot cycle.

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

typedef struct QbAllocPartArgsRec QbAllocPartArgs

Function Documentation

NvError NvLoadPtFromFile ( NvS8 * pPtImagePath )

Loads partition table from specified file.

Parameters

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

pPtImagePath	A pointer to the input file containing blob of PT.
IsSigned	flag to indicate if PT is signed
ppQbPartTable	A 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]	DriverType	Driver type as defined in the QbDriver enumeration.
[in]	Instance	Device instance for which this information is required.
[in]	Offset	Absolute address in the device.
[out]	PartitionId	A 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

PartId	ID of the partition to add.
pPartName	A pointer to the partition name.
pGuestPartName	A pointer to the Guest partition name.
PartInfo	Basic information specifying partition properties like logical/physical address, size, etc.
PartArgs	Additional 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

NumPartitions The number of partitions to be added.

Return values

NvError_Success	No Error.
NvError_BadParameter	Invalid value for NumPartitions.
NvError_InsufficientMemory	No 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]	PartitionId	A partition ID to look up.
[out]	BootCompHdrPartId	Partition ID for the boot component header for the specified partition.

Return values

NvSuccess	Partition ID lookup was successful.
NvError_PartitionNotExist	The partition ID does not exist.
NvError_BadValue	The boot component header partition ID for the given partition ID was invalid.
NvError_NotInitialized	The Partition Table was not initialized.

NvError QbPartMgrGetIdByName	(	const char *	PartitionName,
		NvU32 *	PartitionId
	)

Returns the partition ID for the named partition.

Parameters

[in]	PartitionName	Name of the partition.
[out]	PartitionId	Pointer to the partition's ID.

Return values

NvSuccess	Partition name lookup is successful.
NvError_BadValue	Partition name not found.

NvError QbPartMgrGetIdByType	(	QbPartitionType	PartitionType,
		NvU32 *	PartitionId
	)

Returns the partition ID for the partition type.

Parameters

[in]	PartitionType	Partition type.
[out]	PartitionId	Pointer to the partition's ID.

Return values

NvSuccess	Partition type lookup is successful.
NvError_PartitionNotExist	Partition type not found.

NvError QbPartMgrGetNameById	(	NvU32	PartitionId,
		char *	PartitionName
	)

Returns the name of the specified partition ID.

Parameters

[in]	PartitionId	Partition ID to look up.
[out]	PartitionName	Name of the corresponding partition.

Return values

NvSuccess	Partition ID lookup is successful.
NvError_BadValue	Partition 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]	PartitionId	Partition ID to look up.
[in]	QbPartTable	PT buffer
[out]	PartitionName	Name of the corresponding partition.

Return values

NvSuccess	Partition ID lookup is successful.
NvError_BadValue	Partition 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]	DeviceId	Device ID for the current partition.
[in]	DeviceInstance	Device instance for the current partition.
[out]	*NextDeviceId	A pointer where the function returns the next deviceId value.
[out]	*NextDeviceInstance	A 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

PartitionId Partition 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]	DeviceId	DeviceId for the current partition.
[in]	DeviceInstance	DeviceInstance for the current partition.
[in]	PartitionId	Partition 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

PartitionId	Partition ID for the current partition. Specify zero to look up the ID of the first partition in the Partition Table.
QbPartTable	PT 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]	PartitionId	Partition ID to look up.
[out]	pPartInfo	Pointer to the QbPartInfo structure for the specified partition.

Return values

NvSuccess	Partition information retrieved successfully.
NvError_BadValue	Partition 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]	PartitionId	Partition ID to look up.
[out]	pPartInfo	Pointer to the QbPartInfo structure for the specified partition.
[in]	QbPartTable	PT buffer

Return values

NvSuccess	Partition information retrieved successfully.
NvError_BadValue	Partition 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:

Loads partition table for the guest.
Updates offsets of partitions in that table to make them absolute.
Updates partition names and adds guest ID at the beginning.
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

DeviceId	Device ID of the device where the BR BCT resides.
DeviceInstance	Device 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:

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

Once such a partition is found, this function:

loads partition table from the beginning of the blob from storage.
Updates offsets of the partitions in that table to make them absolute.
Updates partition ids to make them unique.
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

DeviceId	Storage device type.
DeviceInstance	The 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

DeviceId	Storage device type.
DeviceInstance	The instance of the storage device.
StartLogicalByte	First Byte to read when searching for Partition Table.
NumLogicalBytes	Maximum Byte to read when searching for Partition Table.
IsSigned	If NV_TRUE, check signature on partition table image loaded from storage device; if NV_FALSE, don't check signature.
IsEncrypted	If 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

PartId	partition id of the required partition
pIvc	Pointer 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

	DeviceId	ID of device.
	DevInstance	Device Instance of device.
	SignTable	NV_TRUE if Partition Table is to be signed, else NV_FALSE.
	EncryptTable	NV_TRUE if Partition Table is to be encrypted, else NV_FALSE.
[in]	FileName	A 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.

NVIDIA DRIVE OS Linux API Reference

5.1.0.2 Release

Detailed Description

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

Typedef Documentation

Function Documentation