Tcl File Format Specification - 2022.2 English

Vitis Unified Software Platform Documentation: Embedded Software Development (UG1400)

Document ID
UG1400
Release Date
2023-01-02
Version
2022.2 English

Each OS and library has a Tcl file associated with the MLD file. This Tcl file has the following sections:

DRC
Contains Tcl routines that validate your OS and library parameters for consistency.
Generation
Contains Tcl routines that generate the configuration header and C files based on the library parameters.

MLD Design Rule Check Section

proc mydrc { handle } { }

The DRC function could be any Tcl code that checks your parameters for correctness. The DRC procedures can access (read-only) the Platform Specification Format database (which the tool builds using the hardware (XSA) and software (MSS) database files) to read the parameter values that you set. The handle is associated with the current library in the database. The DRC procedure can get the OS and library parameters from this handle. It can also get any other parameter from the database by first requesting a handle and 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 return without any value.

MLD Format Examples

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

Example: MLD File for a Library

Following is an example of an MLD file for the xilmfs library.

option psf_version = 2.1.0 ;

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.

The psf_version of the MLD file is defined to be 2.1 in this example. This is the only option that can occur before a BEGIN LIBRARY construct now.

BEGIN LIBRARY xilmfs

The BEGIN LIBRARY construct defines the start of a library named xilmfs.

option DESC = "Xilinx Memory File System" ;
option drc = mfs_drc ;
option copyfiles = all;
option REQUIRES_OS = (standalone xilkernel freertos_zynq);
option VERSION = 2.0;
option NAME = xilmfs;

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 the library. The DRC option specifies the name of the Tcl procedure that the tool invokes while processing this library. The mfs_drc is the Tcl procedure in the xilmfs.tcl file that would be invoked while processing the xilmfs library.

PARAM name = numbytes, desc = "Number of Bytes", type = int, default =
100000, drc = drc_numbytes ;
PARAM name = base_address, desc = "Base Address", type = int, default =
0x10000, drc = drc_base_address ;
PARAM name = init_type, desc = "Init Type", type = enum, values = ("New
file system"=MFSINIT_NEW,
"MFS Image"=MFSINIT_IMAGE, "ROM Image"=MFSINIT_ROM_IMAGE), default =
MFSINIT_NEW ;
PARAM name = need_utils, desc = "Need additional Utilities?", type =
bool, default = false ;

PARAM defines a library parameter that can be configured. Each PARAM has the following properties associated with it, whose meanings are self-explanatory: NAME, DESC, TYPE, DEFAULT, RANGE, and DRC. The property VALUES defines the list of possible values associated with an ENUM type.

BEGIN INTERFACE file
PROPERTY HEADER="xilmfs.h" ;
FUNCTION NAME=open, VALUE=mfs_file_open ;
FUNCTION NAME=close, VALUE=mfs_file_close ;
FUNCTION NAME=read, VALUE=mfs_file_read ;
FUNCTION NAME=write, VALUE=mfs_file_write ;
FUNCTION NAME=lseek, VALUE=mfs_file_lseek ;
END INTERFACE

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

PROPERTY defines the properties associated with the construct defined in the BEGIN construct. Here HEADER is a property with value xilmfs.h, defined by the file interface. FUNCTION defines a function supported by the interface.

The open, close, read, write, and lseek functions of the file interface have the values mfs_file_open, mfs_file_close, mfs_file_read, mfs_file_write, and mfs_file_lseek. These functions are defined in the header file xilmfs.h.

BEGIN INTERFACE filesystem

BEGIN INTERFACE defines an interface the library supports. Here, file is the name of the interface.

PROPERTY HEADER="xilmfs.h" ;
FUNCTION NAME=cd, VALUE=mfs_change_dir ;
FUNCTION NAME=opendir, VALUE=mfs_dir_open ;
FUNCTION NAME=closedir, VALUE=mfs_dir_close ;
FUNCTION NAME=readdir, VALUE=mfs_dir_read ;
FUNCTION NAME=deletedir, VALUE=mfs_delete_dir ;
FUNCTION NAME=pwd, VALUE=mfs_get_current_dir_name ;
FUNCTION NAME=rename, VALUE=mfs_rename_file ;
FUNCTION NAME=exists, VALUE=mfs_exists_file ;
FUNCTION NAME=delete, VALUE=mfs_delete_file ;
END INTERFACE
END LIBRARY

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

Example: Tcl File of a Library

The following is the xilmfs.tcl file corresponding the xilmfs.mld file described in the previous section. The mfs_drc procedure would be invoked for the xilmfs library while running DRCs for libraries. The generate routine generates constants in a header file and a c file for the xilmfs library based on the library definition segment in the MSS file.

