GreenBus Auto Generation Project

#!html

Download a first Version

This project will automatically generate GreenBus components from SPIRIT compatible XML. The aim is also to feed back to SPIRIT / IP-XACT any extentions required to describe a bus fabric.

Alpha Version released

Download here

Contents:

1. codestructure: These classes are used to build a C++ and SystemC code structure like classes, functions, variables. Essentially for getting greenbus code is the method call "toSystemC()" in each of the classes.
2. datastructure: The generated JAXB Java classes from the Spirit XML schema by using the Java tool "xjc"
3. docs: Java documentation of IPIGen source code
4. input/ipxact: Contains SPIRIT example files for a bus defintion (busdef.xml), a master component (master1.xml), a slave component (slave1.xml), a bus component (gb1.xml) and an interconnection design (gb_design.xml)
5. ipigen: Contains the main file for IPIGen. Invoking "java IPIGEN [SPIRIT files]" will start the program
6. libs: These are the necessary JAXB 2.0 libs for compiling IPIGen
7. model: The model represents greenbus components in Java objects. From here the router-side protocol (attributes, phases,...), the port-side protocol (access to attributes, transaction defintion, notifications,...) and the user API are built
8. output/greenbus:
9. : i. generatedModuls: Modules which are generated from the given SPIRIT bus definition (router-side protocol, port-side protocol,...)
10. : i. generatedStubs: UserAPI which is generated according to the master and slave components (in progress / test status), user must add the component behavior here
11. : i. genericGreenBus: Generic parts of the greenbus implementation which don't have to be changed
12. : i. greenbus: Greenbus user code (makefile, main program, executable simulation) plus a log file (log_simplebus.txt) containing an simulation example of simplebus

Short description for starting the program:

1. Specify the functionality of the bus in a IP-XACT bus defintion (see example "busdef.xml" in folder "input/ipxact") and put the xml file in folder "input/ipxact".
2. Specify master and slave components (see example "master1.xml" and "slave1.xml" in folder "input_ipxact") which bus interfaces refer to the previously defined bus definition and put them in folder "input/ipxact".
3. Start the program by invoking "java IPIGen" and add the names of all your SPIRIT files as program arguments.
4. The generation of greenbus datastructure and source code is performed and stored in folder "output/greenbus". The user has to add the master and slave components behavior in sub-folder "generatedStubs" (see example "master.tpp"). At the moment four methods can be used. Two blocking methods b_read() and b_write() with parameters data and address, and two non-blocking methods read() and write() with parameters data, address and burst length.
5. Compile greenbus by invoking "make" in sub-folder "greenbus" and start the simulation.

GreenBus generation

Short-term strategy

1. Elaborating the sections of GreenBus components which have to be configurable
2. Mapping of these parts to SPIRIT
3. Extending SPIRIT to meet the requirements of a bus fabric

Overview of GreenBus components

• Master components: responsible to start a message
• Slave components: receiving and responding to a message
• Router: transferring messages from master components to slave components regarding the protocol
• Protocol: defining the attributes (e.g. read/write command, target address, data types) and the phases (e.g. request, data transmission) of a transaction, notifying the router to forward processed messages
• Scheduler: processing the sequence of messages

Key elements of SPIRIT

• Bus definition: definition of the signals that comprise a bus including information about present signals on a master, slave, or system interface, signal direction, width, default values, etc.
• Component: definition of a single IP containing information about register and address map requirements, bus interfaces (instances of bus definitions), views, i/o etc.
• Design: definition of a subsystem containing information indicating how a set of components is to be configured and connected
• Generator: definition of tools that are to be run to transform the design containing descriptions e.g. when and where the tools should be run

Generation of GreenBus components out of a SPIRIT description

How can the generator be integrated in SPIRIT?

• Tight Generator Interface (TGI) in IP-XACT release alpha2
  • generator invocation (e.g. executable, parameters)
  • TGI API

Which are the topics for generation?

• Meta data
  • Attributes of a transaction (e.g. name, type, description)
  • Access to attributes (e.g. get/set methods)
  • Structure of user data (e.g. type)
  • Enumeration of master commands and slave responses (e.g. read/write)
  • phases of a transaction (see long-term goals)

How can these topics be defined in SPIRIT?

• Within IP-XACT busses are basically regarded as components.
• Ports of a IP-Component are specified in the bus interface.
• IP-Components are connected together by linking their bus interfaces.
• A Bus-IP is defined in the bus definition, which is referred by the components bus interfaces. Therefore the bus defintion is a "common standard" of the IP-component interfaces so that they are compatible. So far the bus definition only contains definitions of the interfaces, but no behavior of the bus itself. To define generic attributes which are used by a bus fabric the SPIRIT specification needs to be extended.

How can the different phases of a transaction be defined in SPIRIT?

• As there are no attributes which are used in different phases in the OCP standard one could say that attributes are associated with phases. So if a certain attribute is specified the corresponding phase is specified, too.

