Revision as of 15:48, 23 September 2011



XML specifications

Introduction

XML files are used to describe the project, the platform and the components. The following chapter present the content of each file type.

Before describing the XML file formats in details, some coding rules have to be considered:

• a file must start with a standard xml header containing the character encoding and the xml version:

<?xml version="1.0" encoding="utf-8"?>

• all tags and attributes are in lowercase.
• each file has one element: the base node, which identifies the file content. This base node can be one of these types:
  • component: for a component (Virtual Peripheral).
  • platform: for a platform.
  • project: for a project.
  • bus : for a bus (wishbone8, wishbone16, plb, ...)
  • toolchain: for a compilation/simulation/synthesis toolchain.
• A subnode "description" is used to describe the element.

A short example of a xml "component" file:

<?xml version="1.0" encoding="utf-8"?>
<component name="button" instance_name="mybutton" num="0" version="1.0">
  <description>
      A simple button, rise an irq when pressed or released.
  </description>
...
</component>

Component file format

figure 1 - XML component ER-diagram

Several files are required to use a component:

• A xml file describing the component
• one or several HDL files (VHDL or Verilog)
• one or several Drivers files (C, H, makefile)

The XML file is detailed below and is based on the following structure:

• component
  • driver_files
  • interrupts
  • hdl_files
  • interfaces

component node

The component node has several mandatory attributes:

• name: component name. The component name must be the same of the top entity name of HDL file.
• instance_name: instance name. When a component is instantiated in a project, an unique name has to be given. This name can be specified by the user or automatically generated by POD using the default component name and by adding a number
• num: used internaly by POD to differentiate several instances of the same component.
• version: component version.

<component  name="button" instance_name="mybutton" num="0" version="1.0">
...

driver_files node

The driver_files node contains the OS-driver files for this component. In the driver_templates node, the architecture attribute indicates the supported operating system.

• filename : name of the file(s) required for the compilation of the driver
• support: indicates which versions of the operating system are supported

<?xml version="1.0" encoding="utf-8"?>
<component name="button" instance_name="mybutton" num="0" version="1.0">
 <driver_files>
  <driver_templates architecture="linux">
   <file name="button.h" />
   <file name="button.c" />
   <file name="Makefile" />
   <file name="Konfig" />
   <support version="2.6.23" />
   <support version="2.6.24" />
  </driver_templates>
 </driver_files>
</component>

interrupts node

Some components may have one or several interrupt pins. This node is used to describe the name of the interrupt pins.

<?xml version="1.0" encoding="utf-8"?>
<component name="button" instance_name="mybutton" num="0" version="1.0">
[...]
 <interrupts>
  <interrupt interface="interrupt_button" port="irq" />
  <interrupt ... />
 </interrupts>
[...]
</component>

Each interrupt port has a size of 1 pin. This information is required for driver generator, with this, POD can know which irq number is used for this component.

hdl_files node

The hdl_files node contains the HDL file list (VHDL, Verilog,...) used in the synthesis of the component. Each hdl_file element has the following attributes:

• scope: describes the FPGA type supported and can be of type:
  • all: all fpga (default value).
  • xilinx: only for xilinx.
  • altera: only for altera.
  • tb: can't be synthesis, only for benchmarking.
• istop: a "1" indicates a top file otherwise "0" for standard HDL files.

<?xml version="1.0" encoding="utf-8"?>
<component name="button" instance_name="mybutton" num="0" version="1.0">
 <hdl_files>
  <hdl_file filename="hdl/button.vhd" scope="all" istop="1" />
 </hdl_files>
</component>

interfaces node

The interfaces node defines the component interfaces with the following attributes:

• name: interface name.
• bus : in case of a bus, this attribute gives the name of the bus (wishbone16, wishobne8, plb, etc...)
• class: describes the class of the interface, can be of type:
  • MASTER: for master bus.
  • SLAVE: for slave bus.
  • GLS: if the interface is not one of the above types then it is GLS (global)
• clockandreset: When interface is a bus, it must be synchronized with a clock and a reset. In some cases, a component can use several clock/reset (CLK_RST) domains. The clockandreset bus attribute indicates which clock/reset interface is used for this interface.

In case of a master bus or a clock/reset generator, a list containing the slave interfaces is built by POD. Each element of the list has two attributes:

