SPI API Changes#

API Changes for Timeout Support and SPI_ERROR_HW_ERR Status#

Target Changes

Backward Compatible

Platform

OS

Timeout Support

7.2.3.0

New member interrupt_timeout_ms is added in spi_hal_xchange_info_t struct, in HAL header file (spi_hal.h). interrupt_timeout_ms is set by the user. For no timeout, interrupt_timeout_ms is set to SPI_TIMEOUT_INFINITE (0U) macro, which translates to infinite timeout (No timeout).

A new header file, nvspi_common.h, is included by spi_hal.h, which exports SPI_TIMEOUT_INFINITE macro to both HAL and the user.

7.2.4.0

HAL supports timeout and “No timeout” when waiting for hardware interrupt in the 7.2.5.0 release. HAL should use the interrupt_timeout_ms variable, passed by the core driver, to determine the timeout value.

7.2.5.0

Nvidia QNX SPI allows users to set timeout in 7.2.5.0; HAL should support timeout and “No timeout” when waiting for hardware interrupt by release 7.2.5.0.

Remove SPI_ERROR_HW_ERR Status

7.2.4.0

Add SPI status definitions in nvspi_common.h (without SPI_HAL_ERROR_HW_ERR)

HAL should use SPI status definitions in nvspi_common.h instead of definitions in spi_hal.h by 7.2.5.0

7.2.5.0

Remove SPI status definitions in spi_hal.h

SPI HAL major version +1 since SPI status definitions in spi_hal.h are not available in 7.2.5.0 (the change is not backward compatible)

No

NSR, SR

QNX only

Migration Path

Dimensity C-X1 to Dimensity C-X1

Migration Release Path

7.0 to 7.2

Migration Rationale

Timeout Support

Refer to DOS_UREQ_010 in the NVIDIA DriveOS Safety Manual. The customer should handle timeout to avoid an extra kernel call (TimerTimeout())

Remove SPI_HAL_ERROR_HW_ERR

SPI_HW_ERROR_HW_ERR is legacy. The change consolidates signal for any FIFO-related ERR signal. The software implementation should abstract hardware details.

Defining SPI status in one file only (nvspi_common.h) avoids confusion

Steps to Migrate

HAL should support timeout and “No timeout” when waiting for HW interrupt by 7.2.5.0 release. HAL should use the interrupt_timeout_ms variable, passed by Core driver, to determine the timeout value.

HAL should use SPI status definitions in nvspi_common.h instead of definitions in spi_hal.h by 7.2.5.0

API Changes for spi_getstatus#

Target Changes

Backward Compatible

Platform

OS

In release 7.2.5.0, spi_getstatus will not report SPI_ERROR_HW_ERR.

The SPI status definition will move from nvspi_api.h to nvspi_common.h.

No

NSR, SR

QNX only

Migration Path

  • Orin to Thor

Migration Release Path

7.0 to 7.2

Migration Rationale

SPI_ERROR_HW_ERR is legacy from NVIDIA SPI hardware.

SPI status is shared for both customers and partners (DriveOS for Dimensity).

Steps to Migrate

If using SPI_ERROR_HW_ERR status, note that it is deprecated in release 7.2.5.0. nvspi_common.h is included by nvspi_api.h; there is no impact when using another SPI status

API Prototype Changes#

Target Changes

Backward Compatible

Platform

OS

The prototype of spi_read/spi_write/spi_xchange/spi_dma_xchange changed in the 7.2.5.0 release with the addition of a new parameter: interrupt_timeout_ms. This change does not apply to previous releases, and no action is required for those releases.

No

NSR, SR

QNX only

Migration Path

  • Orin to Thor

Migration Release Path

7.0 to 7.2

Migration Rationale

Customers should handle the timeout. If the QNX SPI driver does not use a timeout for the interrupt, the extra kernel call, TimerTimeout(), is not necessary. For additional information, refer to the NVIDIA DriveOS Safety Manual

Steps to Migrate

Add a parameter interrupt_timeout_ms when calling spi_read/spi_write/spi_xchange/spi_dma_xchange.

Transaction API Signature Reorder and DMA Length Tightening#

Target Changes

Backward Compatible

Platform

