Microprocessor Driver Definition (MDD)

Microprocessor Driver Definition Overview

A Microprocessor Driver Definition (MDD) file contains directives for customizing software drivers. This document describes the MDD format and the parameters that can be used to customize drivers.

Requirements

Each device driver has an MDD file and a Tool Command Language (Tcl) file associated with it. The MDD file is used by the Tcl file to customize the driver, depending on different options configured in the MSS file. For more information on the MSS file format, see Microprocessor Software Specification (MSS).

The driver source files and the MDD file for each driver must be located at specific directories in order to find the files and the drivers. This document describes the MDD format and the parameters that can be used to customize drivers.

MDD Driver Definition Files

Driver Definition involves defining a Data Definition file (MDD) and a Data Generation file (Tcl file).

Data Definition File

The MDD file (<driver_name>.mdd) contains the configurable parameters. A detailed description of the parameters and the MDD format is described in MDD Parameter Description.

Data Generation File
The second file (<driver_name>.tcl), with the filename being the same as the MDD filename) uses the parameters configured in the MSS file for the driver to generate data. Data generated includes but is not limited to generation of header files, C files, running DRCs for the driver, and generating executables. The Tcl file includes procedures that are called by the tool at various stages of its execution.

Various procedures in a Tcl file includes: the DRC (name of the DRC given in the MDD file), generate (tool defined procedure) called after driver files are copied, post_generate (tool defined procedure) called after generate has been called on all drivers and libraries, and execs_generate called after the libraries and drivers have been generated.

Note: A driver does not require the data generation file (Tcl file).

MDD Format Specification

The MDD format specification involves the MDD file Format specification and the Tcl file Format specification which are described in the following subsections.

MDD File Format Specification

The MDD file format specification describes the parameters defined in the Parameter Description section. This data section describes configurable parameters in a driver. The format used to describe these parameters is discussed in MDD Parameter Description.

Tcl File Format Specification

Each driver has a Tcl file associated with the MDD file. This Tcl file has the following sections:
DRC Section
This section contains Tcl routines that validate your driver parameters for consistency.
Generation Section
This section contains Tcl routines that generate the configuration header and C files based on the driver parameters.

MDD Format Examples

This section explains the MDD format through an example of an MDD file and its corresponding Tcl file.

Example: MDD File

The following is an example of an MDD file for the uartlite driver.

option psf_version = 2.1;

option is a keyword identified by the tool. The option name following the option keyword is a directive to the tool to do a specific action. Here the psf_version of the MDD file is defined as 2.1. This is the only option that can occur before a BEGIN DRIVER construct.

BEGIN DRIVER uartlite

The BEGIN DRIVER construct defines the start of a driver named uartlite.

option supported_peripherals = (mdm axi_uartlite);
option driver_state = ACTIVE;
option copyfiles = all;
option VERSION = 3.0;
option NAME = uartlite;

The NAME option indicates the name of the driver. The VERSION option indicates the version of the driver. The COPYFILES option indicates the files to be copied for a “level” 0 uartlite driver.

BEGIN INTERFACE stdin

BEGIN INTERFACE defines an interface the driver supports. The interface name is stdin.

PROPERTY header = xuartlite_l.h;
FUNCTION name = inbyte, value = XUartLite_RecvByte;
END INTERFACE

An Interface contains a list of standard functions. A driver defining an interface should have values for the list of standard functions. It must also specify a header file in which all the function prototypes are defined.

PROPERTY defines the properties associated with the construct defined in the BEGIN construct. The header is a property with the value xuartlite_l.h, defined by the stdin interface. FUNCTION defines a function supported by the interface. The inbyte function of the stdin interface has the value XUartLite_RecvByte. This function is defined in the header file xuartlite_l.h.