• instancename: instance name containing the slave interface.
• interfacename: name of the slave interface.

<?xml version="1.0" encoding="utf-8"?>
<component name="button" instance_name="mybutton" num="0" version="1.0">
 <interfaces>
  <interface name="IO" class="GLS" >
    [...]
  </interface>

  <interface name="CANDR" class="CLK_RST" >
    [...]
  </interface>

  <interface name="mwb16" bus="wishbone16" class="MASTER" clockandreset="CANDR" >
   <slaves>
     <slave instancename="myled" dest_interface="swb16" >
   </slaves>
    [...]
  </interface>

 </interfaces>
</component>

ports node

The ports node contains the ports definitions for a given interface. Each port is described with one port node with the following attributes:

• name : port name.
• size : port size (number of pins).
• variable_size : boolean attribute ('0' or '1'), indicates whether the port size is variable or not.
• dir : port direction (in, out, inout).
• unconnected_value : if an in or inout pin is left unconnected, use this default value. If this attribute is not present, default value is '0'.
• type : for a recognized bus (bus description file), each port has a type describing its functionality (ADR, DAT_O, etc...).
• position: gives the position port in the fpga (platform specific).
• freq : gives the frequency of the clock connected to the fpga (platform specific).

During the connection process of one port to an other port, the port node is "opened" and a "pin" node is added with following attributes:

• num: port pin number.

To describe the destination connection(s), a connect element is added by POD with following attributes:

• instance_dest : instance destination name.
• interface_dest : interface destination name.
• port_dest: port destination name.
• pin_dest: pin destination name.

If the connect element is present in the component before the instantiation (in library component), POD will try to connect automatically this pin when component is added in project.

...
<interface name="candr">
  <ports>
    <port name="wbc_candr_reset" type="rst" size="1" dir="in" >
        <pin num="0">
            <connect ... />
        </pin>
     </port>
    <port name="wbc_candr_clk" type="clk" size="1" dir="in" />
  </ports>
</interface>

<interface name = "LCD">
<ports>
  <port name="gls_lcd_export" type="EXPORT" dir="out" size="8">
     <pin num="0">
        <connect instance_dest="platform" interface_dest="fpga" port_dest="FPGA8" pin_num="0" />
     </pin>
     <pin num="7">
         <connect instance_dest="platform" interface_dest="bank0" port_dest="FPGA12" pin_num="0" />
         <connect instance_dest="led02" interface_dest="led_in" port_dest="pled" pin_dest="0" />
     </pin>
  </port>
</ports>
</interface>
...

registers node

The registers node is specific to the slave-bus interfaces. It indicates the registers which can be used by the driver.

• base : base address of the slave interface registers.

For each register, a register element is added with the following attributes:

• name : register name.
• offset : register address relative to the base address
• size : size of the register (8, 16 or 32bits).
• rows : if an array or a RAM is described, rows indicates the number of rows.

<?xml version="1.0" encoding="utf-8"?>
<component name="button" instance_name="mybutton" num="0" version="1.0">
 <interfaces>
  <interface name="WB_IRQ_MNGR" class="WBS" bus="wishbone">
   <registers base="0x0020">
    <register name="reg_button" offset="0x00" size="16" rows="1" />
   </registers>
  </interface>
 </interfaces>
</component>

generics node

In VHDL language, a component can be specialized with generic parameters. These parameters can be listed in the XML files. Depending on the value of the public attribute, these generics can be modified by the user or not.

• name : generic name
• public : indicates whether the generic can be manually configured by the user or not.
• destination : indicates if the generic is used in the fpga or in the driver or both (fpga, driver, both).
• op : POD can automatically compute a generic based on the rules described in the operator field. Operators are:
  • realsizeof : real size of port indicated in target.
• target : parameter used by op.
• match: defines a regular expression used to check the generic value entered by the user. Python style is used for the regular expression : RE.
• value : generic default value.

<generics>
    <generic name="brightness" op="sizeof" target="interfacename.portname" public=true value="middle" match="[low|middle|strong]" type="std_logic" destination="both" />
</generics>

Platform file format

The platform file describes the environment of the project ie the FPGA type, the targeted electronics board and the auto-loaded components specific to this platform.

