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: # Any information provided in the optional field for these properties meta-data/values will be generated in the <driver name>Config.cmake file, which will be then used by the drivers (e.g., for generating headers, and so on). # 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 ...