What has to be specified exactly in xml? (in progress)

• metaDataConstraints (attribute portRef (optional))
  • transactionAttributes (attribute "abstrationLevel", attribute "genericType/specificType", attribute "mandatory/optional")
    • transactionAttribute
      • attrName
      • type/width
        • choiceRef (for user-specific enumeration types)
      • transactionPhase
      • equivalentAttribute (reference to transactionAttribute) (generic <-> specific)
      • transformation (reference to FileSet)
      • access (reference to FileSet)
      • parameters
      • description

Where can the attribute extensions be integrated into IP-XACT?

The set of attributes a bus can cope with is actually the definition of its functionality because an attribute is just the content of the data currently transferred over the bus similar to meta-data information. Therefore one possible and probably the best place to integrate the extensions for specifying attributes is the busDefinition. At instantiation time the IP components busInterfaces should refer to this busDefinition to be compatible to each other.

There are two approaches of integration:

• approach 1: mapping of protocol-specific attributes to generic GreenBus attributes is done by the GreenBus component (using different protocols is hardly possible)
  • append to: busDefinition
• approach 2: mapping of protocol-specific attributes to generic GreenBus attributes is done on the IP component side e.g. in the interface or in the outgoing ports of the IP component
  • append to: busDefintion -> ports -> port -> onSystem/onMaster/onSlave

Overview of attributes of the OCP Specification and their type representation in SystemC

<:#FF8080> phase	<:#FF8080> attribute	<:#FF8080> IP-XACT type	<:#FF8080> SystemC type	<:#FF8080> importance
<|18#E0E0FF> request	MCmd	spirit:choice	enumeration	high
MAddr	spirit:long	unsigned long long	high
MAddrSpace	spirit:long	unsigned int
MData	spirit:string	char*	high
MDataInfo	spirit:long	unsigned int
MByteEn	spirit:long	unsigned int
MID	spirit:long	unsigned int	high
MThreadID	spirit:long	unsigned int
MConnID	spirit:long	unsigned int
MTagID	spirit:long	unsigned int
MTagInOrder	spirit:bool	bool
MReqInfo	spirit:long	unsigned int
MAtomicLength	spirit:long	unsigned int
MBurstLength	spirit:long	unsigned int	high
MBurstPrecise	spirit:bool	bool
MBurstSeq	spirit:choice	enumeration
MBurstSingleReq	spirit:bool	bool
MReqLast	spirit:bool	bool
<|5#E0E0FF> data handshake	MDataByteEn	spirit:long	unsigned int
MDataLast	spirit:bool	bool
MDataTagID	spirit:long	unsigned int
MdataThreadID	spirit:long	unsigned int
MDataValid	spirit:bool	bool
<|8#E0E0FF> response	SData	spirit:string	char*
SResp	spirit:choice	enumeration	high
SThreadID	spirit:long	unsigned int
STagID	spirit:long	unsigned int
STagInOrder	spirit:bool	bool
SDataInfo	spirit:long	unsigned int
SRespInfo	spirit:long	unsigned int
SRespLast	spirit:bool	bool

Generation process (in progress)

<30%:#FF8080> generation process	<:#FF8080> screenshots
1. Generic attributes are extracted from bus defintion IP-XACT file seperated into master and slave attributes
2. Protocol-specific attributes are extracted from component IP-XACT files and mapped to the generic attribute which they refer to
3. If the type of the specific attribute differs from the type of the generic one in the mapping process a type-transformation has to be made. For this purpose a stub is being created where the user can add code to do this transformation
4. If there are generic attributes left, which could not have been mapped in step 3, a client stub is being prepared where the user can add code to specify each of the "free" generic attributes
5. If there are specific attributes left, which could not have been mapped to a generic attribute in step 3, an additional generic attribute is being created and a client stub is being prepared where the user can specify the created generic attribute (see "Important Issues")
6. The user API is created with the mapped attributes and the stub placeholders of "free" attributes
7. The router protocol and port protocol are created to define the generic attributes from bus definition and additionally created ones in step 6 and to provide master and slave access to these attributes

Important Issues (in progress)

1. Using generic attributes of the OCP standard (see above) is a way to transport semantical information from sender to receiver. By mapping of protocol-specific attributes to generic attributes semantics is transferred from generic to specific attribute. Even if there is no appropriate attribute defined in the specific protocol the user can be prompted to add the information GreenBus or its participants need to communicate properly. But problems occur if there exists no adequate generic attribute for an attribute of a certain protocol because sender and receiver exactly have to know the meaning of this attribute. To solve this problem there has to be a global repository of attributes and descriptions to this attributes to be able to publish a complete attribute list which is available to all developers and system designers.

... to be continued

Long-term goals

1. Transforming and mapping master/slave attributes to common generic attributes of GreenBus to be able to connect components with different protocols
2. Abstract description of the protocol phases to be able to even connect components which implement protocols with (slightly) different phases. For that we have to implement a SPIRIT-phase-state-machine with specified state transitions