POD create component

Page under construction... 

Informations on this page are not guaranteed !!

This chapter describe how-to create a component for a POD library. There is two way to create a component:

• By hand : create directory and xml description with your favorite text editor and file manager.
• With POD : using library environnement and its commands to generate the component.

Whatever method used, 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>

This can be done in library POD environment :

$ pod
POD>library
POD.library> addlibrary path_to_my_lib/my_lib
POD.library> load my_lib
POD.library:my_lib>

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.

By hand

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>

With POD

First select your working library as indicated in first paragraph then create component :

POD.library> load my_lib
POD.library:my_lib> component 
POD.library.component> create my_component.wb16
POD.library:podvirginlib.my_component>

Then description can be set with setdescription command:

POD.library:podvirginlib.my_component> setdescription testing component

Add HDL files

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

By hand

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

With POD

POD.library:podvirginlib.my_component> addtophdlfile my_component_top.vhd
POD.library:podvirginlib.my_component> addhdlfile my_component_bottom.vhd

Create interfaces

Interfaces are used to group ports of same category.

By hand

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>

With POD

POD.library.component> addinterface int_button
POD.library.component> setinterface int_button class=GLS
POD.library.component> addinterface clock_and_reset 
POD.library.component> setinterface clock_and_reset class=CLK_RST
POD.library.component> addinterface swb16
POD.library.component> setinterface swb16 class=SLAVE 
POD.library.component> setinterface swb16 bus=wishbone16 
POD.library.component> setinterface swb16 clockandreset=clock_and_reset

Create ports

Ports are defined by a size and interface used.

By hand

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>

With POD

POD.library.component> addport button int_button
POD.library.component> editport int_button.button type=EXPORT
POD.library.component> addport irq int_button
POD.library.component> editport int_button.irq type=EXPORT

Assign pins

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

By hand

TODO

With POD

TODO

Adding driver templates files

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

By hand

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="3" />
		<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

With POD

TODO

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.

By hand

Add generic in <generics> node:

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

With POD

TODO

Add interruption

In some component a port is used to generate interruption.

By hand

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

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

With POD

TODO

Describe registers

Slave busses interfaces has registers that must be described.

By hand

<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>

With POD

TODO