Data Folder in Drivers - 2024.1 English

Porting Guide for embeddedsw Components System Device Tree Based Build Flow (UG1647)

Document ID
UG1647
Release Date
2024-06-21
Version
2024.1 English

A YAML file named <driver_name>.yaml must be added inside the data folder. This YAML file is a replacement of the older AMD proprietary metadata files (*.mdd, *.tcl). For example, the data folder in the CSUDMA driver must contain a file named csudma.yaml.

The adopted YAML specification borrows heavily from open source Linux YAML device tree bindings with some customizations to work with AMD embeddedsw stack. The YAML file contains the following sections:

  • Headers, copyrights, and generic information such as maintainer and type.
    # SPDX-License-Identifier: MIT
    %YAML 1.2
    ---
    title: <Description of the yaml file>
    maintainers:
        - Name(s) of the maintainer(s)
    type: <Describes the type of baremetal module the yaml file describes, e.g, driver>
    
    device_type: <Describes the type of devices that the driver supports>
    # Helps in giving meaningful error when there is a dependency of one kind of IP over a template application, a library or a driver. 
    # Available values are ethernet, serial, interrupt-controller, ipi and timer.
  • Specification(s) that help(s) in selecting the corresponding driver for an IP. The corresponding driver would get picked up into BSP if the IP is present in the system device tree and its compatible property in the device tree node matches with this "compatible" string specified in the driver YAML. It replaces the .mdd file-based approach and instead relies on the Linux-like compatible property. Detailed usage of compatible property can be found in Usage Information for "compatible". Refer to the sample csudma.yaml at the end of this section.
    properties:
      compatible:
         items:
           - const: <Typically the name of the HW IP as seen in xsa file, e.g. xlnx,zynqmp-csudma-1.0>
      reg:
         description: <Physical base address and size of the controller register map>
      other_properties_as_needed:
        description: <Description of the property>
  • Specifications that help in generating the driver configuration file (*_g.c file) and driver config structure alongside the required xparameters.h. More data on the usage of below section can be found in below snippet and in Options Available in the "required" Section and Sample YAML for a Driver.
    config:
        - <The name of the driver config structure, e.g. XCsuDma_Config>
    
    xparam_prefix: xcsu
    # Specifies a custom name different than that of ip-name in canonical macros
    # General canonical macros follow the XPAR_X<driver_name>_<instance_number>_<PROPERTY> syntax
    # X<driver_name> will be replaced with the value of xparam_prefix in the above defined syntax
    
    required:
    # Describes the elements that will show up in the driver config structure
    # As an example, csudma driver *_g.c file will contain the XCsuDma_Config structure with following elements.
        #- compatible
        #- reg
        #- xlnx,dma-type
        #- interrupts
        #- interrupt-parent
     
    # The order mentioned under the "required" section must be same as that the driver config structure.
     
    optional:
    # Entries that are needed in the config structure but not in xparameters.h will be generated using this option.
    # Same keys and rules as that under the required section
     
    additionalProperties:
    # Entries that are needed only in xparameters.h and not in the config structure will be generated using this option.
    # Same keys and rules as that under required section.
    
  • Specifications that describe driver example dependencies with hardware IP properties. Examples can depend on other supporting .h or .c files. Examples can have dependency on hardware IP properties (like interrupts). Few examples can be valid only for few platforms. Refer to the sample csudma.yaml at the end of this section and to the Sample YAML for a Driver section for more information. Examples listed here are also listed in the import example section in the GUI of the AMD Vitis™ Unified Software Platform 2023.2.
    examples:
        <Example name>:
            - <supported_platforms>: <has to be mentioned only when example is applicable to specific platform>
            - <dependency_files>: <List of supported files that need to be pulled while creating the example>
            - <Which HW parameters, it is dependent on. As an example xcsudma_intr_example.c needs interrupts to be enabled through HW.>
  • Specifications that help in defining driver dependencies. A driver can be dependent on other drivers or a library, for example, libmetal.
    depends:
    # Create dict keys with the driver name on which the driver depends
    # Source files of the driver mentioned here will be pulled in libsrc
        <drv_name>: []
     
    depends_libs:
    # Create dict keys with the library name on which the driver depends
        libmetal: {}
  • Specifications that help in generating peripheral tests. The following examples are selected for generating peripheral tests. For more information, see Including a Driver Example in the Peripheral Test Application.
    tapp:
        <Example name>:
            - declaration: <Declaration to be used for the example>
            - hwproperties:
                - <HW property that should be available for the example to be picked as peripheral
    test>
    # For csudma driver example, it would look like:
    tapp: 
        xcsudma_selftest_example.c:
            declaration: XCsuDma_SelfTestExample
        xcsudma_intr_example.c:
            declaration: XCsuDma_IntrExample
            hwproperties:
                - interrupts
  • A sample YAML file for the existing CSUDMA driver looks as shown in the following example. The YAML name is csudma.yaml. More information on how the YAML takes the device tree data and convert them into xparameters and Config structure can be found in Sample YAML for a Driver.
    # SPDX-License-Identifier: MIT
    %YAML 1.2
    ---
    title: Bindings for CSUDMA controller
    maintainers:
        - Maintainer Name <abc.xyz@domain.com>
    type: driver
    properties:
        compatible:
            items:
                - const: xlnx,zynqmp-csudma-1.0
        reg:
            description: Physical base address and size of the controller register map
        xlnx,dma-type:
            description: |
                Differentiates the dma controller that driver supports
                0 - CSUDMA controller
                1 - PMCDMA-0 controller
                2 - PMCDMA-1 controller
        config:
            - XCsuDma_Config
        required:
            - compatible
            - reg
            - xlnx,dma-type
            - interrupts
            - interrupt-parent
    examples:
        xcsudma_intr_example.c:
            - interrupts
    tapp:
        xcsudma_selftest_example.c:
            declaration: XCsuDma_SelfTestExample
        xcsudma_intr_example.c:
            declaration: XCsuDma_IntrExample
            hwproperties:
                - interrupts
    ...