System Software Components and Interfaces
This topic provides guidance on using system software and component interfaces to interact with the platform. Examples of platform interfaces are file system components, I2C drivers, and SPI drivers.
Enabling/Disabling Serial Port Bus
The UART ports are configured via device tree (DT) nodes and boot loader configuration files. To reconfigure or update the UART port functionality:
• Change/update device tree files
• Enable the UART port
• Change/update the bootloader configuration files
• Optionally assign ownership of the port to a VM
The following sections detail how to accomplish these tasks.
Location and Default Configuration of Serial Device Tree Files
The serial ports are defined in the included device tree file:
drive-t186ref-foundation/bsp/device-tree/hardware/nvidia/soc/t19x/kernel-dts/tegra194-soc/tegra194-soc-uart.dtsi
All serial bus definitions are listed in this file and are disabled by default. For non-safety builds they are enabled in the included DT file:
drive-t186ref-foundation/bsp/device-tree/hardware/nvidia/platform/t19x/automotive/kernel-dts/e3550/common/tegra194-e3550-0001-A.dtsi
In QNX safety builds they are disabled in the safety override DT file:
drive-t186ref-<os>/bsp/device-tree/qnx-device-tree/platform/t19x/common/tegra194-drive-common-qnx-vm1-safety-overrides.dtsi
If you are working with dual-QNX there is a separate override for VM2:
drive-t186ref-<os>/bsp/device-tree/qnx-device-tree/platform/t19x/common/tegra194-drive-common-dual-qnx-vm2-safety-overrides.dtsi
By default, the only serial ports enabled are as follows:
Bus Function | Bus Name | DTB Node | Status Standard | Status Safety |
Debug serial | serial0 / uartc | serial@c280000 | Enabled | Disabled |
GPS/IMU | serial1 / uartb | serial@3110000 | Enabled | Enabled |
Enabling Debug Serial0 (UARTC) In Safety Configuration
In safety QNX platforms, the debug serial port is disabled by default. Three steps are required to enable it:
1. Edit DT file to enable serial0 bus (node serial@c280000)
2. Edit the disable_uart.subcfg under virtualization
3. Bind partitions with prod_debug_extra variant
To edit the DT file and enable the debug serial port (node serial@c280000), see the steps above.
To edit the disable_uart.subcfg from PDK_TOP:
1. Navigate to:
cd drive-t186ref-foundation/virtualization/pct
2. Navigate to the platform/SOC you wish to enable the debug serial. For this example, we are working with e3550b03-t194a and the QNX OS platform.
cd e3550b03-t194a/qnx
We want to edit disable_uart.subcfg to allow the debug console. There are six choices for the user:
Debug Level | Configuration Variable |
Disabled | Verbosity = 0 |
Critical | Verbosity = 1 |
Error | Verbosity = 2 |
Warning | Verbosity = 3 |
Informative | Verbosity = 4 |
Debug | Verbosity = 5 |
3. Choose the log level you want and save the file. Then, run bind partitions as normal to pick up the changes.
export PDK_TOP=$PWD
export NV_OUTDIR="$PDK_TOP/drive-t186ref-foundation/out"
export QNX_BASE="$PDK_TOP/toolchains/qnx_toolchain/"
export QNX_TARGET="$QNX_BASE/target/qnx7/"
export QNX_HOST="$QNX_BASE/host/linux/x86_64"
export QNX_TOP="$PDK_TOP/drive-t186ref-qnx"
export NV_ROOTFS_LOCAL_DIR="$QNX_TOP/targetfs"
cd drive-t186ref-foundation
make -f Makefile.bind PCT=qnx PCT_VARIANT=prod_debug_extra BOARD=e3550b03-t194a clean
make -f Makefile.bind PCT=qnx PCT_VARIANT=prod_debug_extra BOARD=e3550b03-t194a
4. Flash the target.
Changing the DTB Used By VM
To use a custom DTB within the VM:
• Alter the VM config file
• Make bind partitions
As with changing disable_uart.subcfg:
1. Navigate from PDK_TOP to:
cd drive-t186ref-foundation/virtualization/pct
2. Navigate to the platform/SOC you wish to reconfigure. For this example, we are working with e3550b03-t194a and the Linux OS platform.
cd e3550b03-t194a/linux
3. Edit linux_storage_emmc.cfg and change the file name under the kernel-dtb section to your custom DTB. In the config file the default fields are:
[partition]
name=kernel-dtb
allocation_policy=sequential
filesystem_type=basic
size=0x40000
partition_attribute=0
filename=<PDK_TOP>/drive-t186ref-linux/kernel/tegra194-<DTB_VARIANT>-linux-driveav<COMMSEC_ENABLED_SUFFIX><C2C_ENABLED_SUFFIX>-vm1.dtb
os_args="aurixfw=AFW root=/dev/vblkdev0p1 gpt rootwait ip=off rw gpt console=ttyS0,115200n8 tegra_keep_boot_clocks cma=536870912 disable_android_paranoid_network sdhci_tegra.en_boot_part_access=1 "
authentication_group=1
4. After you edit the config file, run bind partitions as shown above.
Assigning Ownership to Guest VM
The UART port can be mapped to a specific VM address space so that it is the sole owner of the port. There are three choices that can be made:
• Hypervisor owned: All access is trapped by hypervisor
• Guest<n> owned: The UART port is mapped to the numbered VM address space
• Unassigned: Not owned by any VM
The default configuration can be found in:
drive-t186ref-foundation/virtualization/pct/<BOARD_TYPE>/drive_av/guest_io_periph_assign.h
The current default configuration is as follows
UART PORT | OWNER |
TEGRA_UART_A | UNASSIGNED |
TEGRA_UART_B | GOS0_VM |
TEGRA_UART_C | HYPERVISOR |
TEGRA_UART_D | UNASSIGNED |
TEGRA_UART_E | UNASSIGNED |
TEGRA_UART_F | UNASSIGNED |
Calculating GPIO Index in Linux
The following section describes how to calculate the GPIO index:
1. The Xavier GPIOs are grouped in banks and each bank has up to 8 pins. The bank and the pin information of a GPIO is fundamental for calculating its index.
GPIO is represented as X.Y, where:
• X encodes the bank and can have the following values: PA, PB, …, PZ or AA, BB, …, GG.
For the banks with naming scheme P*, the “P” must be ignored, i.e., “PA” refers to bank A.
• Y encodes the pin within a bank. For example, 00 for pin 0, 01 for pin 1, …, and 07 for pin 7.
2. The banks are associated to a base and can also be sequentially translated into a bank_index as shown in the table below:
The base numbering may change in cases where customization is done in kernel and can be identified using the dmesg log:
[ 2.659198] gpiochip_setup_dev: registered GPIOs 288 to 511 on device: gpiochip0 (tegra-gpio)
[ 2.671152] gpiochip_setup_dev: registered GPIOs 248 to 287 on device: gpiochip1 (tegra-gpio-aon)
The base is 288 for tegra-gpio and 248 for tegra-gpio-aon from the above log.
3. The GPIO index can be calculated as: GPIO_index = base + bank_index*8 + pin.
The following is an example of calculating the GPIO index for PS.05.
a) PS.05 represents bank S and pin 5.
b) Bank S has bank_index 18 and base 288(tegra-gpio base)
c) GPIO index is 437 (437 = 288 + 18*8 +5)
Persistence Across Bootburn Flashing Using Persistent Partition
NVIDIA DRIVE OS provides persistence across bootburn flashing as part of the secure login feature. The persistence works by reserving a partition in bootburn that is not written or modified in the flashing process. Due to this effect, the data in this partition is completely unchanged across bootburn flashing.
Persistent Data Across Flashing
The following data is persistent across flashing:
1. SSH host keys that uniquely identifies a system during SSH connection setup.
2. User account metadata files such as /etc/passwd, /etc/shadow, etc. that contains the user’s list, user’s hashed password, etc.
The exact list of persistent data is located at:
<top>/drive-t186ref-linux/modules/scripts/copy_security_data.sh
Note: | Even though user account data is persistent, the user’s data itself is not persistent across flashing. |
Why You Require Persistent Data Across Flashing
As shown in the previous section, persistent data is used to store identity-based data. For instance, SSH-keys existing after a bootburn flashing indicates that system’s identity has not been compromised.
Similarly, user account data shows the identity of the end-users in the system.
Workflow with Persistent Partition
The following flashing iterations demonstrate persistence partition workflow when the secure login feature is enabled:
1. Persistence partition is empty.
2. Platform is flashed via bootburn.
3. OEM-config executes because user metadata is NULL and creates the users.
4. Persistence service copies data from rootfs (/) partition to persistent partition.
5. Persistence partition overlays its content on top of rootfs (/) partition.
6. Any new files created under /etc goes into the persistence partition.
7. Platform is flashed again via bootburn.
8. OEM-config execution is skipped.
9. The end-user sees the set of users established after Step 3.
Note: | At step 9, if a user with UID 1000 was added in flashing and has user data, then as a one case exception, persistence service renames the user from rootfs partition to the user from persistence partition. |
Methods to Reset Persistent Partition
The instructions below assume Xavier A as the example. The instructions apply equally for Xavier B, or both Xavier A and Xavier B at once.
If access to target is NOT available: Since console access is not present, change the PCT cfg to ensure bootburn erases the persistent partition.
1. Update cfgs depending on Xavier A or Xavier B:
<top>/drive-t186ref-foundation/virtualization/pct/e3550b03-t194a/linux/global_storage_qspi.cfg
<top>/drive-t186ref-foundation/virtualization/pct/e3550b03-t194b/linux/global_storage_qspi.cfg
2. For each of the files, add the following files in the pers-gos1 partition just before the #endif:
filesystem_type=ext2
dirname=/tmp/tmp
3. Create an empty directory /tmp/tmp:
# mkdir /tmp/tmp
4. Execute bind partitions to ensure cfg changes take effect. (As an example, for Xavier A):
cd <top>/drive-t186ref-foundation
make -f Makefile.bind BOARD=e3550b03-t194a PCT=linux
5. Flash with the bound configuration to Xavier A (as an example):
./bootburn.sh -b e3550b03-t194a -B qspi
DRIVE OS Linus SDK Upgrade/Downgrade Based Persistent Partition Handling
When end-user downgrades or upgrades to a new DRIVE OS Linus SDK version, persistent partition data influences the code execution path. This section describes the different cases and what action end-users must take to ensure seamless change from one version to another.
When changing SDK versions with regard to persistent partition, the following cases do not require any action:
• Old version < 5.2.6.0 and new version < 5.2.6.0 and new version <= old version:
• Old version < 5.2.6.0 and new version < 5.2.6.0 and new version >= old version:
• Old version < 5.2.6.0 and new version >= 5.2.6.0:
The following cases require you to format persistent partition using the method in Methods to Reset Persistent Partition:
• Old version >= 5.2.6.0 and new version < 5.2.6.0:
• Old version > 5.2.6.0 and new version > 5.2.6.0 and new version <= old version:
• Old version > 5.2.6.0 and New version > 5.2.6.0 and New version >= Old version