BEGIN INTERFACE stdout
PROPERTY header = xuartlite_l.h;
FUNCTION name = outbyte, value = XUartLite_SendByte;
END INTERFACE
BEGIN INTERFACE stdio
PROPERTY header = xuartlite_l.h;
FUNCTION name = inbyte, value = XUartLite_RecvByte;
FUNCTION name = outbyte, value = XUartLite_SendByte;
END INTERFACE

END is used with the construct name that was used in the BEGIN statement. Here END is used with BLOCK and DRIVER constructs to indicate the end of each BLOCK and DRIVER construct.

Example: Tcl File

The following is the uartlite.tcl file corresponding to the uartlite.mdd file described in the previous section. The “uartlite_drc” procedure would be invoked for the uartlite driver while running DRCs for drivers. The generate routine generates constants in a header file and a c file for uartlite driver, based on the driver definition segment in the MSS file.

proc generate {drv_handle} {
::hsi::utils::define_include_file $drv_handle "xparameters.h"
"XUartLite" "NUM_INSTANCES" "C_BASEADDR"
"C_HIGHADDR" "DEVICE_ID" "C_BAUDRATE" "C_USE_PARITY" "C_ODD_PARITY"
"C_DATA_BITS"
::hsi::utils::define_config_file $drv_handle "xuartlite_g.c"
"XUartLite" "DEVICE_ID" "C_BASEADDR"
"C_BAUDRATE" "C_USE_PARITY" "C_ODD_PARITY" "C_DATA_BITS"
::hsi::utils::define_canonical_xpars $drv_handle "xparameters.h"
"UartLite" "DEVICE_ID" "C_BASEADDR"
"C_HIGHADDR" "C_BAUDRATE" "C_USE_PARITY" "C_ODD_PARITY" "C_DATA_BITS"
}

MDD Parameter Description

This section gives a detailed description of the constructs used in the MDD file.

Conventions

[ ]: Denotes optional values.

< >: Value substituted by the MDD writer.

Comments

