POD create component

This chapter describe how-to create a component for a POD library.

Some stuff are required :

Required:

• HDL top file : the top description of the component, with the external interface. POD library commands will parse interface to ease component creation.

Optional:

• All other HDL files.
• Driver template files.
• Documentation files.

Choose/create library

A component must be created in a library. Then, the first things to do is to choose the library. Official library can be use, but using personal library is encouraged. To add a personal library in POD, create a directory then add it in the configuration file (~/.podrc by default):

<?xml version="1.0" encoding="utf-8"?>
<podconfig>
    <libraries>
        <lib path="path_to_my_lib/my_lib" />
    </libraries>

Creating component

Component name must have exactly the same name as entity name of the top HDL component. A version name can be added to generate different xml description of the same VHDL file.

To create component «by hand» make directory with component name in library director and mandatory subdirectory as follow :

    my_lib
    |-- doc
    |-- hdl
    `-- drivers_templates

Then create xml file in component directory with name of version. Different version can be added for component description, it usefull when the same HDL code is used for différent interface configured with generics.

<?xml version="1.0" encoding="utf-8"?>
<component name="my_component" version="1.0">
	<description>
		A simple button ip
	</description>
</component>

Add HDL files

First things to do when a component is created is to add HDL files. Beginning with TOP HDL file.

Adding vhdl files names in xml :

<hdl_files>
    <hdl_file filename="hdl/my_component_top.vhd" scope="all" istop="1" />
    <hdl_file filename="hdl/my_component_bottom.vhd" scope="all" />
</hdl_files>

Then adding files in hdl directory:

hdl/
|-- my_component_bottom.vhd
`-- my_component_top.vhd

Create interfaces

Interfaces are used to group ports of same category.

Interfaces are described in <interfaces> node :

<interfaces>
		<interface name="int_button" class="GLS" />
		<interface name="clock_and_reset" class="CLK_RST" />
		<interface name="swb16" class="SLAVE" bus="wishbone16" clockandreset="clock_and_reset" />
</interfaces>

Create ports

Ports are defined by a size and interface used.

Open the <interface> node where port must be integrated then use <ports> node to list each port:

<interface name="int_button" class="GLS" >
    <ports>
	    <port name="button" type="EXPORT" size="1" dir="in" />
	    <port name="irq" type="EXPORT" size="1" dir="out" />
	</ports>
</interface>

Assign pins

Some component are designed by default for specific platform, then default pin assignation can be done to simplify user configuration. TODO

Adding driver templates files

Note: Read POD_Drivers to know how to write a driver tempate for POD

Template files are used for a specific BSP also named "architecture".

Use driver_files node to describe driver_templates files used. One driver_templates node for each architecture.

<driver_files>
    <driver_templates architecture="armadeus">
        <support version="4.0" />
		<file name="Makefile" />
		<file name="my_component.c" />
        <file name="my_component.h" />
    </driver_templates>
</driver_files>

And copy each file in directory with name of architecture

drivers_templates/
`-- armadeus
    |--  Makefile
    |--  my_component.c
    `--  my_component.h

Describe generics

Generics are found automatically by the parser of POD, but sometimes, others generic are necessary for drivers side then others generic must be added. And all generics must be configured by the develloper to define some caracteristics.

Add generic in <generics> node:

      <generic name="id" public="true" value="1" match="\d+" type="natural" destination="both" />

Add interruption

In some component a port is used to generate interruption.

Use node <interrupts> to designate interface.port that generate interruption.

<interrupts>
	<interrupt interface="int_button" port="irq" />
</interrupts>

Describe registers

Slave busses interfaces has registers that must be described.

<registers> node is included in slave bus interface :

<interface clockandreset="candr" name="swb16" class="SLAVE" bus="wishbone16" >
    <registers>
        <register name="id" offset="0x00" size="16" rows="1" />
		<register name="reg_button" offset="0x01" size="16" rows="1" />
	</registers>
    ...
</interface>