Virtual Platform IP Authoring Requirements
One of the major challenges with peripheral IP authoring is to model and manage registers. Some IP may include tens of thousands of registers and hundreds of thousands of register fields, which can represent 80% to 90% of the model code. In addition, the IP developer may have to create multiple implementations of the model, each at different abstraction levels such as a TLM-2.0 model (LT and AT), a TLM synthesizable model or an RTL model.
All of these representations are likely to share the same set of registers, hence the need to have a unique, golden reference of the model registers from which the implementation models can be derived. For tool and IP interoperability reasons, this golden reference should be compliant to an existing standard. Hence the idea to use the IP-XACT (IEEE 1685) as the golden model to represent registers. For more details on IP-XACT for TLM refer to a recent Industry Insights article by Richard Goering.
IP-XACT supports all the major requirements for modelling IP register and memory banks. Its XML structure eases the processing of the metadata and the automation of the implementation code at various abstraction levels. SystemC Virtual Platform IP models are just one specific use case of IP-XACT, but it's interesting to look into the details of the specific requirements for SystemC IP model creation.
TLM-2.0 defines the main infrastructure for IP interoperability, but one thing it lacks is a standard representation of registers. Until a standard register representation becomes available the Virtual System Platform provides a class called sc_register.
Overview of tlmgen
The Virtual System Platform includes a TLM Generator, called tlmgen, that saves time and coding effort by automating the generation of SystemC TLM code, mainly for defining and accessing the registers, both from the bus and from the internal behavior of the model. In addition tlmgen provides the following:
The tlmgen solution is fully open. Not only you can get all of the above from an IP-XACT standard description, but the SystemC code that's generated relies on a SystemC register class delivered as source code to all Virtual System Platform users. It can therefore simulate on the OSCI simulator, but if you use Virtual System Platform to simulate and debug your code, you will be able to visualize the register descriptions and content at runtime.
Let's put our hands on the keyboard, and check how much code can be automatically generated and check how useful and how easy to update and maintain the code is. For this article, I propose to create a SystemC TLM-2.0 un-timed model for the PL011 UART, starting from the same ARM specification I used in my previous experiment.
Modelling the Registers
The first step is to capture the registers. Virtual System Platform offers two options:
The Cadence RDF format is a simple ASCII file, with a very simple grammar to describe each register and its fields and to describe a bank of registers with the base address for each.
Below is an example of a register bank for for the UART.
Each register in the register bank also has a description. Below shows the description of the UART data register.
One of the inputs for tlmgen is the specification of callback hooks in the register input format. These hooks are called PREAMBLE and POSTAMBLE. They indicate to the code generator that the user may want to add a specific functionality before and/or after a register access. For example, when writing to the DR register, the model should also write to TX field of the RIS register. In IP-XACT format the PREAMBLE and POSTAMBLE hooks are defined as register vendor extensions.You can see the example of postamble = RW in the picture above for the UART Data Register.
Below is an IP-XACT representation showing the vspExtensions and the equivalent POSTAMBLE for the UART Data Register.
Another nice feature of tlmgen is the ability to generate IP-XACT output from an RDF input file, thus letting the user start with a simple text register description format and automate the translation to the verbose IP-XACT XML format. This IP-XACT output can then be used later for platform assembly.
Generating the SystemC TLM model
This step can be mostly automated by the execution of tlmgen to take an IP-XACT (or RDF) input and generate the SystemC TLM output. The SystemC code generated includes a SystemC module skeleton that you can modify to add the specific functionality. This skeleton already includes the definition and implementation of registers, target socket, tlm transport methods and registers access functions.
Creating the HW IP is a two-step process:
1) Run the command:
% tlmgen -name uartPL011 -rdf uart_registers.rdl -simple
Or for IP-XACT input:
% tlmgen -name uartPL011 -ipxact uart_registers.xml -simple
This generates about 80% of the code for the UART. It includes the SystemC TLM-2.0 module skeleton for the model of the UART which derives from an automatically generated base class with all the registers defined, the target socket to access them and the implementation of the transport methods to access these registers.
2) Update the generated HW template code to match the UART behavior.
Once the base model is generated it's up to the model creator to add processes, add extra ports, and add the functionality inside the pre- and post-register access virtual methods. This completes the model functionality.
The advantage of using tlmgen is not only that you save writing code (and writing errors), but also that all the registers can be visualized at runtime.
Below is the register viewer which provides the values at runtime by automatically recognizing the sc_register class. This is very helpful for software engineers who spend much of their time reading, writing, shifting, ANDing, and ORing register bits to make the hardware do what it is supposed to do.
One of the issues with code generation from a golden source is the ability to manage (not lose) user modifications when the golden source needs to be modified. Let's assume one of the bit fields of the register of our UART IP needs to be modified. How should we propagate this change to the generated code? tlmgen solves this problem by generating a hierarchy of classes and virtual methods where the user functional code is localized in the top-most inherited class.
Whenever a change occurs in the golden register representation (RDF or IP-XACT), all of the base classes can be re-generated without loosing the user code. Moreover, most if the time, the user code does not need to change or needs very little and localized modification to include the new register change. Such an inheritance hierarchy of classes and virtual methods allow the user functional code to be localized, hence allowing reuse if the user code when the base classes have to be re-generated.
The flexibility of tlmgen also allows the user to choose the type of target interface generated depending on its usage. It could be a TLM-2.0 simple socket or multi passthrough socket or it could be a TLM-1.0 sc_export. In the tlmgen usage example above, the -simple option specifies a TLM-2.0 simple target socket.
Like any other IP, a virtual platform IP needs to be packaged to be delivered to other internal or external groups. Such a package should be self-contained, versioned, and easy to plug into a system and easy to verify. The IP should therefore be delivered as a kit including hardware verification, software verification, APIs, documentation, and scripts.
You have now an effective, standard, and reusable solution to ease the modeling and validation of TLM-2.0 peripheral IP using tlmgen from VSP.
Many models created using tlmgen have been integrated in various Virtual Platforms. It has proven to not only save a lot if development time but it also significantly helps the platform creator and the embedded software developer to debug and fine tune their hardware and software models. It overcomes the blank page syndrome when it's time to create a new model and provides much of the needed structure and checking to help users learn TLM-2.0 very quickly. The good news is that it doesn't try to hide the details of TLM-2.0 from the user, but instead generates clean code that users can learn from.
So what else is needed to help the Virtual Platform Model creator's life?
More complex register specification should be supported. Some are already supported by IP-XACT, others need extensions to the standard, such as preamble and postamble, conditional registers, dependant registers. These are all being considered as IP-XACT enhancements within Accellera Working Groups. As with any automation there is always more code that can be automatically generated such as multiple target sockets (and multiple memory maps), initiator sockets, and reset or interrupt behaviour by further using the information recorded in IP-XACT.
This Team ESL article is provided by Jean-Michel Fernandez, Archtect for System Solutions. Jean-Michel has actively contributed to the definition of the TLM and IP-XACT standards.
Boris, yes tlmgen is a stand-alone tool; it ships with the Virtual System Platform. The executable name is actually tlmgen. If you have a recent Incisive installation you will likely find it in there also.
Is timgen a stand-alone tool or part of the Virtual System platform?
I'd like to use simpleRDL and timgen to create IP-Xact model and then to generate SystemC sc_register class(es).
Can CtoS synthesize sc_register to RTL?