Options Available in the "required" Section - 2024.2 English - UG1647

Porting Guide for embeddedsw Components System Device Tree Based Build Flow (UG1647)
Document ID
UG1647
Release Date
2024-11-27
Version
2024.2 English

The following options are available in the required section:

Key Notes Config Structure XPARAMETERS Usage Of Padding
compatible The existing embedded software driver uses "DEVICE_ID" in the driver config structure to get the peripheral instance. This approach is now being replaced with Base Address.

Base Address of the peripheral instance is derived used the reg property.

Filler for DEVICE_ID. 
#define XPAR_{node_label_name}_COMPATIBLE {value}

Canonical define:

#define XPAR_X{driver_name}_{index}_COMPATIBLE {value}
 Not allowed
reg Device tree nodes usually have reg property in <base_addr size> format.

This reg property is used to derive BASE_ADDRESS and HIGH_ADDRESS of the IP instance.

 Filler for Base Address. 
#define XPAR_{node_label_name}_BASEADDR {hex(base_addr)}
#define XPAR_{node_label_name}_HIGHADDR {hex(base_addr + size -1)}

Canonical define:

#define XPAR_X{driver_name}_{index}_BASEADDR {hex(base_addr)}

#define XPAR_X{driver_name}_{index}_HIGHADDR {hex(base_addr + size -1)}
 For example: reg: 2.

This is needed if the config structure has more than one base address in sequence. Check GIC node and its config structure for more information.
interrupts Interrupt property format for a mapped interrupt in a system device tree looks like: <PPI/SPI interrupt_id trigger_type>. This property format is converted to generate the Interrupt Property which has the following format:
  • bits[11:0] interrupt-id
  • bits[15:12] trigger type and level flags
  • bits[19:16] CPU Mask
  • bit[20] interrupt-type (1: PPI, 0: SPI)
 Generated the interrupt hex value. 
#define XPAR_{node_label_name}_INTERRUPTS {hex(derived_intr_format)}

Canonical define:

#define XPAR_X{driver_name}_{index}_INTERRUPTS {hex(derived_intr_format)}
 For example, interrupts: 2.

This is needed when a peripheral can have multiple interrupts attached.

  • Config_structure: A C list containing all the interrupts in the earlier described format is added to the config structure.
  • XPARAMETERS:
    • #define XPAR_{node_label_name}_INTERRUPTS_<x> {hex(derived_intr_format[x])}, where x ranges from 0 to padding - 1.
    • Examples:
      • #define XPAR_{node_label_name}_INTERRUPTS_0 {hex(derived_intr_format[0])}
      • #define XPAR_{node_label_name}_INTERRUPTS_1 {hex(derived_intr_format[1])}
interrupt-parent Adds the base address of the interrupt-parent, which is usually the base address of GIC or INTC. Base address of the interrupt-parent. 
#define XPAR_{node_label_name}_INTERRUPT_PARENT {hex(intr_parent_addr)}

Canonical define:

#define XPAR_X{driver_name}_{index}_INTERRUPT_PARENT {hex(intr_parent_addr)}
 Not allowed
child,required Generates the sub nodes/arrays. A C array of child node's property values. 
#define XPAR_{node_label_name}_{j}_{p.upper()} {val}

Canonical define:

#define XPAR_X{driver_name}_{index}_{j}_{<property>.upper()} {val}
 Not allowed
Any other property (<property> or xlnx,<property>) Property value is of type string. Value is used as it is. 
#define XPAR_{node_label_name}_{<property>.upper()} {string value}

Canonical define:

#define XPAR_X{driver_name}_{index}_{<property>.upper()} {string value}
 For example: xlnx,num_slcr_addr: 2.
  • Mainly used for 64-bit addresses and floating values converted to hex.
  • Concatenates multiple 32-bit hex number/addresses into one 64-bit hex number/address.
  • XPARAMETERS: #define XPAR_{label_name}_{<property>.upper()} {combined_address_prop}
Property value is of type phandle:

If the IP property points to a different device-tree node reference, the YAML key must be denoted as: <property>: phandle.

 Base Address of the IP on which this property depends is used. 
#define XPAR_{node_label_name}_{prop.upper()} {hex(base_addr of the new IP)}

Canonical define:

#define XPAR_X{driver_name}_{index}_{prop.upper()} {hex(base_addr of the new IP)}
Property value is of type int. Convert into hex and use the hex value. 
#define XPAR_{node_label_name}_{<property>.upper()} {hex(int_value)}

Canonical define:

#define XPAR_X{driver_name}_{index}_{<property>.upper()} {hex(int_value)}
Property value is of type list. List values are fomatted as a C list, int value is converted to hex, while string value is used as default. 
#define XPAR_{node_label_name}_{<property>.upper()}_<x> {hex(int_value)}

Canonical define:

#define XPAR_X{driver_name}_{index}_{<property>.upper()}_<x> {hex(int_value)}
Any other property (<property> or xlnx,<property>) Property value is of type /bits/ which is a Linux-specific way to show certain properties. Hex value kept at the end of the property value is converted into int with base 16. 
#define XPAR_{node_label_name}_{<property>.upper()}_<x> {hex(int_value)}

Canonical define:

#define XPAR_X{driver_name}_{index}_{<property>.upper()}_<x> {hex(int_value)}
 For example: xlnx,num_slcr_addr: 2.
  • Mainly used for 64-bit addresses and floating values converted to hex.
  • Concatenates multiple 32-bit hex number/addresses into one 64-bit hex number/address.
  • XPARAMETERS: #define XPAR_{label_name}_{<property>.upper()} {combined_address_prop}
Note: Check canonical macros in the xparameters.h file. In the legacy flow, drivers had canonical macros defined in different ways. These macros have now been made uniform across drivers and follows the XPAR_X<driver_name>_<instance_number>_<PROPERTY> syntax. Changes are therefore needed to conform to the new syntax. If you want to have a name that is different from the IP name inside canonical definition, you must define the “xparam_prefix” key with that name. X<driver_name> is replaced with the value of xparam_prefix in the new syntax.