OS

  • The four SPI transaction APIs spi_read, spi_write, spi_xchange and spi_dma_xchange were re-ordered: the length parameter moved ahead of the buffer pointer(s), and a new uint32_t interrupt_timeout_ms parameter was inserted between length and the buffer pointer(s). The valid range is SPI_TIMEOUT_INFINITE or 1..UINT32_MAX.

  • The valid DMA exchange length range for spi_dma_xchange was tightened from 4..65516 to 4..16372, and the length is now required to be 4-byte aligned.

No. Source changes are required.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

6.5.4.2 to 7.2.5.0

Migration Rationale

Surface a per-transaction interrupt timeout to callers so they can bound transaction wait time while normalizing the four transaction APIs to a consistent (len, timeout, buffers) calling convention. The DMA length range is tightened to match the underlying controller capability.

Steps to Migrate

  1. Update every direct caller of spi_read / spi_write / spi_xchange / spi_dma_xchange to the new argument order and pass an explicit interrupt_timeout_ms.

    // Before
int64_t n = spi_read(fd, dev, buf, 256U);
int64_t m = spi_dma_xchange(fd, dev, wbuf, rbuf, 60000U);

    // After
int64_t n = spi_read(fd, dev, 256U, 100U, buf);
// DMA: length must be in [4..16372] and 4-byte aligned
int64_t m = spi_dma_xchange(fd, dev, 16372U, 100U, wbuf, rbuf);

  2. For spi_dma_xchange callers, clamp the transfer length to the new [4..16372] window and round up to a multiple of 4 bytes.

    Compile-time signal of this break: incompatible argument type passing 'void *' where 'uint32_t' is expected.

EPERM Error Code and Documentation Updates#

Target Changes

Backward Compatible

Platform

OS

  • EPERM (“No permission to access SPI device”) is now a documented errno on every SPI API that takes an fd: spi_close, spi_getdevinfo, spi_read, spi_write, spi_xchange, spi_dma_xchange and spi_getstatus.

  • The “Wrong iomsg message ID/command” error wording has been replaced by “Wrong devctl message ID/command” throughout.

  • spi_close return semantics were tightened to “0 for success, -1 if an error occurs”.

  • @pre clauses (for example, “spi_open() must be called”) and explicit Re-entrant: No annotations were added throughout the API documentation.

No. The source rebuilds, but runtime behavior changed.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

6.5.4.2 to 7.2.5.0

Migration Rationale

Document the privilege-related EPERM that callers may now observe under the new nvspi/cs custom ability scheme, and align the API documentation terminology and pre-condition annotations.

Steps to Migrate

  1. Audit every site that switches on errno after an SPI call and add an EPERM arm where appropriate.

    int64_t n = spi_read(fd, dev, len, 100U, buf);
if (n < 0 && errno == EPERM) { /* missing nvspi/cs ability */ }

  2. Update any in-house diagnostic strings that still reference “iomsg” to “devctl” to match the new API documentation wording.

nvspi/cs Custom Ability for Per-Chip-Select Access Control#

Target Changes

Backward Compatible

Platform

OS

  • A new access-control page documents the nvspi/cs:{value} custom ability. The 12-bit {value} uses a 0xXYZ sub-range encoding where X is the SPI instance number plus 1 (valid range 1..5) and YZ is the chip-select number (valid range 0..3).

  • All non-spi_open SPI APIs now require this ability. Previously they were documented as “Required privileges: None”.

  • The @usage doc-contract was reformatted to “Allowed execution state” with new “Implementation ASIL: QM” and “Maturity: GA” tags, and the defgroup was renumbered into spi_ifc.

No. All non-spi_open SPI APIs now require the new nvspi/cs:{value} custom ability; existing privilege manifests must be updated.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

6.5.4.2 to 7.2.5.0

Migration Rationale

Adopt the per-CS ability scheme so SPI access can be granted per chip-select rather than open-to-all, and align the safety doc-contract template across the BSP API surface.

Steps to Migrate

  1. Update the SPI privilege manifest for every process that performs SPI I/O. Grant nvspi/cs:{value} for every chip-select the process intends to access, encoding value as 0x<instance+1><cs> (for example, SPI0 CS2 -> 0x102).

  2. Validate at integration time that previously working processes that received “Required privileges: None” now receive EPERM from non-open SPI APIs unless the new ability has been granted.