Sample YAML for a Driver - 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

Following are some sample YAMLs for drivers:

  • A comprehensive sample YAML file for drivers. Note that data points are only for syntax-related understanding and are not related to any IP.
    # SPDX-License-Identifier: MIT
    %YAML 1.2
    ---
    title: Bindings for IPI controller available in the zynqMP and Versal platform
     
    maintainers:
        - ASDF GHJKL <asdf.ghjkl@domain.com>
        - ZXCV VBNM <zxcv.vbnm@domain.com>
     
    type: driver
    
    device_type: ipi
     
    properties:
        compatible:
            items:
                OneOf:
                    - items:
                        - enum:
                            - xlnx,zynqmp-ipi-mailbox
                            - xlnx,psu-ipi-1.0
        reg:
            description: Standard reg property
        ipi-bitmask:
            description: foo0 bar0 abc0 xyz0
        interrupts:
            description: foo1 bar1 abc1 xyz1
        interrupt-parent:
            description: foo2 bar2 abc2 xyz2
        num_slcr_addr:
            description: foo3 bar3 abc3 xyz3
        axistream-connected:
            description: foo4 bar4 abc4 xyz4
        child-required:
            description: foo5 bar5 abc5 xyz5
        ipi-id:
            description: foo6 bar6 abc6 xyz6
        max-intr-size:
            description: foo7 bar7 abc7 xyz7
     
    config:
        - XIpiPsu_Config
     
    required:
        - compatible
        - reg
        - xlnx,ipi-bitmask
        - interrupts
        - interrupt-parent
        - xlnx,num_slcr_addr: 2
        - axistream-connected: phandle
        - child,required:
            - xlnx,ipi-bitmask
            - xlnx,ipi-buf-index
     
    optional:
        - xlnx,ipi-id
     
    additionalProperties:
        - xlnx,max-intr-size
     
    depends:
        clockps: []
        resetps: []
     
    depends_libs:
        libmetal: {}
     
    examples:
        xdrv1_selftest_example.c::
            - reg
        xdrv1_polltimeout_interrupt_example.c:
            - dependency_files:
                - xdrv1_flash_config.h
            - interrupts
            - compatible : xlnx,versal-wwdt-1.0
        xdrv1_generic_interrupt_example.c:
            - interrupts 
  • A sample device tree data for an example IP:
    ipi3: mailbox@ff330000 {
        status = "okay";
        compatible = "xlnx,zynqmp-ipi-mailbox";
        interrupt-parent = <&gic_a72>;
        interrupts = <0x0 0x1e 0x4>;
        reg = <0x0 0xff330000 0x0 0x20>;
        xlnx,ipi-bitmask = <0x4>;
        xlnx,ipi-id = <0x2>;
        xlnx,ipi-buf-index = <0x2>;
        xlnx,ip-name = "psv_ipi";
        xlnx,num_slcr_addr = <0x00000006 0x00000000>;
        xlnx,max-intr-size = <0x20>;
        xlnx,name = "CIPS_0_pspmc_0_psv_ipi_0";
        axistream-connected = <&axi_dma_0>;
        phandle = <0x6d>;
     
        ipi0_0: child@0 {
                xlnx,ipi-bitmask = <0x4>;
                xlnx,ipi-rsp-msg-buf = <0xff3f04a0>;
                xlnx,ipi-id = <0x2>;
                xlnx,ipi-buf-index = <0x2>;
                xlnx,ipi-req-msg-buf = <0xff3f0480>;
                phandle = <0xe1>;
        };
     
        ipi0_1: child@1 {
                xlnx,ipi-bitmask = <0x8>;
                xlnx,ipi-rsp-msg-buf = <0xff3f04e0>;
                xlnx,ipi-id = <0x3>;
                xlnx,ipi-buf-index = <0x3>;
                xlnx,ipi-req-msg-buf = <0xff3f04c0>;
        };
    }
     
    axi_dma_0: axi_dma@a4050000 {
        xlnx,num-s2mm-channels = <1>;
        xlnx,ip-name = "axi_dma";
        reg = <0x0 0xa4050000 0x0 0x10000>;
        xlnx,s2mm-burst-size = <16>;
    };
  • Generated Config structure file for the IPIPSU driver:
    #include "xipipsu.h"
     
    XIpiPsu_Config XIpiPsu_ConfigTable[] __attribute__ ((section (".drvcfg_sec"))) = {
        {
            "xlnx,zynqmp-ipi-mailbox", /* compatible */
            0xff330000, /* reg */
            0x4, /* xlnx,ipi-bitmask */
            0x401e, /* interrupts */
            0xf9000000, /* interrupt-parent */
            0x600000000, /* xlnx,num_slcr_addr */
            0xa4050002, /* axistream-connected */
            {
                {
                    4, /* xlnx,ipi-bitmask */
                    2 /* xlnx,ipi-buf-index */
                },
                {
                    8, /* xlnx,ipi-bitmask */
                    3 /* xlnx,ipi-buf-index */
                }
            },
            0x2 /* xlnx,ipi-id */
        },
        {
             NULL
        }
    };
  • Generated xparameters.h for the IPIPSU driver:
    /* Definitions for peripheral IPI3 */
    #define XPAR_IPI3_COMPATIBLE xlnx,zynqmp-ipi-mailbox
    #define XPAR_IPI3_BASEADDR 0xff330000
    #define XPAR_IPI3_HIGHADDR 0xff33001f
    #define XPAR_IPI3_IPI_BITMASK 0x4
    #define XPAR_IPI3_INTERRUPTS 0x401e
    #define XPAR_IPI3_INTERRUPT_PARENT 0xf9000000
    #define XPAR_IPI3_IPI_NUM_SLCR_ADDR 0x600000000
    #define XPAR_IPI3_0_AXISTREAM-CONNECTED 0xa4050002
    #define XPAR_IPI3_0_IPI_BITMASK 0x4
    #define XPAR_IPI3_0_IPI_BUF_INDEX 0x2
    #define XPAR_IPI3_1_IPI_BITMASK 0x8
    #define XPAR_IPI3_1_IPI_BUF_INDEX 0x3
    #define XPAR_IPI3_MAX_INTR_SIZE 0x20
     
    /* Canonical definitions for peripheral IPI3 */
    #define XPAR_XIPIPSU_3_BASEADDR 0xff330000
    #define XPAR_XIPIPSU_3_HIGHADDR 0xff33001f
    #define XPAR_XIPIPSU_3_COMPATIBLE xlnx,zynqmp-ipi-mailbox
    #define XPAR_XIPIPSU_3_IPI_BITMASK 0x4
    #define XPAR_XIPIPSU_3_INTERRUPTS 0x401e
    #define XPAR_XIPIPSU_3_INTERRUPT_PARENT 0xf9000000
    #define XPAR_XIPIPSU_3_IPI_NUM_SLCR_ADDR 0x600000000
    #define XPAR_XIPIPSU_3_AXISTREAM-CONNECTED 0xa4050002
    #define XPAR_XIPIPSU_3_MAX_INTR_SIZE 0x20
    Note: Canonical entries follow the XPAR_X<driver_name>_<instance_number>_<PROPERTY> syntax.