<?xml version="1.0" encoding="utf-8"?>
<platform name="platform_name" version="1.0" >
  <description></description>
  <FPGA  device="XC3S200" family="spartan3" package="tq144" speed="-4"/>
  <simulation lang="VHDL">
    <library filename="apf_test_pkg.vhd">
        <description>
        </description>
    </library>
    
  </simulation>
  <components>
     <component name="syscon"/>
     <component name="irq_mngr"/>
  </components>
  <interfaces>
    <interface name="fpga">
      <ports>
        <port name="FPGA01" standard="LVCMOS" position="P141" drive="8" freq="96"/>
      <ports>
    <interface>
  </interfaces>
</platform>

fpga node

This node defines the FPGA with the following attributes

• family : fpga type ex: Spartan3,CycloneII,...
• device: complete fpga reference.
• speed : the speed of component.
• package: the package of fpga.
• main_clock: the frequency of the main clock connected to the FPGA in kHz.

components node

This node gives the list of auto-loaded components when the platform is selected. The component node has the following attribute :

• name: the name of the component.

interfaces node

This node is identical to interface node of a component.

simulation node

This node lists the libraries used for the simulation. The library files can be found in the simulation directory of the platform directory. Each file is described with a simlib subnode and an attribute filename.

<simulation>
    <simlib filename="atmega_emi_pkg.vhd" />
</simulation>

Toolchain file format

Toolchain files are used to describe the tools/languages used to synthesize, to simulate or to generate the drivers.

<?xml version="1.0" encoding="utf-8"?>
<toolchain name="toolchain_name" version="1.0" type="synthesis" >
  <description></description>
</toolchain>

Attributes of toolchain node are:

• name: toolchain name
• type: toolchain type : synthesis,simulation

For each toolchain type, a node is added:

simulation node

To simulate a project, the language name and the library name are required:

• language: testbench language (VHDL,SystemC,...)
• library: library used during the simulation ("work" in general)

Each element has an attribute name.

<language name="VHDL"/>
<library name="work"/>

synthesis node

Tool

To synthetize a project, the tool name has to be given

• tool: tool used for the synthesis (ISE,Quartus,...)
• command: command used to launch it in shell mode. This command will be used by POD to launch the tcl script with call : "command < tclscript.tcl"

 <tool name="ise" command="xtclsh" />

Script

POD can generate script for synthesis tool, the name of script is given by <script/> node:

 <script filename="ise_script.tcl" />

• name:file name of the script generated in synthesis/ directory.

Bus file format

Describes a bus which can be automatically managed by POD.

<bus name="wishbone16" version="1.0" datasize="16">
    <description></description>
    <class name="WBM" type="master">
        <type name="ADR" type="address" dir="out" />
        <type name="DAT_I" type="datain"    dir="in" />
        <type name="DAT_O" type="dataout"    dir="out" />
        <type name="WE"  type="write"  dir="out" />
        <type name="SEL" type="select" dir="out" />
        <type name="ACK" type="ack"     dir="in" />
        <type name="CYC" type="cycle"  dir="out" />
        <type name="STB" type="strobe" dir="out" />
    </class>
    <class name="WBS" type="slave">
        <type name="ADR" type="address" dir="in" />
        <type name="DAT_I" type="datain"   dir="in" />
        <type name="DAT_O" type="dataout"   dir="out" />
        <type name="WE" type="write"  dir="in" />
        <type name="SEL" type="select" dir="in" />
        <type name="ACK" type="ack"    dir="out" />
        <type name="CYC" type="cycle"  dir="in" />
        <type name="STB" type="strobe" dir="in" />
    </class>
</bus>

Project file format

A project description file is built by POD for each project created by the user.

<?xml version="1.0" encoding="utf-8"?>
<project name="ledbutton" version="1.0" >
  <description></description>
  <language name="VHDL"/>
  <bsp directory="/home/login/armadeus/target/linux/module/fpga/pod" os="linux" />
  <components>
    <component name="syscon01"/> 
    <component name="led01"/> 
    ...
  </components>
  <platform>
  ...
  </platform>
  <toolchains>
    <simulation name="ghdl"/>
    <synthesis name="ise" />
  </toolchains>
</project>

Node description:

• components: gives the instances list.
• platform : copy of platform.xml file, describes the platform used.
• language : language used for the synthetis.
• toochains: toolchain used for the project.
• bsp : this node indicates:
  • directory : where the driver will be copied.
  • os : the targeted operating system