DT Configuration for VSE Driver#

On Linux, the VSE driver reads the engine nodes such as vse@xxxx and vtsec@xxxx and follows the nvidia,ivccfg phandles attached to each engine. Each phandle points to a child node under nvvse-ivccfgdb that describes one VSE IVC channel.

The DT configuration must stay aligned with the PCT configuration. Buffer limits, SMMU SID values, engine routing, and enabled IVC channels are expected to match.

Linux DT layout#

The Linux DT is split into two layers:

Per-engine nodes such as vse@xxxx and vtsec@xxxx define the engine-level configuration and list the IVC entries used by that engine.
A top-level nvvse-ivccfgdb node contains one child node per IVC channel.

Example:

<engine-node>@<controller-address> {
  compatible = "nvvse-plug-arch";
  se_port = <...>;
  se_engine_domain = <...>;
  se_engine_domain_instanceId = <...>;
  iommus = <&smmu... ...>;
  status = "okay";
  nvidia,ivccfg_cnt = <1>;
  nvidia,ivccfg = <&nvvse_ivccfg_301_alias>;
};

Properties in Linux engine nodes#

compatible: Identifies the Linux VSE engine node. Current DTs use "nvvse-plug-arch".
se_port: Identifies the engine type. The child entries referenced by nvidia,ivccfg must match this value.
se_engine_domain: Identifies the engine security domain. The child entries referenced by nvidia,ivccfg must match this value.
se_engine_domain_instanceId: Identifies the physical engine instance within the selected se_port and se_engine_domain. The child entries referenced by nvidia,ivccfg must match this value.
#zero-copy: Marks the engine as zero-copy capable. For every referenced IVC entry, zero_copy_supported must match this flag.
iommus: Provides the SMMU phandle and SID used by the engine. The SID must match the SID encoded in each referenced IVC entry’s se_sid.
status: Enables or disables the engine node.
dma-coherent: Indicates to the Linux DMA API that the SE uses coherent DMA and does not require manual cache maintenance operations.
hwrng_ivc_id: Optional IVC channel ID used to register the hardware RNG interface when supported by the platform.
nvidia,ivccfg_cnt: Number of phandles listed in nvidia,ivccfg. Supported range is 1 to 75.
nvidia,ivccfg: Array of phandles to child nodes under nvvse-ivccfgdb.

If #zero-copy is present, the channel is restricted to the zero-copy feature set supported by the driver. Zero-copy support is intended only for internal use cases.

Properties in each `nvvse-ivccfgdb` child#

Property	Description	Supported values / constraints
`se_comm_id`	Unique VSE communication channel ID.	`0` to `999`
`label`	Descriptive label for the channel.	String up to `32` characters.
`se_domain`	Security domain of the SE engine.	`0` non-secure
`se_port`	Engine type.	`0` AES, `1` SHA
`se_domain_instance_id`	Selects the engine instance within the port.	For `se_port = 0`: `0` GPSE-AES0, `1` GPSE-AES1, `2` GCSE1-AES0, `3` GCSE1-AES1, `4` GCSE2-AES0, `5` GCSE2-AES1 For `se_port = 1`: `0` GPSE-SHA, `1` GCSE1-SHA, `2` GCSE2-SHA
`virtual_instance_id`	Virtualized instance number used while enumerating device nodes for the engine.	Must be unique within a given engine instance space. AES port: `se_domain_instance_id = 0` or `1`: `0` to `10` `se_domain_instance_id = 2` or `4`: `0` to `18` `se_domain_instance_id = 3` or `5`: `0` to `11` SHA port: `se_domain_instance_id = 0`: `0` to `6` `se_domain_instance_id = 1` or `2`: `0` to `10`
`priority`	Channel priority. The Linux driver validates the value but does not otherwise use it.	`0` low priority, `1` high priority
`max_buffer_size`	Maximum mapped buffer size.	Less than `16 MB`
`zero_copy_supported`	Indicates whether zero-copy is supported for the channel.	`0` unsupported, `1` supported
`channel_group_id`	Group ID assigned to the VSE device node.	Numeric group ID.
`se_sid`	Per-entry SMMU phandle plus SID.	Must encode the same SID as the parent engine node’s `iommus` SID.
`gcm_decrypt_supported`	Indicates whether GCM decrypt is supported for the channel.	AES port: `1`; SHA port: `0`
`thread_attr`	Thread attribute value.	Unused on Linux.

Linux validation rules#

The Linux driver validates the following before enumerating a device node:

nvidia,ivccfg_cnt must match the number of phandles in nvidia,ivccfg.
se_comm_id must be unique across all VSE channels.
se_port, se_domain, and se_domain_instance_id in the child node must match the parent engine node’s se_port, se_engine_domain, and se_engine_domain_instanceId.
zero_copy_supported must match the presence of #zero-copy.
se_sid must encode the same SID as the parent engine’s iommus property.
gcm_decrypt_supported must be 1 for AES channels and 0 for SHA channels.

How to Add Entries#

Add a new child node under nvvse-ivccfgdb with the required named properties.
Add a phandle to that child node from the owning Linux engine node.
Update nvidia,ivccfg_cnt so the count matches the number of phandles.

Entry planning rules#

se_comm_id must match the IVC channel enabled in PCT.
se_domain, se_port, and se_domain_instance_id must match the PCT engine routing.
priority must match PCT when that field is used by the client stack.
max_buffer_size must not exceed the PCT limit.
se_sid must match the SMMU SID required for that engine instance.
channel_group_id is the group ID assigned to the VSE device node.
virtual_instance_id is the virtualized instance number used by the driver while enumerating device nodes. It must stay unique within the engine instance space exposed by the driver.
gcm_decrypt_supported must match the SoC contract:
On Thor, set gcm_decrypt_supported to 1 for AES channels and to 0 for SHA channels.

Examples#

Example Linux child entry:

nvvse_ivccfg_301_alias: nvvse_ivccfg_301 {
  se_comm_id = <301>;
  label = "Default_GPSE_AES0";
  se_domain = <0>;
  se_port = <0>;
  se_domain_instance_id = <0>;
  virtual_instance_id = <0>;
  priority = <0>;
  max_buffer_size = <(1 * 1024 * 1024)>;
  zero_copy_supported = <0>;
  channel_group_id = <2281>;
  se_sid = <&smmu1_mmu TEGRA_SID_SE_AES0_VM0>;
  gcm_decrypt_supported = <1>;
  thread_attr = <0xFF>;
};

How to Remove an Entry#

Remove the relevant phandle reference from the OS-specific parent node.
Delete the now-unused child node from nvvse-ivccfgdb if no other consumer references it.
Update nvidia,ivccfg_cnt so the count still matches.