NVHV::User interface

Detailed Description

Description: NvTegraHv library provides interfaces to request virtualization system for various services.

Note

Users should belong to 'nvhv' group defined in /etc/groups to access these interfaces.

Macros
#define	DISPLAY_VM   "DISPLAY_VM"

Enumerations
enum	NvOsType {   Os_Non_Native = 0,   Os_Native = 1,   Os_Detection_Failed = -1 }
	enum for OS type More...

Functions
int32_t	NvHvYieldVcpu (uint32_t vm_id, uint32_t timeout_us)
	API to request Guest VM to yield VCPU to a low priority VM. More...
int32_t	NvHvCheckOsNative (void)
	API to check whether running on Virtualized System or Native. More...
int32_t	NvHvGetOsVmId (uint32_t *vmid)
	API to get Vitual Machine ID. More...

NvHv VCPU-Yield Access Control

Common Privileges

Description of custom abilities

nvhv/yield_vcpu

• Custom ability to yield VCPU of Guest VM to a low priority VM

Common privileges required for all NvHv VCPU-Yield APIs

• Service/Group Name: nvhv

Macro Definition Documentation

DISPLAY_VM

#define DISPLAY_VM   "DISPLAY_VM"

Definition at line 35 of file nvtegrahv.h.

Enumeration Type Documentation

NvOsType

enum NvOsType

enum for OS type

Enumerator
Os_Non_Native	OS is running as non native.
Os_Native	OS is running as Native.
Os_Detection_Failed	OS detection failed.

Definition at line 127 of file nvtegrahv.h.

Function Documentation

NvHvCheckOsNative()

int32_t NvHvCheckOsNative

(

void

)

API to check whether running on Virtualized System or Native.

This API internally checks if "/dev/nvhv" node is present or not. This devnode is present only on virtualized system.

Returns

0 Running on Virtualized System
1 Native
-1 Failed

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread safe: Yes
  • Async/Sync: Sync
• Required Privileges: None
• API Group
  • Initialization: Yes
  • Run time: Yes
  • De-initialization: Yes

NvHvGetOsVmId()

int32_t NvHvGetOsVmId

(

uint32_t *

vmid

)

API to get Vitual Machine ID.

This API requests virtualization system to get current VM ID.

Parameters

[out]

vmid

Guest VM ID. Memory for this shall be allocated by calling function/process.

Returns

EOK Success
ENODEV Failed to open NvHv device node
EINVAL Invalid argument
EFAULT devctl call to NvHv device node returned failure

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread safe: Yes
  • Async/Sync: Sync
• Required Privileges:
  • Custom abilities: nvhv/get_gid
• API Group
  • Initialization: Yes
  • Run time: Yes
  • De-initialization: Yes

NvHvYieldVcpu()

int32_t NvHvYieldVcpu	(	uint32_t	vm_id,
		uint32_t	timeout_us
	)

API to request Guest VM to yield VCPU to a low priority VM.

This API yields the VCPU to a low priority VM if no other higher priority process than the caller is ready to
run on this VCPU in the Guest VM. The API blocks till the time VCPU is yielded to the low priority VM is
expired (i.e. timeout) or till the low priority VM returns the VCPU actively.
The VCPU number is read from QNX device tree property "nvhv/yield_vcpu" which is updated by bootloader before launching NvHv resource manager. An IVC communication channel is established between Guest VM and the low priority VM to yield and return VCPU.
When the low priority VM releases it through the IVC communication channel or timeout occurs on Guest VM,
the VCPU is returned to Guest VM.
Timeout value 0 is an invalid input parameter because VCPU yielding for 0 microsecond is inappropriate.
Minimum timeout value is 1 microsecond and maximum timeout value is configured by "nvhv/max_timeout_us" property in QNX device tree (the default value of the configuration is 1000000 in microseconds).
QNX device tree property "nvhv/low_prio_vm" specifies the list of low priority VM Ids, user needs to
ensure that the VM IDs listed in the DT property are valid and correct based on PCT configuration.
But the resolution of timeout for QNX is millisecond because of limitation of ARM timer resolution.
So the timeout value internally rounds up to the next millisecond.

Parameters

[in]	vm_id	VM ID for low priority VM for which VCPU is requested to be yielded
[in]	timeout_us	Time for which the user is requesting to yield the VCPU to low priority VM The minimum value is 1 microsecond and maximum value is configured in device tree. (In QNX, the timeout value rounds up to the next millisecond due to limitation of ARM timer resolution)

Returns

EOK Success - VCPU is yielded successfully and returned to Guest VM by low priority VM releasing the VCPU
ENODEV Failed to open NvHv device node (potentially invalid VM ID)
ETIMEDOUT Success - VCPU is yielded successfully and taken back to Guest VM by timeout
EFAULT VCPU yielding operation failed
EINVAL Invalid timeout_us parameter (zero or exceeded maximum value)

Precondition

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Async/Sync: Sync
  • Re-entrant: Yes
• Required Privileges:
  • Custom abilities: nvhv/yield_vcpu
• API Group
  • Initialization: Yes
  • Run time: Yes
  • De-initialization: Yes