proc mfs_drc {lib_handle} {
puts "MFS DRC ..."
}
proc mfs_open_include_file {file_name} {
set filename [file join "../../include/" $file_name]
if {[file exists $filename]} {
set config_inc [open $filename a]
} else {
set config_inc [open $filename a]
::hsi::utils::write_c_header $config_inc "MFS Parameters"
}
return $config_inc
}
proc generate {lib_handle} {
puts "MFS generate ..."
file copy "src/xilmfs.h" "../../include/xilmfs.h"
set conffile [mfs_open_include_file "mfs_config.h"]
puts $conffile "#ifndef _MFS_CONFIG_H"
puts $conffile "#define _MFS_CONFIG_H"
set need_utils [common::get_property CONFIG.need_utils $lib_handle]
if {$need_utils} {
# tell libgen or xps that the hardware platform needs to provide
stdio functions
# inbyte and outbyte to support utils
puts $conffile "#include <stdio.h>"
}
puts $conffile "#include <xilmfs.h>"
set value [common::get_property CONFIG.numbytes $lib_handle]
puts $conffile "#define MFS_NUMBYTES $value"
set value [common::get_property CONFIG.base_address $lib_handle]
puts $conffile "#define MFS_BASE_ADDRESS $value"
set value [common::get_property CONFIG.init_type $lib_handle]
puts $conffile "#define MFS_INIT_TYPE $value"
puts $conffile "#endif"
close $conffile
}
Example: MLD File for an OS

An example of an MLD file for the standalone OS is given below:

option psf_version = 2.1.0 ;

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 MLD file is defined to be 2.1. This is the only option that can occur before a BEGIN OS construct at this time.

BEGIN OS standalone

The BEGIN OS construct defines the start of an OS named standalone.

option DESC = "Generate standalone BSP";
option COPYFILES = all;

The DESC option gives a description of the MLD. The COPYFILES option indicates the files to be copied for the OS.

PARAM NAME = stdin, DESC = "stdin peripheral ", TYPE =
peripheral_instance, REQUIRES_INTERFACE = stdin, DEFAULT = none; PARAM
NAME = stdout, DESC = "stdout peripheral ", TYPE = peripheral_instance,
REQUIRES_INTERFACE = stdout, DEFAULT = none ; PARAM NAME = need_xilmalloc,
DESC = "Need xil_malloc?", TYPE = bool, DEFAULT = false ;

PARAM defines an OS parameter that can be configured. Each PARAM has the following, associated properties: NAME, DESC, TYPE, DEFAULT, RANGE, DRC. The property VALUES defines the list of possible values associated with an ENUM type.

END OS

END is used with the construct name that was used in the BEGIN statement. Here END is used with OS to indicate the end of OS construct.

Example: Tcl File of an OS

The following is the standalone.tcl file corresponding to the standalone.mld file described in the previous section. The generate routine generates constants in a header file and a c file for the xilmfs library based on the library definition segment in the MSS file.

proc generate {os_handle} {
	global env
	set need_config_file "false"
	# Copy over the right set of files as src based on processor type
	set sw_proc_handle [get_sw_processor]
	set hw_proc_handle [get_cells [get_property HW_INSTANCE
$sw_proc_handle] ]
	set proctype [get_property IP_NAME $hw_proc_handle]
	set procname [get_property NAME $hw_proc_handle]
	set enable_sw_profile [get_property
CONFIG.enable_sw_intrusive_profiling $os_handle]
	set mb_exceptions false
	switch $proctype {
		"microblaze" {
		foreach entry [glob -nocomplain [file join $mbsrcdir *]] {
# Copy over only files that are not related to exception
handling.
# All such files have exception in their names.
file copy -force $entry "./src/"
}
	set need_config_file "true"
	set mb_exceptions [mb_has_exceptions $hw_proc_handle]
}
	"ps7_cortexa9" {
	set procdrv [get_sw_processor]
	set compiler [get_property CONFIG.compiler $procdrv]
	if {[string compare -nocase $compiler "armcc"] == 0} {
	set ccdir "./src/cortexa9/armcc"
	} else {
	set ccdir "./src/cortexa9/gcc"
	}
	foreach entry [glob -nocomplain [file join
	$cortexa9srcdir *]] {
	file copy -force $entry "./src/"
	}
	foreach entry [glob -nocomplain [file join $ccdir *]] {
	file copy -force $entry "./src/"
	}
	file delete -force "./src/armcc"
	file delete -force "./src/gcc"
	if {[string compare -nocase $compiler "armcc"] == 0} {
	file delete -force "./src/profile"
	set enable_sw_profile "false"
	}
	set file_handle [xopen_include_file "xparameters.h"]
	puts $file_handle "#include \"xparameters_ps.h\""
	puts $file_handle ""
	close $file_handle
	}
	"default" {puts "unknown processor type $proctype\n"}
}