Comments can be specified anywhere in the file. A pound (#) character denotes the beginning of a comment, and all characters after it, right up to the end of the line, are ignored. All white spaces are also ignored and semicolons with carriage returns act as sentence delimiters.

Driver Definition

The driver section includes the driver name, options, dependencies, and other global parameters, using the following syntax:

option psf_version = <
psf version number>
BEGIN DRIVER <driver name>
[option drc = <global drc name>]
[option depends = <list of directories>]
[option help = <help file>]
[option requires_interface = <list of interface names>
]
PARAM <parameter description>
[BEGIN BLOCK,dep = <condition>
.......
END BLOCK]
[BEGIN INTERFACE <interface name>
.......
END INTERFACE]
END DRIVER

MDD Keywords

The keywords that are used in an MDD file are as follows:

Begin

The BEGIN keyword begins with one of the following: library, drive, block, category, or interface.

END

The END keyword signifies the end of a definition block.

PSF_VERSION

Specifies the PSF version of the library.

DRC

Specifies the DRC function name. This is the global DRC function that is called by the GUI configuration tool or the command line tool. This DRC function is called when you enter all the parameters and the MLD or MDD writers can verify that a valid library or driver can be generated with the given parameters.

option

Specifies the name following the keyword option is an option to the tool. The following five

options are supported: COPYFILES, DEPENDS, SUPPORTED_PERIPHERALS, and

DRIVER_STATE.

SUPPORTED_OS_TYPES

Specifies the list of supported OS types. If it is not specified, then driver is assumed as standalone driver.

COPYFILES

Specifies the list of files to be copied for the driver. If ALL is specified as the value, the tool copies all the driver files.

DEPENDS

Specifies the list of directories on which a driver depends for compilation.

SUPPORTED_PERIPHERALS

Specifies the list of peripherals supported by the driver. The values of this option can be specified as a list or as a regular expression. The following example indicates that the driver supports all versions of opb_jtag_uart and the opb_uartlte_v1_00_b version:

option supported_peripherals = (xps_uartlite_v1_0, xps_uart16550)

Regular expressions can be used in specifying the peripherals and versions. The regular expression (RE) is constructed as described below.

Single-Character REs

  • Any character that is not a special character (to be defined) matches itself.
  • A backslash (followed by any special character) matches the literal character itself. That is, it escapes the special character.
  • The special characters are: + * ? . [ ] ^ $
  • The period matches any character except the newline. For example, .umpty matches both Humpty and Dumpty.
  • A set of characters enclosed in brackets ([]) is a one-character RE that matches any of the characters in that set. For example, [akm]matches an a, k, or m. A range of characters can be indicated with a dash. For example, [a-z] matches any lower-case letter.
However, if the first character of the set is the caret (^), then the RE matches any character except those in the set. It does not match the empty string. For example, [^akm] matches any character except a, k, or m. The caret loses its special meaning if it is not the first character of the set.

Multi-Character REs

  • A single-character RE followed by an asterisk (*) matches zero or more occurrences of the RE. Therefore, [a-z]* matches zero or more lower-case characters.
  • A single-character RE followed by a plus (+) matches one or more occurrences of the RE. Therefore, [a-z]+ matches one or more lower-case characters.
  • A question mark (?) is an optional element. The preceding RE can occur no times or one time in the string. For example, xy?z matches either xyz or xz.
  • The concatenation of REs is an RE that matches the corresponding concatenation of strings. For example, [A-Z][a-z]* matches any capitalized word.

The following example matches any version of xps_uartlite, xps_uart16550, and mdm.

option supported_peripherals = (xps_uartlite_v[0-9]+_[1-9][0-9]_[a-z]
xps_uart16550 mdm);

DRIVER_STATE

Specifies the state of the driver. The following are the list of values that can be assigned to DRIVER_STATE:

ACTIVE
This is an active driver. By default the value of DRIVER_STATE is ACTIVE.
DEPRECATED
This driver is deprecated and is scheduled to be removed.
OBSOLETE
This driver is obsolete and is not recognized by any tools. Tools error out on an obsolete driver, and a new driver should be used instead.

REQUIRES_INTERFACE

Specifies the interfaces that must be provided by other libraries or drivers in the system.

HELP

Specifies the help file that describes the library or driver.

DEP

Specifies the condition that needs to be satisfied before processing an entity. For example, to enter into a BLOCK, the DEP condition should be satisfied. Conditions of the form ( operand1 OP operand2) are supported.

BLOCK

Specifies the block is to be entered into when the DEP condition is satisfied. Nested blocks are not supported.

INTERFACE

Specifies the interfaces implemented by this library or driver and describes the interface functions and header files used by the library or driver.

BEGIN INTERFACE <interface name>
option DEP=<list of dependencies>;
PROPERTY HEADER=<name of header file where the function is declared>
;
FUNCTION NAME=<name of interface function>, VALUE=<function name
of library/driver implementation> ;
END INTERFACE

HEADER

Specifies the header file in which the interface functions would be defined.

FUNCTION

Specifies the function implemented by the interface. This is a name-value pair where name is the interface function name and value is the name of the function implemented by the library or driver.

PARAM

Generally, the MLD/MDD file has a name = value format for statements. The PARAM keyword is required before every such NAME, VALUE pair. The format for assigning a value to a parameter is param name = <name>, default= value. The PARAM keyword specifies that the parameter can be overwritten in the MSS file.

DTGPARAM

The DTGPARAM keyword is specially used for the device-tree specific parameters that can be configured. Driver defines these DTGPARAMs if it needs to dump any parameters in the Tool DTG generated DTS file.

PROPERTY

Specifies the various properties of the entity defined with a BEGIN statement.

NAME

Specifies the name of the entity in which it was defined (example: PARAM, PROPERTY ). It also specifies the name of the driver if it is specified with option.

VERSION

Specifies the version of the driver.

DESC

Describes the entity in which it was defined (example: PARAM, PROPERTY ).

TYPE

Specifies the type for the entity in which it was defined (example: PARAM ). The following are the supported types:

  • bool: Boolean (true or false)

    int: Integer

    string: String value within “ " (quotes).

    enum: List of possible values, that this parameter can take.

    library: Specify other library that is needed for building the library or driver.

    peripheral_instance: Specify other hardware drivers needed for building the library or driver. Regular expressions can be used to specify the peripheral instance. Refer to SUPPORTED_PERIPHERALS in MLD Keywords for more details about regular expressions.

DEFAULT

Specifies the default value for the entity in which it was defined.

GUI_PERMIT

Specifies the permissions for modification of values. The following permissions exist:

NONE

The value can not be modified at all.

ADVANCED_USER
The value can be modified by all. The Vitis IDE does not display this value by default. It is displayed only as an advanced option in the GUI.
ALL_USERS
The value can be modified by all. The Vitis IDE displays this value by default. This is the default value for all the values. If GUI_PERMIT = NONE, the category is always active.

MDD Design Rule Check (DRC) Section

proc mydrc { handle }

The DRC function can be any Tcl code that checks your parameters for correctness. The DRC procedures can access (read-only) the Platform Specification Format database (built by the tool using the hardware (XSA) and software (MSS) database files) to read the parameter values you set. The "handle" is a handle to the current driver in the database. The DRC procedure can get the driver parameters from this handle. It can also get any other parameter from the database by first requesting a handle and then using the handle to get the parameters.

  • For errors, DRC procedures call the Tcl error command error "error msg" that displays in an error page.
  • For warnings, DRC procedures return a string value that can be printed on the console.
  • On success, DRC procedures just return without any value.

MDD Driver Generation (Generate) Section

proc mygenerate { handle }

generate could be any Tcl code that reads your parameters and generates configuration files for the driver. The configuration files can be C files, Header files, or Makefiles. The generate procedures can access (read-only) the Platform Specification Format database (built by the tool using the MSS files) to read the parameter values of the driver that you set. The handle is a handle to the current driver in the database. The generate procedure can get the driver parameters from this handle. It can also get any other parameters from the database by requesting a handle and then using the handle to get the parameter.

Custom Driver

This section demonstrates how to hand-off a custom driver associated with an IP(driver files are specified in IPXACT file of the IP component) and access the driver information in HSI as well as associate the driver with IP during BSP generation. For more information on packaging IP with custom driver, refer to Vivado Design Suite User Guide: Creating and Packaging Custom IP (UG1118).

An example design of an IP with custom driver specified in its IPXACT definition.

Figure 1: Example Design with an IP with custom driver
Figure 2: Custom driver specified in IPXACT specification of an IP

Custom driver specified in IPXACT specification of an IP

Run Vivado hardware hand-off flow either in Pre-Synth or Post-Bitstream mode. The custom driver for each IP is packaged in an XSA.

# Open the hardware design with custom drivers.
hsi::open_hw_design ./base_zynq_design_wrapper.xsa
				base_zynq_design_wrapper
# Create a software design
hsi::create_sw_design swdesign -proc ps7_cortexa9_0 -os standalone
				Swdesign
# Check if the custom drivers are assigned to respective IP cores or not
join [hsi::get_drivers ] \n
					axi_bram_ctrl_0
					axi_gpio_0
					myip_0
# Check the custom driver properties
common::report_property [ hsi::get_drivers myip*]
Property Type Read-only Visible Value
CLASS string true true driver
HW_INSTANCE string true true myip_0
NAME string false true myip
VERSION string false true 1.0
# Generate BSP. BSP source code including custom driver sources will be dumped to the bsp_out #directory 
hsi::generate_bsp -dir bsp_out
					base_zynq_design_wrapper
					ls ./bsp_out/ps7_cortexa9_0/libsrc/
					. . .
					myip_v1_0
					. . .