Authors Jeremy Bennett
License CC-BY-2.0
Building a Loosely Timed SoC Model with OSCI TLM 2.0 A Case Study Using an Open Source ISS and Linux 2.6 Kernel Jeremy Bennett Embecosm Application Note 1. Issue 2 Publication date May 2010 Legal Notice This work is licensed under the Creative Commons Attribution 2.0 UK: England & Wales License. To view a copy of this license, visit http://creativecommons.org/licenses/by/2.0/uk/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA. This license means you are free: • to copy, distribute, display, and perform the work • to make derivative works under the following conditions: • Attribution. You must give the original author, Embecosm (www.embecosm.com), credit; • For any reuse or distribution, you must make clear to others the license terms of this work; • Any of these conditions can be waived if you get permission from the copyright holder, Embecosm; and • Nothing in this license impairs or restricts the author's moral rights. The software examples written by Embecosm and used in this document are licensed under the GNU General Public License (GNU General Public License). For detailed licensing information see the file COPYING in the source code of the examples. Embecosm is the business name of Embecosm Limited, a private limited company registered in England and Wales. Registration number 6577021. ii Copyright © 2008, 2010 Embecosm Limited Table of Contents 1. Introduction ................................................................................................................ 1 1.1. New in Issue 2 ................................................................................................. 1 1.2. Target Audience ................................................................................................ 1 1.3. About the Embecosm TLM 2.0 Application Notes .............................................. 2 1.4. Acknowledgment ............................................................................................... 2 2. Background to SystemC and the TLM 2.0 Standard .................................................... 3 2.1. What is SystemC .............................................................................................. 3 2.2. What is a TLM ................................................................................................. 4 2.2.1. Hardware and Software Views of Parallelism ........................................... 4 2.2.2. Modeling Hardware Parallelism in Software ............................................ 4 2.3. Overview of OSCI TLM 2.0 ................................................................................ 4 2.3.1. Transaction Payload ............................................................................... 5 2.3.2. Initiators and Targets ............................................................................. 6 2.3.3. Blocking, Non-Blocking, Debug and Direct Memory Interfaces ................. 6 2.3.4. Loosely Timed, Approximately Timed and Untimed TLM .......................... 6 2.3.5. TLM 2.0 Convenience Sockets ................................................................ 7 3. Case Study: A Loosely Timed SoC Using TLM 2.0 ........................................................ 8 3.1. The Example Designs ....................................................................................... 8 3.1.1. Or1ksim ISS TLM 2.0 Wrapper with Logger ............................................. 9 3.1.2. Simple SoC Design ................................................................................. 9 3.1.3. SoC with Interrupt Support .................................................................... 9 3.1.4. SoC with Debugger Support ................................................................. 10 3.2. Example Code ................................................................................................. 10 3.2.1. Source Code for Example Models and Programs .................................... 10 3.2.2. Code Documentation ............................................................................ 11 3.2.3. SystemC Model Coding Conventions ..................................................... 11 3.2.4. Derived classes ..................................................................................... 11 3.2.5. Configuration ....................................................................................... 12 4. Wrapping the ISS ...................................................................................................... 13 4.1. Modifying the Or1ksim ISS for TLM 2.0 ........................................................... 13 4.1.1. Converting Or1ksim to a Library ........................................................... 13 4.1.2. Additional Functionality for Or1ksim .................................................... 14 4.2. Or1ksim Wrapper Module Class Definition ...................................................... 14 4.2.1. Included Headers ................................................................................. 14 4.2.2. Module Declaration .............................................................................. 15 4.2.3. Constructor and Destructor .................................................................. 15 4.2.4. Public Interface .................................................................................... 16 4.2.5. Threads ................................................................................................ 16 4.2.6. Upcalls ................................................................................................. 16 4.3. Or1ksim Wrapper Module Class Implementation ............................................. 17 4.3.1. Headers and Macros ............................................................................. 18 4.3.2. Constructor .......................................................................................... 18 4.3.3. Thread .................................................................................................. 19 4.3.4. Upcalls ................................................................................................. 19 4.3.5. Blocking Transport ............................................................................... 20 5. Testing the Or1ksim ISS TLM 2.0 Wrapper ................................................................ 21 5.1. Overall Design of the Test Program ................................................................. 21 5.1.1. Class Structure .................................................................................... 21 5.1.2. Behavioral Diagrams ............................................................................ 21 5.2. Definition of the TLM 2.0 Logger Module ......................................................... 22 5.2.1. Include Files ......................................................................................... 22 iii Copyright © 2008, 2010 Embecosm Limited 5.2.2. Module Declaration and Constructor .................................................... 22 5.2.3. Public Interface .................................................................................... 23 5.2.4. Blocking Transport ............................................................................... 23 5.3. Implementation of the TLM 2.0 Logger Module ................................................ 23 5.3.1. Included Headers ................................................................................. 23 5.3.2. Constructor .......................................................................................... 23 5.3.3. Blocking Transport Callback ................................................................. 23 5.4. The Model Main Program ................................................................................ 24 5.4.1. Included Headers ................................................................................. 24 5.4.2. Argument Processing ............................................................................ 25 5.4.3. Module Instantiation ............................................................................ 25 5.4.4. Connecting the Modules ....................................................................... 25 5.4.5. Model Execution ................................................................................... 25 5.5. Test Program to Run on the Or1ksim .............................................................. 26 5.5.1. The Utility Functions ............................................................................ 26 5.5.2. Memory Mapped Data Structure ........................................................... 26 5.5.3. Checking Write Access ......................................................................... 26 5.5.4. Checking Read Access .......................................................................... 27 5.5.5. Program Compilation ............................................................................ 27 5.6. Running the Test ............................................................................................ 28 5.6.1. Compiling the SystemC Model .............................................................. 28 5.6.2. Configuring the OpenRISC 1000 Or1ksim ISS ........................................ 28 5.6.3. Running the Compiled Model ............................................................... 28 6. Modeling Peripherals ................................................................................................. 30 6.1. Details of the 16450 UART ............................................................................. 30 6.2. UART Module Design ...................................................................................... 31 6.2.1. UART Model Interfaces ......................................................................... 31 6.2.2. UART Model Registers .......................................................................... 32 6.2.3. UART Model Interrupts ......................................................................... 32 6.3. Extending the Or1ksimSC Wrapper Module ...................................................... 32 6.3.1. Adding an Endianness Test Function to the Or1ksim Library ................. 32 6.3.2. Extended Or1ksim Wrapper Module Class Definition ............................. 33 6.3.3. Extended Or1ksim Wrapper Module Class Implementation .................... 33 6.4. UART: Module Class Definition ....................................................................... 34 6.4.1. Headers and Constant Definitions ........................................................ 34 6.4.2. Class Declaration and Constructor ....................................................... 35 6.4.3. Public Interface .................................................................................... 35 6.4.4. SystemC Processes ............................................................................... 35 6.4.5. Blocking Transport Callback ................................................................. 36 6.4.6. Utility Functions .................................................................................. 36 6.4.7. UART State .......................................................................................... 36 6.4.8. Notifying the Bus Thread of Transaction Activity ................................... 36 6.5. UART Module Class Implementation ............................................................... 37 6.5.1. UART Constructor ................................................................................ 37 6.5.2. UART Processes .................................................................................... 37 6.5.3. UART Blocking Transport Callback ....................................................... 38 6.5.4. UART Read Behavior ............................................................................ 38 6.5.5. UART Write Behavior ............................................................................ 39 6.5.6. UART Utility Functions ......................................................................... 39 7. Adding a Terminal as a Test Bench ........................................................................... 40 7.1. Overall Design of the Simple SoC Model ......................................................... 40 7.1.1. Class Structure .................................................................................... 40 7.1.2. Behavioral Diagrams ............................................................................ 40 iv Copyright © 2008, 2010 Embecosm Limited 7.2. SystemC Terminal Module Design ................................................................... 41 7.3. Terminal Module Class Definition ................................................................... 42 7.3.1. Mapping Signals to Class Instances ...................................................... 42 7.3.2. The SystemC Class ............................................................................... 42 7.3.3. Setting up the xterm ............................................................................. 42 7.3.4. Signal and event handling .................................................................... 42 7.4. Terminal Module Class Implementation .......................................................... 42 7.4.1. SystemC Processes ............................................................................... 43 7.4.2. Signal and event handling .................................................................... 43 7.5. The Complete SoC .......................................................................................... 43 7.5.1. The Model Main Program ...................................................................... 43 7.5.2. Test Program to Run on the Or1ksim ISS .............................................. 44 7.5.3. Compiling and Running the Model ....................................................... 46 7.5.4. Model Timing ....................................................................................... 47 8. Adding Synchronous Timing to the Model ................................................................. 50 8.1. Summary of Changes Required for Synchronous Timing .................................. 50 8.2. Overall Design of the Synchronized SoC Model ................................................ 50 8.2.1. Class Structure .................................................................................... 51 8.2.2. Behavioral Diagrams ............................................................................ 51 8.3. Extending the Or1ksimExtSC Wrapper Module ................................................. 52 8.3.1. Adding Clock Rate and Timing Functions to the Or1ksim Library ........... 52 8.3.2. Or1ksimSyncSC Module Class Definition ................................................. 52 8.3.3. Or1ksimSyncSC Module Class Implementation ........................................ 53 8.4. Extending the UartSC Module Class ................................................................ 54 8.4.1. UartSyncSC Module Class Definition ...................................................... 54 8.4.2. UartSyncSC Module Class Implementation ............................................. 55 8.5. Extending the TermSC Module Class ................................................................ 56 8.5.1. TermSyncSC Module Class Definition ...................................................... 57 8.5.2. TermSyncSC Module Class Implementation ............................................. 57 8.6. Main Program for the Synchronous Model ...................................................... 58 8.7. Compiling and Running the Synchronous Model ............................................. 58 9. Adding Temporal Decoupling to the Model ................................................................ 60 9.1. What is Temporal Decoupling ......................................................................... 60 9.1.1. Timing Concepts ................................................................................... 60 9.1.2. The Global Quantum Class, tlm_global_quantum .................................. 62 9.1.3. TLM 2.0 Quantum Keepers ................................................................... 63 9.1.4. Other Styles of Temporal Decoupling .................................................... 63 9.2. Guidelines for Using TLM 2.0 Temporal Decoupling ......................................... 63 9.3. Overall Design of the Temporally Decoupled SoC Model ................................... 64 9.3.1. Class Structure .................................................................................... 64 9.3.2. Behavioral Diagrams ............................................................................ 65 9.4. Temporal Decoupling the Or1ksim Wrapper Class ........................................... 66 9.4.1. Adding a Function to the Or1ksim Library to Support Temporal Decoupling ..................................................................................................... 67 9.4.2. Or1ksimDecoupSC Module Class Definition ............................................. 67 9.4.3. Or1ksimDecoupSC Module Class Implementation .................................... 67 9.5. Modifying the UART to Support Temporal Decoupling ..................................... 69 9.5.1. uartDecoupSC Module Class Definition .................................................. 69 9.5.2. uartDecoupSC Module Class Implementation ......................................... 69 9.6. Main Program for Temporal Decoupling .......................................................... 70 9.7. Compiling and Running the Decoupled Model ................................................. 70 10. Modeling Interrupts and Running Linux on the Example SoC ................................... 73 v Copyright © 2008, 2010 Embecosm Limited 10.1. Overall Design of the SoC Model with Interrupts ........................................... 73 10.1.1. Class Structure .................................................................................. 73 10.1.2. Behavioral Diagrams .......................................................................... 74 10.2. Extending the Or1ksimDecoupSC Module Class ............................................... 75 10.2.1. Adding Interrupt Generation Functions to the Or1ksim Library ............ 75 10.2.2. Or1ksimIntrSC Module Class Definition ............................................... 76 10.2.3. Or1ksimIntrSC Module Class Implementation ...................................... 76 10.3. Extending the UartDecoupSC Module Class .................................................... 77 10.3.1. UartIntrSC Module Class Definition .................................................... 77 10.3.2. UartIntrSC Module Class Implementation ........................................... 78 10.4. Main Program for the Interrupt Driven Model ................................................ 79 10.5. Running the Interrupt Driven Model ............................................................. 79 10.5.1. Simple Test for the Interrupt Driven SoC Model .................................. 79 10.5.2. Running Linux .................................................................................... 79 11. Adding a JTAG Interface to the Model ..................................................................... 82 11.1. Overall Design of the SoC Model with JTAG Interface .................................... 83 11.1.1. Class Structure .................................................................................. 83 11.1.2. Behavioral Diagrams .......................................................................... 84 11.2. A TLM 2.0 Interface for JTAG Using a Payload Extension ............................... 84 11.2.1. JtagExtensionSC Extension Class Definition ....................................... 85 11.2.2. JtagExtensionSC Extension Class Implementation ............................... 86 11.3. Extending the Or1ksimIntrSC Module Class .................................................. 86 11.3.1. Adding JTAG Interface Functions to the Or1ksim library ..................... 86 11.3.2. Or1ksimJtagSC Module Class Definition ............................................... 87 11.3.3. Or1ksimJtagSC Module Class Implementation ...................................... 88 11.4. A JTAG Traffic Generating Class ................................................................... 89 11.4.1. JtagLoggerSC Module Class Definition ................................................ 90 11.4.2. JtagLoggerSC Module Class Implementation ....................................... 91 11.5. Main Program for the Model with JTAG Debug Interface ................................ 92 11.6. Running the Model with JTAG Debug Interface ............................................. 93 11.6.1. Simple Test for the Model with JTAG Debug Interface ......................... 93 A. Downloading the Example Models ............................................................................. 96 A.1. Configuring and Building ................................................................................ 96 A.2. Building the Linux Kernel ............................................................................... 97 B. Running with Mac OS ............................................................................................... 98 Glossary ....................................................................................................................... 99 References .................................................................................................................. 104 vi Copyright © 2008, 2010 Embecosm Limited List of Figures 2.1. Key components in an OSCI TLM 2.0 model. ............................................................ 5 3.1. Testing the TLM 2.0 wrapper for Or1ksim. ................................................................ 9 3.2. Simple SoC based on the OpenRISC 1000 Or1ksim. .................................................. 9 3.3. Simple SoC based on the OpenRISC 1000 Or1ksim with interrupts and MMU enabled. ........................................................................................................................ 10 3.4. Simple SoC based on the OpenRISC 1000 Or1ksim with separate JTAG interface. .... 10 5.1. Class diagram for the Or1ksim test model. ............................................................. 21 5.2. Sequence diagram for a read transaction with the Or1ksim test model. .................... 22 5.3. Output from the logger test of the Or1ksim wrapper module. .................................. 29 6.1. 16450 UART: Key interfaces. .................................................................................. 30 7.1. Class diagram for the simple Or1ksim SoC. ............................................................ 40 7.2. Sequence diagram for a write transaction with the Or1ksim simple SoC. .................. 41 7.3. SystemC terminal model using a xterm child process. ............................................. 41 7.4. UART loop back program log output. ..................................................................... 46 7.5. xterm with the UART loop back program running. .................................................. 47 7.6. UART loop back program log output with timing annotation. .................................. 49 8.1. Class diagram for the Or1ksim SoC with synchronized timing. ................................ 51 8.2. Sequence diagram for the Or1ksim SoC with synchronized timing, showing the timing calls. .................................................................................................................. 51 8.3. UART loop back program log output. ..................................................................... 59 9.1. Diagram illustrating temporal decoupling ............................................................... 61 9.2. Class diagram for the Or1ksim SoC with decoupled timing. ..................................... 64 9.3. Sequence diagram for the Or1ksim SoC with decoupled timing, showing interaction with the quantum keepers. ........................................................................................... 66 9.4. UART loop back program log output with temporal decoupling. ............................... 71 9.5. UART loop back program log output with temporal decoupling and 10ms global quantum. ...................................................................................................................... 71 10.1. Simple SoC based on the OpenRISC 1000 Or1ksim with interrupts and MMU. ........ 73 10.2. Class diagram for the Or1ksim SoC with interrupts. ............................................. 74 10.3. Sequence diagram for a write transaction on the Or1ksim SoC with interrupts....... 75 11.1. Simple SoC based on the OpenRISC 1000 Or1ksim with interrupts, MMU and JTAG debug interface. ................................................................................................... 82 11.2. Simple SoC based on the OpenRISC 1000 Or1ksim with interrupts, MMU and JTAG logger. .................................................................................................................. 82 11.3. Class diagram for the Or1ksim SoC with JTAG interface. ...................................... 83 11.4. Sequence diagram for a debug transaction on the Or1ksim SoC with JTAG interface. ....................................................................................................................... 84 vii Copyright © 2008, 2010 Embecosm Limited List of Tables 6.1. NS 16450 UART Registers ...................................................................................... 31 viii Copyright © 2008, 2010 Embecosm Limited Chapter 1. Introduction The Open SystemC Initiative (OSCI) has issued the second version of its standard for Transaction Level Modeling (TLM) in June 2008 [6]. This defines an interface for writing high level software models of hardware. An updated version (TLM 2.0.1) was released in July 2009. The OSCI standard is comprehensive. As well as a powerful general purpose interface, it defines a number of convenience components to facilitate adoption of the technology. This application note provides an introductory tutorial on using TLM 2.0 for loosely timed models—ideally suited for early development of embedded software. It demonstrates through a practical case study the development of a complete SoC, capable of running a modern Linux 2.6 kernel, using the TLM 2.0 convenience components. One of the most important components in any SoC system model is the processor core Instruction Set Simulator (ISS). This application note demonstrates how to wrap an existing ISS to provide a TLM 2.0 compliant interface. This application note is the first in a series from Embecosm (www.embecosm.com), providing case studies in OSCI TLM 2.0 use. The objective is to provide an introduction to TLM 2.0 within a practical context. Examples are provided throughout, based on open source components, which are freely reusable under the GNU General Public License. 1.1. New in Issue 2 Issue 2 of the application note is based on TLM 2.0.1. The wrapping of the ISS is extended to cover modeling of the JTAG interface and its connection to the GNU debugger, GDB. To aid in understanding how the components fit together, this issue includes UML class and sequence diagrams, showing the relationships and interaction between classes. The examples have been reworked to make them easier to build. In particular the example OpenRISC programs are now also built automatically. Finally, Robert Günzel (see Section 1.4), as well as making a number of well informed suggestions for improvements which I have adopted, has written a paper on using this application note under Mac OS (Appendix B). 1.2. Target Audience SystemC represents a challenge to engineers, because it bridges the divide between the worlds of hardware and software. These are two distinct disciplines, the languages of hardware design such as Verilog and VHDL are very different in philosophy to the languages of software development such as C++ and Java. Yet both are brought together in the world of the System on Chip SoC, where large embedded software systems must run on complex silicon chips often containing multiple processor cores of different architectures. This application note is aimed at any engineer intending to bridge the gap between hardware and software. It recognizes that the reader will most likely be expert in only one of these. Explanation is provided throughout of both the hardware ideas and software ideas being covered. The reader is assumed to have basic programming familiarity with C and C++ and the key concepts of object oriented programming: classes and instances of classes. A basic understanding of system level hardware design and the construction of SoC from components linked by buses (or on-chip networks). 1 Copyright © 2008, 2010 Embecosm Limited Familiarity with SystemC is assumed. The user guide supplied with SystemC provides a good introduction [7]. 1.3. About the Embecosm TLM 2.0 Application Notes The OSCI TLM 2.0 standard represents a significant advance in standardizing the creation of fast models of hardware. However the OSCI reference implementation lacks training material and examples to introduce new users to the technology. This series of Embecosm Application Notes was prompted by a customer requesting assistance in porting an existing ISS to the TLM 2.0 standard. This is the first application note in the series. Further Embecosm Application Notes, addressing different aspects of TLM 2.0 are available from the Embecosm website at www.embecosm.com. 1.4. Acknowledgment I am indebted to Dipl Ing Robert Günzel of the Department of Integrated Circuit Design at the Technische Universität Braunschweig, Germany, who made a number of suggestions for improvements (which I have adopted) and provided the instructions for Mac OS (see Appendix B). 2 Copyright © 2008, 2010 Embecosm Limited Chapter 2. Background to SystemC and the TLM 2.0 Standard The development of SystemC as a standard for modeling hardware started in 1996. Version 2.0 of the proposed standard was released by the Open SystemC Initiative (OSCI) in 2002. In 2006, SystemC became IEEE standard 1666-2005 [5]. OSCI has several groups working on supplementary standards. One of these is the TLM Working Group. It proposed its first standard for transaction level modeling in 2005. Two drafts for version 2.0 were released in 2006 and 2007. The version 2.0 standard issued in June 2008, with a minor update (2.0.1) issued in June 2009 [6]. 2.1. What is SystemC Most software languages are not particularly suited to modeling hardware systems1. SystemC was developed to provide features that facilitate hardware modeling, particularly the parallelism of hardware, in a mainstream programming language. An important objective was that software engineers should be comfortable with using SystemC. Rather than invent a new language, SystemC is based on the existing C++ language. SystemC is a true super-set of C++, so any C++ program is automatically a valid SystemC program. SystemC uses the template, macro and library features of C++ to extend the language. The key features it provides are: • A C++ class, sc_module, suitable for defining hardware modules containing parallel processes Note Process is a general term in SystemC to describe the various ways of representing parallel flows of control. It has nothing to do with processes in the Linux or Microsoft Windows operating systems. • A mechanism to define functions modeling the parallel threads of control within sc_module classes; • Two classes, sc_port and sc_export to represent points of connection to and from a sc_module; • A class, sc_interface to describe the software services required by a sc_port or provided by a sc_export; • A class, sc_prim_channel to represent the channel connecting ports; • A set of derived classes, of sc_prim_channel, sc_interface, sc_port and sc_export to represent and connect common channel types used in hardware design such as signals, buffers and FIFOs; and • A comprehensive set of types to represent data in both 2-state and 4-state logic. The full specification is 441 pages long [5]. The OSCI reference distribution includes a very useful introductory user guide and tutorial [7]. 1 There are some exceptions, most notably Simula67, one the languages which inspired C++. In some respects it is remarkably like SystemC. 3 Copyright © 2008, 2010 Embecosm Limited 2.2. What is a TLM 2.2.1. Hardware and Software Views of Parallelism To understand transaction level modeling, it is essential to understand the difference in approach to parallelism taken in hardware and software design. A hardware engineer, typically writing in a Hardware Description Language (HDL) such as Verilog or VHDL, describes a design as a collection of parallel activities, which communicate via shared data. The parallel activities are always (Verilog) or process (VHDL) blocks. The shared data structures are wires or signals. This follows very naturally the way that physical hardware behaves. There is no one flow of control—all parallel components are active at the same time, with their individual flow of control. By contrast, a software engineer typically describes parallelism in a design as a number of threads, which pass flow of control between them. The threads communicate by a number of mechanisms (message passing or remote procedure call for example), but although there is logical parallelism, only one thread is ever physically active at one time. This follows naturally the behavior on a conventional uni-processor CPU, where there is a single program counter indicating the next instruction to execute, and so only one flow of control. Even with modern multiprocessors, this is still a natural way of programming for the software engineer, because the number or threads or processes will often exceed the number of processor cores available. 2.2.2. Modeling Hardware Parallelism in Software A simple way to model hardware is via a round-robin, which updates the state of each component as time advances. Each component is represented as a software function. A master clock function calls each component function in turn when the clock advances—for example on each clock edge. The wires between the components are represented as variables shared between the components. A number of tools (e.g. ARC VTOC, ARM RealView SoC Designer, Carbon SpeedCompiler, Verilator) use this approach to cycle accurate modeling. With its close parallel of the way hardware is designed with languages such as Verilog and VHDL, this approach has merit for detailed modeling. It is well suited to cycle accurate modeling where every hardware register and wire must be accurate. Efficiency demands that not every HDL process or always is built as a separate function. Automated tools which generate cycle accurate models in SystemC from HDL can often reduce complex designs to a small number of functions executed on each cycle. For less detailed models, the overhead in calling each component whenever time advances cannot be justified. The solution is to model each component only when it has something to do. The individual components communicate by sending messages requesting data be transferred between each other. The exchange of messages is called a transaction, and the approach Transaction Level Modeling (TLM). This mirrors the way hardware behaves at the high level, where functional blocks communicate by reading and writing across buses. 2.3. Overview of OSCI TLM 2.0 OSCI TLM 2.0 offers a standard approach to building Transaction Level Models. 4 Copyright © 2008, 2010 Embecosm Limited At the simplest level a TLM is a set of SystemC modules (i.e. C++ classes), each providing one or more sockets through which the SystemC modules may read and write data. The behavior of each module is provided by a number of parallel threads (functions of the C+ + class), which communicate with the threads in other modules by passing data (i.e. reading or writing) through the sockets. This communication is known as a transaction and the data passed as a payload. Figure 2.1 shows the key components in a TLM 2.0 model. Socket Thread Module Module Figure 2.1. Key components in an OSCI TLM 2.0 model. 2.3.1. Transaction Payload The data passed in a transaction may take any form. However the TLM 2.0 standard defines a generic payload which is suitable for many uses, and which can be extended if required. By using the generic payload, a TLM 2.0 model will maximize interoperability. The main features of the generic payload are: Command Is this a read or a write? Address What is the address (in the hardware sense of an address in memory). Data A pointer to the physical data as an array of bytes Byte Enable Mask A pointer to an array indicating which bytes of the data are valid. Response An indication of whether the transaction was successful, and if not the nature of the error. Further features provide support for streaming, custom memory management and extensions to the generic payload. A TLM 2.0 transport function is used to pass the payload to another SystemC thread and obtain a response—i.e. a transaction. The generic payload is suitable for modeling a wide range of bus interfaces and protocols. However where additional features are required, TLM 2.0 provides an extension mechanism. 5 Copyright © 2008, 2010 Embecosm Limited The chapter on implementing a transactional JTAG debugger interface (see Chapter 11) describes the use of this extension mechanism to model the data for a bit-serial interface. 2.3.2. Initiators and Targets A module's threads may act as either initiators or targets. An initiator is responsible for creating a payload (see Section 2.3.1) and calling the transport function to send it. A target receives payloads from the transport function for processing and response. In the case of non- blocking interfaces (see Section 2.3.3), the target may create new transactions backwards in response to a transaction from an initiator. Initiator calls are made through initiator sockets, target calls received through target sockets. A module may implement both target and initiator sockets, allowing its threads to both generate and receive traffic. 2.3.3. Blocking, Non-Blocking, Debug and Direct Memory Interfaces There are two principal types of TLM 2.0 transport function. 1. The blocking transport functions are called by the initiator thread, received by the target thread, which processes the request and then returns the result. Until the transaction has been processed and released the initiator thread is blocked. 2. The non-blocking transport functions are called by the initiator thread, received by the target thread, which immediately returns, before processing the request. Subsequently the target, having processed the request makes a transport call backwards to the initiator to return the result. In the non-blocking case there are actually two types of transport used. The forward transport path is used by the initiator to pass the request to the target and the backward transport path used by the target to return the response. The advantage of the non-blocking transport interface is that the initiator can carry on processing, while the target is processing the request originally made. In addition TLM 2.0 provides two more specialized types of transaction. 1. A debug transaction is a read that does not affect the state of the model. These are for use by debuggers, which wish to see the state of a model, without affecting that state. 2. TLM 2.0 recognizes that a full-blown transaction is too heavyweight for some types of access. For example an ISS accessing memory using transactions would destroy performance. TLM 2.0 provides the concept of a direct memory interface, allowing threads direct access to blocks of memory in other threads for high performance. 2.3.4. Loosely Timed, Approximately Timed and Untimed TLM TLM 2.0 considers two levels of timing detail. 1. A loosely timed model uses transactions corresponding to a complete read or write across a bus or network in physical hardware. It provides timing at the level of the individual transaction. 2. An approximately timed model breaks down transactions into a number of phases corresponding much more closely to the phasing of particular hardware protocols (for example the address and data phases of an AHB read or write). Typically loosely timed models are implemented with a blocking interface and approximately timed models with a non-blocking interface. TLM 2.0 also introduces the concept of temporal decoupling. Standard SystemC keeps a single synchronized view of time, which is used by all threads in all modules. However with temporal 6 Copyright © 2008, 2010 Embecosm Limited decoupling, each thread can keep its own local view of time, allowing the thread to run ahead in simulation time, until it needs to synchronize with another thread. This improves performance in loosely timed models with blocking interfaces, by avoiding bottlenecks in processing. To ensure that one thread doesn't run away hogging all the processing, TLM 2.0 temporal decoupling uses the concept of the quantum, the greatest amount that a thread may differ in timing from the central view of time. This allows other threads a chance to catch up TLM 2.0 does not have an explicit concept of an untimed socket (something that was explicit in TLM 1.0). The standardization group took the view that in practice all models need some concept of time, so purely untimed models are of little value. However, untimed models are easily implemented as loosely timed models which always set the timing parameter in transport calls to zero. The example in Chapter 4, Chapter 6 and Chapter 7 uses this approach to create an untimed model. This is then refined in Chapter 8 to add synchronous timing information and in Chapter 9 to add temporal decoupling. 2.3.5. TLM 2.0 Convenience Sockets The standard TLM 2.0 approach to modeling requires the user to derive their own classes from the standard TLM 2.0 sockets, so that those sockets can then implement the TLM 2.0 interfaces. Modules then instantiate these derived sockets and use the bind function to connect them to sockets on other modules. This is a very flexible approach, but the need to define new derived classes for sockets is an unnecessary layer of complexity for simple modeling. For such uses, the TLM 2.0 standard defines a number of convenience sockets which can be instantiated directly by modules, and which specify their interface functions as callbacks. These convenience sockets are used throughout the case study in this application note. 7 Copyright © 2008, 2010 Embecosm Limited Chapter 3. Case Study: A Loosely Timed SoC Using TLM 2.0 In this case study, TLM 2.0 convenience sockets are used to wrap an existing ISS. This is then built into a simple SoC using additional hand-written TLM 2.0 components. Modeling uses the TLM 2.0 generic payload with no extensions. It is independent of the specific bus architecture that will be used in the implementation. The ISS used is from the OpenCores (www.opencores.org) project. This open source project has developed a complete 32/64-bit architecture, the OpenRISC 1000, complete with GNU compiler chain, architectural simulator and Linux port. This application note uses the OpenRISC 1000 architectural simulator, Or1ksim as the ISS for all the examples. The model is constructed in a number of stages: 1. The basic wrapper for the Or1ksim ISS is built using TLM 2.0 convenience sockets and tested with a simple logger. In this first stage timing is ignored—this is effectively an untimed model. See Chapter 4 and Chapter 5. 2. A model UART is added as an example peripheral, demonstrating how TLM 2.0 and existing SystemC technologies can be mixed. See Chapter 6. 3. A model of a terminal is added as a test bench for the SoC. This demonstrates how to add SystemC components which use operating system I/O without blocking the SystemC thread. See Chapter 7. 4. Synchronous timing is added to each component, making the model loosely timed. See Chapter 8. 5. Temporal decoupling is added to the Or1ksim ISS, UART and terminal, to improve the performance of the model. See Chapter 9. 6. Interrupt modeling is added to the UART and the Or1ksim ISS, allowing the model to run Linux. See Chapter 10. 7. A second thread, modeling the JTAG interface to the processor is added to the wrapper. This demonstrates how the ISS wrapper can be multi-threaded, while the underlying OpenRISC 1000 ISS remains single threaded. This interface allows the model to be driven from a debugger such as GDB. See Chapter 11. Simple applications, compiled with the OpenRISC 1000 tool chain are used throughout to exercise the model components. The final model is demonstrated booting a Linux 2.6 kernel. 3.1. The Example Designs The example, a simple SoC, is based on the Or1ksim ISS for the OpenRISC 1000 architecture. The OpenRISC 1000 architecture is a conventional 32-bit DSP/RISC design, with optional caches and MMU. Or1ksim is an interpreting ISS written in C, which in its standard configuration models main memory and a number of peripherals as well as the CPU itself. A key feature of Or1ksim is that it is single threaded and the code is generally not re-entrant. Much of the challenge in wrapping such an ISS is ensuring consistency within a multi- threaded SystemC environment. Information on obtaining and setting up the open source Or1ksim simulator and its tool chain are given in Embecosm Application Note 2. The OpenCores OpenRISC 1000 Simulator and Tool Chain: Installation Guide. [4]. 8 Copyright © 2008, 2010 Embecosm Limited For Chapter 4 through Chapter 9 the Or1ksim ISS is configured to model only the CPU and main memory, with example peripherals modeled as separate SystemC modules. For Chapter 10, the ISS is configured to model the data and instruction MMUs and a programmable interrupt controller (PIC). This allows the ISS to support interrupt driven peripherals and hence Linux In Chapter 11 a second thread is introduced to the wrapper to model the JTAG debugging interface. This allows the model to be run under the control of a debugger such as GDB 3.1.1. Or1ksim ISS TLM 2.0 Wrapper with Logger In Chapter 4 the TLM 2.0 wrapper for the Or1ksim ISS is developed. In Chapter 5 the wrapped ISS is tested by connection to a simple TLM 2.0 logger module. This module records transactions sent to it on standard output as shown in Figure 3.1. Or1ksim CPU Memory Data Bus Logger Figure 3.1. Testing the TLM 2.0 wrapper for Or1ksim. 3.1.2. Simple SoC Design To build a simple SoC the Or1ksim ISS CPU/memory subsystem is connected to a UART modeled in SystemC using TLM 2.0. The test bench for the system is a terminal, also modeled in SystemC using TLM 2.0 as shown in Figure 3.2. The model is built up in stages starting with the ISS wrapper module developed in Chapter 4. In Chapter 6 and Chapter 7 models of the UART and terminal are added to create an untimed model. Synchronous timing to create a loosely timed model is added in Chapter 8 and temporal decoupling to improve performance is added in Chapter 9. . Or1ksim CPU Memory Tx Data Bus xterm UART Rx Figure 3.2. Simple SoC based on the OpenRISC 1000 Or1ksim. 3.1.3. SoC with Interrupt Support To run Linux (see Chapter 10), the example must be extended to support interrupt driver I/O. It also needs memory management and other peripheral functions. This is provided internally to the Or1ksim ISS. This design is shown in Figure 3.3. 9 Copyright © 2008, 2010 Embecosm Limited Or1ksim Debug Unit Tx Flash IMMU xterm UART IRQ Rx CPU SRAM DMMU RAM PIC TICK Data Bus Figure 3.3. Simple SoC based on the OpenRISC 1000 Or1ksim with interrupts and MMU enabled. 3.1.4. SoC with Debugger Support A software debugger typically interacts with a processor via an independent debugging interface. For the OpenRISC 1000 the debug interface uses IEEE 1149.1 JTAG. To allow the debugger to connect to the model we must model this interface. This design is shown in Figure 3.4. Or1ksim Debug JTAG GNU Debugger Debug Unit Interface Flash IMMU CPU SRAM xterm Tx IRQ DMMU RAM Rx UART PIC TICK Data Bus Figure 3.4. Simple SoC based on the OpenRISC 1000 Or1ksim with separate JTAG interface. 3.2. Example Code 3.2.1. Source Code for Example Models and Programs The code of the distribution is organized as follows. configure The main configuration script. linux.cfg An Or1ksim configuration file for use when running Linux. progs-or32 A collection of OpenRISC 1000 programs which run on the models created. Binaries are provided as well as source, but to recompile the example programs requires the OpenRISC 1000 tool chain. See Embecosm Application Note 2. The OpenCores OpenRISC 1000 Simulator and Tool Chain: Installation Guide. [4] for more information on building the OpenRISC 1000 tool chain. simple.cfg An Or1ksim configuration file for use when running simple examples. sysc-models The SystemC code for the various models. A separate directory is provided for each model. In each case the models build on previous models using the C++ class inheritance mechanism. 10 Copyright © 2008, 2010 Embecosm Limited logger The simplest model, providing a base class wrapper to Or1ksim and connecting to a simple logger class, which can check the correct behavior of the bus. See Chapter 4 and Chapter 5. simple-soc The simplest complete SoC model, adding a UART and terminal emulator to the Or1ksim model. The base Or1ksim wrapper class from logger is extended to allow other threads to execute. See Chapter 6 and Chapter 7. sync-soc This extends the SoC wrapper from simple-soc to add synchronized timing. Derived classes of the UART and terminal emulator also add synchronized timing. See Chapter 8. decoup-soc Decoupled timing is added to the SoC wrapper from sync-soc. A decoupled version of the UART is also implemented. See Chapter 9. intr-soc This is a version of the SoC wrapper from decoup- soc which adds interrupt handling. A version of the UART which supports interrupt based operation is also implemented. This allows Linux to be supported. See Chapter 10. jtag-soc The SoC wrapper from intr-soc is extended with an additional thread implementing a JTAG interface. This allows code running on the model to be debugged using a tool such as GDB. See Chapter 11. uml UML design information for all the models, created with BoUML is provided in this directory. Various other files and directories are included. These form part of the standard GNU autotools infrastructure. 3.2.2. Code Documentation The code throughout is documented with Doxygen (see www.doxygen.org). This provides a description of the code, generated automatically from the source. The generated HTML can be found in the doc/html sub-directory of both the SystemC model directory and the OpenRISC 1000 program directory. 3.2.3. SystemC Model Coding Conventions All the examples in this application note separate the definition of a class (i.e. what it does) in a .h file, from the implementation (i.e. how it does it) in a .cpp file. Class X is defined in file X.h and implemented in X.cpp. The examples use the convention that classes and other type names start with an Upper Case letter (e.g. Or1ksimSC), variables and functions start with a lower case letter (e.g. dataBus) and defined or enumerated constants are all in UPPER CASE (e.g. #define BAUD_RATE 9600). All SystemC module classes end with the characters 'SC'. 3.2.4. Derived classes C++ provides the hierarchical class mechanism, where derived classes inherit (some) of the functions and variables of their base class. This feature is heavily used within SystemC—for example all module classes are derived classes of the SystemC base class, sc_module. 11 Copyright © 2008, 2010 Embecosm Limited The SystemC models in each section of this application note are built using derived classes of the models from previous sections. Those functions and variables which other classes will use are declared as public. For SystemC modules this usually means the constructor and any SystemC ports or sockets. Occasionally there are some utility functions which are also made public (see for example Or1ksimExt::isLittleEndian in Section 6.3)1. Variables and functions in classes that are not for use by other classes, but are required in derived classes are declared as protected (i.e. visible to derived classes). The remaining functions and variables, which are for use only by the current class, are declared private (visible only to this class). This avoids any unplanned reuse by derived classes. Some of the functions will be reimplemented in later derived classes. Such functions are also declared virtual. In summary public functions and variables may be used by any other class, protected functions and variables may be used only by this class and any derived classes and private functions and variables may be used only by this class. virtual functions may be reimplemented in derived classes. 3.2.5. Configuration The entire example system is now built using the GNU; autotools. This provides for flexibility in configuration and building of the system. Note This is a major change since issue 1 of this application note. Full details of how to configure and build the models are in Appendix A. 1 Object oriented purists prefer to expose only class functions as the public interface, so hiding all state implementation from external view. There is considerable merit in this, but the common SystemC convention is to expose actual ports or sockets, rather than accessor functions for those objects. This application note follows this practice. 12 Copyright © 2008, 2010 Embecosm Limited Chapter 4. Wrapping the ISS The conversion of an existing ISS to a SystemC module with TLM 2.0 sockets involves several steps. • Modify the existing ISS (in this example Or1ksim written in C) so it behaves in a manner suitable for wrapping (see Section 4.1). • Define a SystemC module for the wrapper (see Section 4.2) and provide its implementation (see Section 4.3). • Test the wrapper with a simple logger module attached to the TLM 2.0 socket and a suitable test application running as embedded code on the ISS (see Chapter 5). The code for the Or1ksim wrapper module (Or1ksimSC.cpp and Or1ksimSC.h) may be found in the sysc-models/logger directory of the distribution. 4.1. Modifying the Or1ksim ISS for TLM 2.0 Most ISS need some modification before they can be incorporated into a TLM 2.0 framework. Like many ISS, Or1ksim is designed as a standalone program. The options are: 1. Keep the ISS as a standalone program, but modify it to call out to a SystemC model of the peripherals as required. 2. Modify the ISS to be a library with a set of public interfaces that can be part of a larger system. Given the choice, option 2 is more flexible, making the ISS widely reusable in other environments. It is the approach adopted in this application note. It is not intended that the reader should have to understand the internal workings of Or1ksim. All the changes described in this application note form part of Or1ksim 0.4.0. With the exception of the examples in Chapter 11, the changes described in this application note also form part of Or1ksim 0.3.0. Details of obtaining Or1ksim are provided in Appendix A. 4.1.1. Converting Or1ksim to a Library The Or1ksim main function first initializes the ISS, then sits in a loop executing instructions. This main function is replaced by a series of functions which form the interface to the library. The interface functions needed are: • int or1ksim_init (const char *config_file, const char *image_file, void *class_ptr, int (*upr) (void *class_ptr, unsigned long int addr, unsigned char mask[], unsigned char rdata[], int data_len), int (*upw) (void *class_ptr, unsigned long int addr, unsigned char mask[], unsigned char wdata[], int data_len)); 13 Copyright © 2008, 2010 Embecosm Limited or1ksim_init initializes the simulator. For Or1ksim, configuration data is read from a file, which is passed as the first argument, config_file. The program image is passed as a second argument, image_file. Or1ksim also needs to be able to call up to the SystemC model of which it is part—to read and write from the peripheral address space. These are provided as the fourth and fifth arguments, upr and upw. More explanation of the upcall mechanism can be found in Section 4.2.6. Function calls between C and C++ can be awkward. The upcall functions form part of the SystemC module object, but are written as static functions with C linkage. To enable these functions to invoke functions in the SystemC module, they are passed a pointer to the module class instance to use as a handle. This pointer forms the third argument, class_ptr. • int or1ksim_run( double duration ); or1ksim_run runs the simulator for the specified time in seconds. These functions are a standard part of the Or1ksim 0.3.0 and Or1ksim 0.4.0 libraries. 4.1.2. Additional Functionality for Or1ksim The standard Or1ksim ISS incorporates the functionality of several common peripherals. The objective of this application note is to demonstrate the ISS driving external peripherals modeled in SystemC using TLM 2.0 interfaces. Or1ksim peripherals are configured in a textual configuration file, with a section (introduced by the keyword section) for each device attached. This configuration file specifies the memory mapped addresses of the peripheral. Any reads or writes to those addresses will be directed to the code of the peripheral within Or1ksim. Or1ksim is extended with a new class of peripheral, generic, which specifies an external peripheral. The specification in the configuration file specifies the memory mapped address range covered and whether byte, half word or full word access are enabled. Multiple generic sections may be defined (for different address ranges) in the configuration file. Code is added to Or1ksim, so that any read or write to a generic peripheral is redirected back to the wrapper code via the upcalls specified as arguments to or1ksim_init (see Section 4.1.1 and Section 4.2.6). 4.2. Or1ksim Wrapper Module Class Definition The class definition for the Or1ksim ISS wrapper module may be found in the file sysc_models/ logger/Or1ksimSC.h. 4.2.1. Included Headers The Or1ksim SystemC wrapper module class, Or1ksimSC, is defined in the file Or1ksimSC.h. It will provide a single initiator socket, for data access, dataBus. No instruction accesses are planned, so modeling an external instruction bus is unnecessary. The module includes the tlm.h header, which defines the core TLM 2.0 interface and the required convenience wrapper header—in this case for a simple initiator socket. The POSIX stdint.h header is also included, since the definitions and code will make use of the fixed width native types defined there. 14 Copyright © 2008, 2010 Embecosm Limited #include <stdint.h> #include "tlm.h" #include "tlm_utils/simple_initiator_socket.h" #include "or1ksim.h" Note There is no need to include the standard systemc header, since this is included automatically by tlm.h. 4.2.2. Module Declaration The module is declared as a standard SystemC module, i.e. as a derived class of sc_core::sc_module. class Or1ksimSC : public sc_core::sc_module { Note SystemC provides a macro, so that a module can be defined by: SC_MODULE( Or1ksimSC ) However this is equivalent (IEEE 1666-2005 section 5.2.5) to the C++ derived class declaration class Or1ksimSC : public sc_core::sc_module { public: By using SC_MODULE all functions and variables will be visible to all other classes (public) unless there is a subsequent protected: or private: declaration. The examples provided with SystemC and TLM 2.0 all use explicit declarations of classes derived from sc_module rather than the SC_MODULE macro. This application note uses the same approach. 4.2.3. Constructor and Destructor Or1ksimSC needs a custom constructor, which can be passed the Or1ksim ISS configuration and image files. It will call the or1ksim_init function within the Or1ksim library (see Section 4.1.1) to initialize the ISS. Or1ksimSC( sc_core::sc_module_name name, const char *configFile, const char *imageFile ); 15 Copyright © 2008, 2010 Embecosm Limited The default destructor is sufficient here. The module has no tidying up to do on termination. 4.2.4. Public Interface The only public interface is the TLM 2.0 simple initiator convenience socket, dataBus. The TLM 2.0 convenience sockets are templated with • the class of which any callbacks are members; • a bus width (default BUSWIDTH, 32); and • a protocol type (default the TLM 2.0 base protocol types). For this case study, the default bus width and protocol are appropriate and need not be specified. There is no default class for the template, so Or1ksimSC is used. A class must be specified, even where (as in this case for a simple blocking initiator) no callbacks are actually required. tlm_utils::simple_initiator_socket<Or1ksimSC> dataBus; 4.2.5. Threads The module has a single thread, which executes the instructions of the ISS. The run function implements this: void run(); The thread is not part of the public interface, but will but will be reused and reimplemented in derived classes later in the application note, so it is declared protected and virtual. 4.2.6. Upcalls The Or1ksim ISS makes requests to read and write peripherals via the upcalls passed as arguments to or1ksim_init (see Section 4.1.1). The Or1ksim ISS is implemented in C, which cannot easily call C++ class instance functions. The solution is to declare two static member functions which can be called from C. The call to or1ksim_init also received the address of the actual C++ class instance (cast to void *). This pointer is passed back with the upcall, so the static function can call the corresponding instance function. A total of 4 functions are needed, one static and one instance each for read and write. The static functions use the native C/C++ types (unsigned long int), but convert to defined fixed width types for the instance functions. The native SystemC 64-bit unsigned type is used for the address (which is always 64 bits in TLM 2.0 function calls) and the POSIX 32-bit unsigned data type is used for the byte enable mask and data. These upcall functions are not changed throughout this application note, so are declared private. 16 Copyright © 2008, 2010 Embecosm Limited static int staticReadUpcall (void *instancePtr, unsigned long int addr, unsigned char mask[], unsigned char rdata[], int dataLen); static int staticWriteUpcall (void *instancePtr, unsigned long int addr, unsigned char mask[], unsigned char wdata[], int dataLen); int readUpcall (unsigned long int addr, unsigned char mask[], unsigned char rdata[], int dataLen); int writeUpcall (unsigned long int addr, unsigned char mask[], unsigned char wdata[], int dataLen); Caution ! It might seem logical to use the SystemC limited precision types, rather than the POSIX types. However the SystemC types are not native C++ types, so will not cast as expected. The transport mechanism is common to both, so provided in a utility function, doTrans. This function will be used and re-implemented in derived classes, so is declared protected and virtual. When invoked, each upcall will need to populate a new payload. Since this is something local in both scope and extent to the upcall and its lifetime, the instinct is to declare it as an automatic variable within each upcall. However the TLM 2.0 generic payload has a large underlying structure and complex initialization, so such a local declaration carries a significant performance penalty if it is constructed each time the upcall is used. Since only one upcall is ever in use at any one time, we can declare the payload as a class instance variable. Since it is only used by the upcalls, it can be private to this class. tlm::tlm_generic_payload trans; Note The performance overhead in instantiating a generic payload is not mentioned in the TLM 2.0 LRM. I am indebted to Robert Günzel for bringing the issue to my attention. 4.3. Or1ksim Wrapper Module Class Implementation The class implementation for Or1ksimSC may be found found in sysc-modules/logger/ Or1ksimSC.cpp in the distribution. 17 Copyright © 2008, 2010 Embecosm Limited 4.3.1. Headers and Macros All the definitions required are obtained from the definition file: #include "Or1ksimSC.h" The implementation of a C++ class that is a SystemC module with SystemC threads (SC_THREAD), methods (SC_METHOD) or clocked threads (SC_CTHREAD) requires a number of definitions for that class to be set up using the SC_HAS_PROCESS macro. SC_HAS_PROCESS( Or1ksimSC ); Caution ! The SC_HAS_PROCESS macro is a common cause of confusion with new users to SystemC. It doesn't appear in the user guide and tutorial examples. The reason is that those examples use the SC_CTOR macro to define the constructor for the class, which provides the same definitions as the SC_HAS_PROCESS macro. The SC_CTOR macro can only be used where the constructor's implementation is given within the class definition. As explained in Section 3.2.3, this application note follows the standard C++ practice of separating the class definition from its implementation, with the constructor implemented separately from the class definition. In cases such as this, where the constructor implementation is separate from the definition, SystemC requires that the SC_HAS_PROCESS macro is used before the code of any class functions. The macro is only required if the constructor uses SC_METHOD, SC_THREAD or SC_CTHREAD to associate a process with the module class. 4.3.2. Constructor The constructor passes the name to the constructors of its base class (sc_module) and its simple initiator socket (dataBus), then calls the or1ksim_init function in the Or1ksim library to initialize the ISS. The member function, run is associated with the class as a SystemC thread, using the SC_THREAD macro. It will be called automatically by the SystemC kernel after elaboration (i.e SystemC initialization). Or1ksimSC::Or1ksimSC ( sc_core::sc_module_name name, const char *configFile, const char *imageFile ) : sc_module( name ), dataIni( "data_initiator" ) { or1ksim_init( configFile, imageFile, this, staticReadUpcall, staticWriteUpcall ); SC_THREAD( run ); // Thread to run the ISS } /* Or1ksimSC() */ 18 Copyright © 2008, 2010 Embecosm Limited 4.3.3. Thread The main thread, run, invokes the Or1ksim ISS to run for ever (by passing a negative time argument). The ISS will use the upcalls (see Section 4.2.6) to request reads from and writes to the peripheral address space. The thread is called automatically when the SystemC kernel has completed elaboration (i.e. is initialized). void Or1ksimSC::run() { scLastUpTime = sc_core::sc_time_stamp(); or1kLastUpTime = or1ksim_time(); (void)or1ksim_run( -1.0 ); } // Or1ksimSC() 4.3.4. Upcalls Two functions are declared as static member functions to implement the upcalls from the Or1ksim library (see Section 4.2.6 for an explanation of why these functions are static). The static functions receive the pointer to the Or1ksimSC instance which originally started the Or1ksim ISS (provided as an argument to or1ksim_init described in Section 4.3.3). This allows each static function to call the instance function which implements the upcall, as shown here with staticReadUpcall: int Or1ksimSC::staticReadUpcall (void *instancePtr, unsigned long int addr, unsigned char mask[], unsigned char rdata[], int dataLen) { Or1ksimSC *classPtr = (Or1ksimSC *) instancePtr; return classPtr->readUpcall (addr, mask, rdata, dataLen); } // staticReadUpcall() The instancePtr argument allows identification of the particular instance of the class which called or1ksim_run and hence to which the upcall is directed. The remaining arguments are passed to the instance method unchanged. Caution ! It might be thought that providing a direct upcall to the C++ upcall functions of the class would be more efficient, using the C++ member reference operator (::*). However the linkage to a member is much more complex (to cope with inheritance and overloading). Lack of standardization in the C++ Application Binary Interface (ABI) means that such linkage between C and C++ will not necessarily work. Linkage to static functions is much simpler and usually works between C and C+ +. So the approach used here is more reliable. 19 Copyright © 2008, 2010 Embecosm Limited The upcalls from the ISS generate the transactional activity. These functions set up the payload, execute the transaction (i.e exchange the payload and result with the target) and return the result to the ISS. The example here is coded in a very simple fashion, in the knowledge that the requests to read are always four bytes long (the OpenRISC 1000 has a simple 32 bit bus), possibly with some bytes masked out for byte and half-word reads. This matches the default BUSWIDTH of the simple initiator socket. As noted in Section 4.2.6, the payload is declared as a class instance variable, rather than locally here for performance reasons. This has the added benefit that it will also work should we ever convert the model to using a non-blocking socket, where the lifetime of the payload would need to be longer than the lifetime of the upcall. TLM 2.0 requires that the payload, data and mask fields all remain valid for the duration of the complete transaction. 4.3.5. Blocking Transport Once the payload fields are set up, the doTrans function (which is used for both read and write) is called to transport the payload to the target and return the result. The transport function requires a time to be supplied, even when timing is not being used (as in this case). This must be time variable, not a constant, since the target can update the value. A dummy variable is declared with zero time and passed to the blocking transport function of the socket with the payload. sc_core::sc_time dummyDelay = sc_core::SC_ZERO_TIME; dataBus->b_transport( trans, dummyDelay ); This implementation is sufficient for modeling just the Or1ksim ISS in SystemC. However at no time does the thread execute a SystemC wait call. In the absence of any such yield, no other thread would be able to execute. This will be remedied in Chapter 6 when other threads are added to model peripherals. 20 Copyright © 2008, 2010 Embecosm Limited Chapter 5. Testing the Or1ksim ISS TLM 2.0 Wrapper The test configuration was shown earlier in Figure 3.1. For this a simple logger is needed, which must implement a TLM 2.0 simple target socket. In addition, a simple embedded application is needed to run on the Or1ksim ISS, which will make reads and writes to peripheral address space, which can be detected by the logger. All the behavior is in the callback function—there are no SystemC threads. This means the logger will be suitable for testing the Or1ksimSC wrapper module, even though its thread never yields (see Section 4.3.5). The code for the logger module (LoggerSC.cpp and LoggerSC.h) and the main program (loggerMainSC.cpp may be found with the Or1ksim wrapper code in the sysc-models/logger directory of the distribution. 5.1. Overall Design of the Test Program The key aspects of the overall program are captured in a UML class diagram and a UML sequence diagram, showing how a read transaction is processed. 5.1.1. Class Structure The overall class diagram for the design is shown in Figure 5.1. The Or1ksim wrapper class creates its own TLM 2.0 convenience initiator port, with which a TLM 2.0 generic payload will be associated to carry traffic. Conversely the logger class creates its own TLM 2.0 convenience target port through which it will receive the associated payload. The class structure of the underlying SystemC TLM 2.0 environment connecting initiator and target ports is not shown. Or1ksimSC,32 Or1ksimSC simple_initiator_socket dataBus 1 or1ksim LoggerSC,32 simple_target_socket LoggerSC loggerSocket 1 tlm_generic_payload trans trans 1 1 Figure 5.1. Class diagram for the Or1ksim test model. 5.1.2. Behavioral Diagrams A sequence diagram, illustrating the handling of a read transaction for the design is shown in Figure 5.2. The Or1ksim wrapper class invokes the underlying Or1ksim ISS through its run function. The run function executes without further interruption. Whenever it needs to read or write via the external bus, it uses the staticReadUpcall or staticWriteUpcall function. This in turn invokes the readUpcall function for the wrapper instance. The various TLM 2.0 generic payload functions are used to set up the payload, before the payload is passed to the initiator port using its b_transport function (for simplicity the call 21 Copyright © 2008, 2010 Embecosm Limited to do_trans is omitted from the diagram). The packet is passed internally to the connected target port, where it invokes the handler function (loggerReadWrite) to handle the payload. The payload is modified as appropriate before being returned to the initiator. dataBus: trans: loggerSocket: logger: iss:Or1ksimSC tlm_generic_payload LoggerSC :or1ksim simple_initiator_socket simple_target_socket run() staticReadUpcall() readUpcall() setRead() Further payload access calls b_transport() loggerReadWrite() getCommand() Further payload access calls Figure 5.2. Sequence diagram for a read transaction with the Or1ksim test model. Note All the actions in this diagram are synchronous. There is a single thread of control, which flows from the wrapper module to the logger module as a transaction is processed. 5.2. Definition of the TLM 2.0 Logger Module The code for the logger module definition may be found in sysc-models/logger/LoggerSC.h in the distribution. 5.2.1. Include Files The logger is based on the TLM 2.0 convenience simple target socket, so needs the appropriate header, in addition to the standard TLM 2.0 header: #include "tlm.h" #include "tlm_utils/simple_target_socket.h" 5.2.2. Module Declaration and Constructor The class is a standard SystemC module: class LoggerSC : public sc_core::sc_module A custom constructor is needed, which will be used to register the callback function for the simple target convenience socket blocking transport. LoggerSC( sc_core::sc_module_name name ); 22 Copyright © 2008, 2010 Embecosm Limited 5.2.3. Public Interface The public interface is the single simple target convenience socket. tlm_utils::simple_target_socket<LoggerSC> loggerPort; 5.2.4. Blocking Transport Blocking transport is via a callback function: void loggerReadWrite( tlm::tlm_generic_payload &payload, sc_core::sc_time &delay ); All the behavior of the module is captured in this callback function. There are no SystemC threads required. 5.3. Implementation of the TLM 2.0 Logger Module The code for the logger module implementation may be found in sysc-models/logger/ LoggerSC.cpp in the distribution. 5.3.1. Included Headers The logger will be doing a certain amount of stream IO, so includes the C++ headers that define stream manipulation functions. The POSIX standard integer types are also included. #include <iostream> #include <iomanip> #include <stdint.h> #include "LoggerSC.h" 5.3.2. Constructor The constructor passes its argument (the module) name to the base class sc_module constructor. The body of the function then registers the loggerReadWrite function as the callback for blocking transport to this convenience socket. This means that any initiator which requests blocking transport (by calling the initiator socket's b_transport function) will invoke this callback function in the target. LoggerSC::LoggerSC( sc_core::sc_module_name name ) : sc_module( name ) { loggerPort.register_b_transport( this, &LoggerSC::loggerReadWrite ); } // Or1ksimSC() 5.3.3. Blocking Transport Callback The callback function, loggerReadWrite records the key information regarding any transaction it receives. The payload is a TLM 2.0 generic payload, with appropriate access functions. In this simple implementation, a length of 4 bytes is assumed for the data in the payload. To get at the data and byte enable mask, the pointers to unsigned char are cast to pointers to the POSIX fixed width type, uint32_t, as was used with Or1ksimSC. Endianness issues due 23 Copyright © 2008, 2010 Embecosm Limited to the byte pointers not being word aligned are not an issue, because the Or1ksimSC module also declared them as uint32_t. void LoggerSC::loggerReadWrite( tlm::tlm_generic_payload &payload, sc_core::sc_time &delay ) { // Break out the address, mask and data pointer. tlm::tlm_command comm = payload.get_command(); sc_dt::uint64 addr = payload.get_address(); unsigned char *maskPtr = payload.get_byte_enable_ptr(); unsigned char *dataPtr = payload.get_data_ptr(); // Record the payload fields (data only if it's a write) const char *commStr; switch( comm ) { case tlm::TLM_READ_COMMAND: commStr = "Read"; break; case tlm::TLM_WRITE_COMMAND: commStr = "Write"; break; case tlm::TLM_IGNORE_COMMAND: commStr = "Ignore"; break; } std::cout << "Logging" << std::endl; std::cout << " Command: " << commStr << std::endl; std::cout << " Address: 0x" << std::setw( 8 ) << std::setfill( '0' ) <<std::hex << (uint64_t)addr << std::endl; std::cout << " Byte enables: 0x" << std::setw( 8 ) << std::setfill( '0' ) <<std::hex << *((uint32_t *)maskPtr) << std::endl; if( tlm::TLM_WRITE_COMMAND == comm ) { std::cout << " Data: 0x" << std::setw( 8 ) << std::setfill( '0' ) <<std::hex << *((uint32_t *)dataPtr) << std::endl; } std::cout << std::endl; payload.set_response_status( tlm::TLM_OK_RESPONSE ); // Always OK } // loggerReadWrite() 5.4. The Model Main Program The logger module and the Or1ksim wrapper module must be connected in the main program (sc_main since this is SystemC), and the simulation invoked. The code for the main program may be found in sysc-models/logger/loggerMainSC.cpp in the distribution. 5.4.1. Included Headers The program includes the C++ iostream header, main TLM 2.0 header and the header of the two modules which will be used: 24 Copyright © 2008, 2010 Embecosm Limited #include <iostream> #include "tlm.h" #include "Or1ksimSC.h" #include "LoggerSC.h" The two iostream entities used are brought into the local namespace. using std::cerr; using std::endl; 5.4.2. Argument Processing The program takes two arguments, an Or1ksim configuration file (described further in Section 5.6) and a binary image to execute on the Or1ksim ISS (see Section 5.5). int sc_main( int argc, char *argv[] ) { if( argc != 3 ) { cerr << "Usage: TestSC <config_file> <image_file>" << endl; exit( 1 ); } 5.4.3. Module Instantiation Instances of the Or1ksim ISS and the logger are created, the ISS being passed the two program arguments for its initialization. Or1ksimSC iss( "or1ksim", argv[1], argv[2] ); LoggerSC logger( "logger" ); 5.4.4. Connecting the Modules The target socket of the logger (loggerPort) is connected by passing it as argument to the initiator socket of the ISS (dataBus). The C++ function application operator, (), is overloaded for initiator sockets to provide this binding function. iss.dataBus( logger.loggerPort ); 5.4.5. Model Execution Once the model is instantiated, simulation is invoked to run forever. sc_core::sc_start(); 25 Copyright © 2008, 2010 Embecosm Limited 5.5. Test Program to Run on the Or1ksim The test program in progs-or32/logger-test.c defines a memory mapped volatile data structure and then writes to and reads from each element of that structure. The source code for the logger test program may be found in progs-or32/logger-test.c in the distribution. It uses the utility functions (progs-or32/utils.c and progs-or32/utils.h) and the bootloader (progs-or32/start.s). 5.5.1. The Utility Functions The test program uses some simple utility functions which can write characters (simputc), string (simputs) and hexadecimal numbers (simputh). Its header is included: #include "utils.h" The utilities' implementation can be found in utils.c. 5.5.2. Memory Mapped Data Structure The memory mapped address is defined in the configuration of Or1ksim (see Section 5.6) to be 0x90000000. This is set as a defined constant in the test program. #define BASEADDR 0x90000000 The memory mapped structure consists of a byte, half word (16 bits) and full word (32 bits), all declared as volatile within the struct. These are all declared with the C types, which for the OpenRISC 1000 tool chain are known to correspond to these sizes. struct testdev { volatile unsigned char byte; volatile unsigned short int halfword; volatile unsigned long int fullword; }; The main program declares a pointer to this struct at the BASEADDR, along with 3 variables to hold the results of the various sized results when reading. main() { struct testdev *dev = (struct testdev *)BASEADDR; unsigned char byteRes; unsigned short int halfwordRes; unsigned long int fullwordRes; 5.5.3. Checking Write Access The details of each write are logged and the value then written. (In the absence of a printf, the logging is necessarily cumbersome). 26 Copyright © 2008, 2010 Embecosm Limited simputs( "Writing byte 0xa5 to address 0x" ); simputh( (unsigned long int)(&(dev->byte)) ); simputs( "\n" ); dev->byte = 0xa5; simputs( "Writing half word 0xbeef to address 0x" ); simputh( (unsigned long int)(&(dev->halfword)) ); simputs( "\n" ); dev->halfword = 0xbeef; simputs( "Writing full word 0xdeadbeef to address 0x" ); simputh( (unsigned long int)(&(dev->fullword)) ); simputs( "\n" ); dev->fullword = 0xdeadbeef; 5.5.4. Checking Read Access The values are then read back. No results are expected (the logger does not set any values), but this should check the process behaves as expected. byteRes = dev->byte; simputs( "Read 0x" ); simputh( byteRes ); simputs( " from address 0x" ); simputh( (unsigned long int)(&(dev->byte)) ); simputs( "\n" ); halfwordRes = dev->halfword; simputs( "Read 0x" ); simputh( halfwordRes ); simputs( " from address 0x" ); simputh( (unsigned long int)(&(dev->halfword)) ); simputs( "\n" ); fullwordRes = dev->fullword; simputs( "Read 0x" ); simputh( fullwordRes ); simputs( " from address 0x" ); simputh( (unsigned long int)(&(dev->fullword)) ); simputs( "\n" ); At the end of the program, the utility simexit is used. This not only terminates the program, but will also exit the simulation. 5.5.5. Program Compilation The program is compiled as part of the overall make and will be found in the progs-or32 sub- directory of the main build directory. A custom linker script ensures the program is loaded with its bootloader at the correct address, with its entry point at the OpenRISC 1000 reset vector (0x100). 27 Copyright © 2008, 2010 Embecosm Limited 5.6. Running the Test 5.6.1. Compiling the SystemC Model The complete program is compiled from the top level make file. Both a standalone program (logger) and a libtool compliant library (liblogger.la) are created. The library provides a convenient mechanism for reusing the code from this model, when creating subsequent models which use derived classes. The SystemC modules are all compiled with SC_INCLUDE_DYNAMIC_PROCESSES defined when using TLM 2.0. This is a requirement for using the TLM 2.0 library. The final executable is linked against the SystemC library. 5.6.2. Configuring the OpenRISC 1000 Or1ksim ISS The Or1ksim ISS is configured using a textual configuration file, described in more detail in Embecosm Application Note 2. The OpenCores OpenRISC 1000 Simulator and Tool Chain: Installation Guide. [4]. For the modified Or1ksim ISS, generic peripherals can be added (see Section 4.1.2), which will cause code to call out via the upcall mechanism to the Or1ksim SystemC wrapper module (see Section 4.2.6). The Or1ksim configuration file for this example is in simple.cfg. It disables all the standard peripherals and specifies one block of memory from address 0x0. It adds a generic peripheral allowing byte, half word and full word access to addresses mapped from 0x90000000 to 0x90000007, with the following configuration file entry section generic enabled = 1 baseaddr = 0x90000000 size = 0x8 name = "External UART" byte_enabled = 1 hw_enabled = 1 word_enabled = 1 end 5.6.3. Running the Compiled Model The compiled program can be executed by passing in as arguments the Or1ksim configuration file and the OpenRISC 1000 binary. The result is shown in Figure 5.3. 28 Copyright © 2008, 2010 Embecosm Limited $ ./sysc-models/logger/logger ../simple.cfg progs-or32/logger-test SystemC 2.2.0 --- May 16 2008 10:30:46 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED ... <Or1ksim initialization messages> Writing byte 0xa5 to address 0x090000000 Logging Command: Write Address: 0x90000000 Byte enables: 0x000000ff Data: 0x003f54a5 Writing half word 0xbeef to address 0x090000002 Logging Command: Write Address: 0x90000000 Byte enables: 0xffff0000 Data: 0xefbe8fc4 ... <More test program output> Read half word 0x0FFFF from address 0x090000002 Logging Command: Read Address: 0x90000004 Byte enables: 0xffffffff Read full word 0x028372F09 from address 0x090000004 exit(0) @reset : cycles 0, insn #0 @exit : cycles 33297, insn #16581 diff : cycles 33297, insn #16581 $ Figure 5.3. Output from the logger test of the Or1ksim wrapper module. Each access from the application program generates the expected transactional access. All accesses are 32 bits wide, but for byte and half-word access the relevant bytes are masked off. The reads return meaningless values (the logger was not designed to package a return value), but in each case the value returned fits in the size requested as expected. Note The Or1ksim ISS can be configured to model little-endian architectures. The TLM 2.0 payloads are always packed with data using the endianness of the model. If the exercise were repeated with a little-endian version of Or1ksim the addresses of the access would be unchanged (they are word aligned), but the byte enable masks for the byte and half word accesses would be inverted. 29 Copyright © 2008, 2010 Embecosm Limited Chapter 6. Modeling Peripherals This example uses a single peripheral, a UART. The UART model is based on National Semiconductor 16450 design. The Or1ksim ISS wrapper must be extended to work with this UART. The code for the UART module (UartSC.cpp and UartSC.h) may be found with the extended Or1ksim wrapper code (Or1ksimExtSC.cpp and Or1ksimExtSC.h) in the sysc-models/simple- soc directory of the distribution. 6.1. Details of the 16450 UART The 16450 UART is a very long established industry component. Data written a byte at a time into the transmit buffer is converted to serial pulses on the output (Tx) pin. Serial pulses on the input (Rx) pin are recognized and converted to byte values, which can be read from the receive buffer. Typically Rx and Tx are connected to a terminal and keyboard which can generate and recognize the pulses of data. The UART can also generate additional signals for terminals and keyboards to provide physical flow control, but that is beyond the scope of this model. The key interfaces are shown in Figure 6.1. A-bus a (3-bit) Tx Rx D-bus (8-bit) 16450 UART Interrupt Clk Figure 6.1. 16450 UART: Key interfaces. The 16450 UART specifies a set of registers which control the UART behavior. On the Tx/Rx side, this includes setting the board rate and the pattern of stop, start and data bits. On the CPU side this includes configuring interrupt behavior (if any) and setting flags to show the status of transmit and receive buffers. The registers are shown in Table 6.1. 30 Copyright © 2008, 2010 Embecosm Limited Address Register R/W Description 0 RXBUF R When the DLAB bit is 0 (see register LCR, this is the buffer for read data. TXBUF W When the DLAB bit is 0 (see register LCR, this is the buffer for data to be written. DLL R/W When the DLAB bit is 1 (see register LCR, this is the low byte of the divisor latch (which controls UART performance) 1 IER R/W The interrupt enable register. The lower 4 bits control which events generate an interrupt. DLH R/W When the DLAB bit is 1 (see register LCR, this is the high byte of the divisor latch (which controls UART performance) 2 IIR R Interrupt identification register. Bit 0 indicates if an interrupt is pending, bits 1-2 the reason for the interrupt. 3 LCR R/W Line control register. Various bits controlling the behavior of the UART. Of these, DLAB, bit 7, the divisor latch access bit is important, because it controls the behavior of registers 0 (RXBUF/TXBUF/DLL) and 1 (IER/DLH). 4 MCR W Modem control register. Bits 0-4 control the behavior of the modem. 5 LSR R Line status register. Bits 0-6 report the status of the UART. Of these, DR, bit 0, receiver data ready is important, indicating there is valid data in RXBUF. 6 MSR R Modem Status Register. Bits reporting the state of the modem. 7 SCR R/W Scratch register. Not used by the UART, but may be used by the application to store an 8-bit value. Table 6.1. NS 16450 UART Registers 6.2. UART Module Design A transaction level model cannot show all the intricacies of a UART—the whole point is to simplify and remove detail. The TLM should allow the CPU to read and write registers and communicate with a model terminal/keyboard which will send and receive characters and generate interrupts as appropriate. While all writable registers can be written and all readable registers read, only those registers and bits of registers which are relevant to this level of modeling will have any impact on behavior. 6.2.1. UART Model Interfaces A TLM 2.0 socket is the natural model for the bus interface to the CPU. However the interface to the terminal is much simpler. Standard byte wide SystemC buffers (sc_buffer) will be suitable, one for the Rx direction and one for Tx. The buffer is implemented for the Rx direction and a port to a buffer for the Tx direction. The terminal (see Chapter 7) will offer the complementary arrangement. 31 Copyright © 2008, 2010 Embecosm Limited Note A SystemC buffer (sc_buffer) is used rather than a SystemC signal (sc_signal), since it must report all writes to the buffer, rather than just changes to the value (as would be the case with a signal). At this level of modeling it is quite possible that two identical bytes would follow each other. The interrupt is not modeled as an interface at this stage, so the UART will only be suitable for polled use. An interrupt interface is added in Chapter 10. 6.2.2. UART Model Registers The divisor latch affects the baud rate, which will affect timing of transfers. This will be covered in a later section (see Chapter 8), but is not needed for the current untimed model. The value can be written and read, but does not affect behavior. All interrupts are modeled (see Section 6.2.3), so all bits in the interrupt enable and interrupt control register are modeled. The modem control and status registers are only modeled to the extent of supporting modem loopback. This is used by some software to determine the nature of the modem (for example in the standard Linux serial line driver). The line control register sets details of the bit transfers. In a later section (see Chapter 8), this will affect the timing of transfers, but it is not relevant to the current untimed model. In the Line Status Register, the Data Ready and Transmitter Holding Empty/Transmitter Empty bits are the only ones modeled. The model does not distinguish a separate buffer and holding transmit register, so the last two of these will move in step in the model. 6.2.3. UART Model Interrupts All interrupts are modeled, although there is no way to cause a receiver line status interrupt. The modem status interrupt can only be generated when modem loopback is in operation. 6.3. Extending the Or1ksimSC Wrapper Module For a larger system, the Or1ksim wrapper module described in Chapter 4 must be extended. A public function is required for peripheral models to establish the CPU endianness. The function must be added to the underlying Or1ksim library and then a wrapper function added to the Or1ksimSC wrapper module. In Section 4.3.5 it was noted that the absence of any call to wait meant the Or1ksim ISS could be the only thread in the model. The doTrans function must be extended to yield after each transaction to allow other threads to run. For our new model, this would prevent the UART and terminal models from running. These extensions are achieved by defining a new class, Or1ksimExtSC derived from the existing Or1ksimSC class. It inherits all the functionality of the existing class, re-implements that of the transport function, doTrans and adds an additional public interface function, isLittleEndian. 6.3.1. Adding an Endianness Test Function to the Or1ksim Library The additional function is straightforward, since endianness is a compile time constant in the Or1ksim ISS. • int or1ksim_is_le(); or1ksim_is_le returns 1 if Or1ksim is modeling a little endian architecture, 0 otherwise. It is needed to ensure the payload is packed with the correct byte ordering. 32 Copyright © 2008, 2010 Embecosm Limited This function is a standard part of the Or1ksim 0.3.0 and Or1ksim 0.4.0 libraries. 6.3.2. Extended Or1ksim Wrapper Module Class Definition The new class, Or1ksimExtSC is derived from Or1ksimSC, so the definition file includes its header. The module class can then inherit from that class. #include "Or1ksimSC.h" class Or1ksimExtSC : public Or1ksimSC { A custom constructor must be defined. Custom constructors do not inherit, so a new custom constructor is defined just to pass the arguments on to the base class. Or1ksimExtSC( sc_core::sc_module_name name, const char *configFile, const char *imageFile ); A new public function to report the endianness of the underlying CPU model is defined bool isLittleEndian(); The doTrans function is reimplemented here, to allow the thread to yield. The function remains protected and virtual, since it will be redefined again later in this application note. virtual void doTrans( tlm::tlm_generic_payload &trans ); The extended Or1ksim wrapper module class, Or1ksimExtSC, definition may be found in sys- models/simple-soc/Or1ksimExtSC.h in the distribution. It uses the TLM 2.0 simple target convenience socket (described earlier in Chapter 5). 6.3.3. Extended Or1ksim Wrapper Module Class Implementation The constructor just passes its arguments to its base class Or1ksimExtSC::Or1ksimExtSC ( sc_core::sc_module_name name, const char *configFile, const char *imageFile ) : Or1ksimSC( name, configFile, imageFile ) { } // Or1ksimExtSC() isLittleEndian is a simple wrapper for the underlying Or1ksim ISS library function1. 1 A technicality is that the Or1ksim library function, is_little_endian returns an int, since C does not have a bool type. A C++ compiler would automatically convert one to the other, but making the comparison explicit is good for clarity. The same code will be generated, so there is no loss of performance. 33 Copyright © 2008, 2010 Embecosm Limited bool Or1ksimExtSC::isLittleEndian() { return (1 == or1ksim_is_le()); } // or1ksimIsLe() The majority of the code for doTrans is unchanged from its implementation in Or1ksimSC. The addition is a wait for zero time immediately after the transaction has completed. This allows the SystemC thread to yield, so that any other threads that are ready can take a turn. wait( sc_core::SC_ZERO_TIME ); Caution ! The call to wait is essential. SystemC is not preemptive. Other threads are only considered for execution when the currently executing thread yields. If the code were to return here, control would pass back to the underlying Or1ksim ISS until its next upcall, with no opportunity for another SystemC thread (such as that for the UART or terminal) to execute. The implementation currently is untimed, so a zero delay wait is perfectly acceptable. That just gives all the other untimed threads a turn at execution. The logger described in Chapter 5 worked without this call to wait, because it had no thread—all its functionality was in the blocking transaction callback function. This is part of the same thread as the original transport call from the initiator port in the Or1ksim wrapper. The extended Or1ksim wrapper module class, Or1ksimExtSC implementation may be found in sys-models/simple-soc/Or1ksimExtSC.cpp in the distribution. 6.4. UART: Module Class Definition The UART module class, UartSC definition may be found in sys-models/simple-soc/UartSC.h in the distribution. It uses the TLM 2.0 simple target convenience socket (described earlier in Chapter 5). 6.4.1. Headers and Constant Definitions The header files for TLM 2.0 and the simple target convenience socket are included. #include "tlm.h" #include "tlm_utils/simple_target_socket.h" Convenience constants for the address mask, named register offsets and bit fields are then defined. The address mask is needed, since in this simple SoC model there is no arbiter/ decoder to strip out the higher order bits from the address before the transaction is sent to the UART. #define UART_ADDR_MASK 7 // Mask for addresses (3 bit bus) Named constants are defined giving the address offset of each register of the UART 34 Copyright © 2008, 2010 Embecosm Limited #define UART_BUF 0 // R/W: Rx/Tx buffer, DLAB=0 #define UART_IER 1 // R/W: Interrupt Enable Register, DLAB=0 #define UART_IIR 2 // R: Interrupt ID Register #define UART_LCR 3 // R/W: Line Control Register #define UART_MCR 4 // W: Modem Control Register #define UART_LSR 5 // R: Line Status Register #define UART_MSR 6 // R: Modem Status Register #define UART_SCR 7 // R/W: Scratch Register Bit masks are declared for each of the bits and bit fields of interest in the UART. For example the interrupt identification register needs a mask for the pending bit of a mask for the two bits representing the highest priority interrupt and a mask for each possible interrupt. #define UART_IIR_IPEND 0x01 // Interrupt pending (active low) #define UART_IIR_MASK 0x06 // the IIR status bits #define UART_IIR_RLS 0x06 // Receiver line status #define UART_IIR_RDA 0x04 // Receiver data available #define UART_IIR_THRE 0x02 // Transmitter holding reg empty #define UART_IIR_MOD 0x00 // Modem status 6.4.2. Class Declaration and Constructor The main class is a standard SystemC module class derived from sc_core::sc_module. class UartSC : public sc_core::sc_module { The module has a customized constructor, specifying an input clock rate (which in the SoC example will be the SoC clock rate), and a flag to indicate the endianness of the model. UartSC( sc_core::sc_module_name name, unsigned long int _clockRate, bool _isLittleEndian ); 6.4.3. Public Interface The interfaces to the UART model are: • The simple target convenience socket, bus, representing the bus from the CPU; • A byte wide SystemC buffer (sc_buffer<unsigned char>) for the Rx pin; and • A byte wide SystemC output port (sc_out<unsigned char>) for the Tx pin. No external port is provided for the interrupt at this stage. That will be added in Chapter 10 6.4.4. SystemC Processes A SystemC thread, busThread, is provided to handle transactions arriving on the bus. A SystemC method, statically sensitive to writes to the Rx buffer is used to handle bytes arriving in the Rx buffer. 35 Copyright © 2008, 2010 Embecosm Limited Note Unlike threads, SystemC methods may not yield by calling wait. A SystemC method is started when one of its static sensitivities is triggered and runs to completion. It is suitable here, where it runs when a character is received, copying that character to the UART RXBUF register and then exiting. it is worth using SystemC methods whenever possible, because they can potentially be implemented more efficiently than threads. 6.4.5. Blocking Transport Callback The blocking transport callback function is busReadWrite. This in turn calls for two separate functions which implement read specific (busRead) and write specific (busWrite) behavior. 6.4.6. Utility Functions A utility function, modemLoopback determines the state of registers and generates an interrupt in the event of modem loopback being requested (a bit in the modem control register). It is used by the busRead and busWrite functions. Three utility functions are provided to handle interrupts. setIntrFlags sets the interrupt indication register according to which interrupts are currently pending. genIntr generates an interrupt and clrIntr clears an interrupt. In this implementation these functions ensure all register flags are set correctly but do not drive an external interrupt signal. A set of convenience utilities are provided to set and clear flags in registers (set and clear) and to test the state of a flag bit in a register (isSet and isClear). 6.4.7. UART State struct regs is used to hold the value of each register. There are ten of these, since register 0 is really two registers, depending on whether it is being read (rbr) or written (thr) and the divisor latch is really an extra 16 bit register. struct { unsigned char rbr; // R: Rx buffer, unsigned char thr; // R: Tx hold reg, unsigned char ier; // R/W: Interrupt Enable Register unsigned char iir; // R: Interrupt ID Register unsigned char lcr; // R/W: Line Control Register unsigned char mcr; // W: Modem Control Register unsigned char lsr; // R: Line Status Register unsigned char msr; // R: Modem Status Register unsigned char scr; // R/W: Scratch Register unsigned short int dl; // R/W: Divisor Latch } regs; An additional register, intrPending, holds flags (corresponding to the interrupt enable register bits) indicating which interrupts are currently pending. A flag initialized at construction records the model endianness, isLittleEndian. 6.4.8. Notifying the Bus Thread of Transaction Activity A function is needed for the TLM 2.0 callback function, busReadWrite to notify the thread handling data being sent for transmission (busThread). This is achieved with a SystemC event: 36 Copyright © 2008, 2010 Embecosm Limited sc_core::sc_event txReceived; The callback function notifies on this event, to trigger behavior in the busThread. 6.5. UART Module Class Implementation The UART module class, UartSC implementation may be found in sys-models/simple-soc/ UartSC.cpp in the distribution. 6.5.1. UART Constructor Implementation of the constructor is preceded, like Or1ksimSC, by the SystemC macro. SC_HAS_PROCESS( UartSC ); The constructor calls the base class (sc_module) constructor to set the module name, saves the endianness flag in its internal state variable and clears the interrupt pending flags. The thread to handle bus I/O is associated with this module. SC_THREAD( busThread ); The method handling data on the Rx buffer is associated with this module with static sensitivity to writes to that buffer. It is not initialized. SC_METHOD( rxMethod ); sensitive << rx; dont_initialize(); The blocking transport callback is registered for the bus socket, in the same manner as was used for the logger, LoggerSC. bus.register_b_transport( this, &UartSC::busReadWrite ); Finally the registers (regs) are cleared. 6.5.2. UART Processes We use the term processes in the SystemC sense to cover both SC_THREAD and SC_METHOD. The busThread is a SC_THREAD. It sits in a perpetual loop. It first marks the transmit buffer as empty (on reset the flags are cleared, so the buffer will appear full). Note The 16450 UART describes two flags for transmit buffer status, one to indicate that the transmit holding register is empty and a second to indicate that the internal transmit buffer register is empty. For simplicity, this model does not model a separate internal register (effectively a one byte FIFO), so both flags are set and cleared together. 37 Copyright © 2008, 2010 Embecosm Limited If the transmit buffer empty interrupt is enabled, the thread generates an interrupt to indicate that the buffer is empty. The thread then waits until it is notified via the SystemC event txReceived that a byte is in the buffer to be sent. This event will be triggered by the busWrite callback when a value is written into the transmit holding register. Note It might be thought that a SystemC SC_METHOD sensitive to txReceived would be more efficient. That would certainly be suitable in this implementation. However this is a virtual function, and when we reimplement later to add timing, we will wish to call wait, which requires a SystemC SC_THREAD. The second process, rxMethod is a SystemC SC_METHOD, sensitive to characters appearing in the Rx buffer. The character is read into the read buffer register and the line status data ready flag is set to indicate availability. If the receive data interrupt is enabled, an interrupt is asserted to indicate data availability. 6.5.3. UART Blocking Transport Callback The registered callback function is busReadWrite, which breaks out the address, byte enable mask pointer and data pointer. A switch statement on the mask is used to determine the offset of the actual byte requested and hence the exact byte address, allowing for the endianness of the model. This also provides a check that only a single byte is being requested. switch( *((uint32_t *)maskPtr) ) { case 0x000000ff: offset = isLittleEndian ? 0 : 3; break; case 0x0000ff00: offset = isLittleEndian ? 1 : 2; break; case 0x00ff0000: offset = isLittleEndian ? 2 : 1; break; case 0xff000000: offset = isLittleEndian ? 3 : 0; break; default: // Invalid request payload.set_response_status( tlm::TLM_GENERIC_ERROR_RESPONSE ); return; } In a perfect world, the router/arbiter function would have masked the address to the range handled by the UART. However for this simple model, the full address is received, so masking with UART_ADDR_MASK is carried out here, to give the address of the UART register being read. Separate functions, busRead and busWrite are used to implement the register specific behavior, selected as appropriate based on the payload command field. Single byte reads and writes always succeed, so the response is set to tlm::TLM_OK_RESPONSE in all cases. 6.5.4. UART Read Behavior Read behavior is handled by busRead. A switch on the address is used to identify the result to be returned, usually just the value in the register if it is readable. The interesting cases are: • If the DLAB bit is set in the line control register, then reads to the first two registers (read buffer and interrupt enable) yield instead the low and high bytes of the divisor latch. 38 Copyright © 2008, 2010 Embecosm Limited • Reading the read buffer (when DLAB=0) yields the byte just read, if flag DR is set in the line status register. The act of reading causes the DR flag and the read buffer full interrupt to be cleared. If no interrupts remain pending then the interrupt pending flag is cleared. • Reading the interrupt indicator register clears the transmit buffer empty interrupt if it was pending. If no interrupts remain pending, then the interrupt pending flag is cleared. • Reading the line status register clears any error indications and the receive line status interrupt if it was pending, although the model has no way of setting any of these indications. If no interrupts remain pending, then the interrupt pending flag is cleared. • Reading the modem status register clears all flags and the modem status interrupt if it was pending. However the modem loopback indication may still be in operation and if so the bits and interrupts are set to indicate the state of the loopback by a call to modemloopback. If no interrupts remain pending, then the interrupt pending flag is cleared. 6.5.5. UART Write Behavior Write behavior is handled by busWrite. A switch on the address is used to identify the action required. Usually the register is just written (if writable). The interesting cases are: • If the DLAB bit is set in the line control register, then writes to the first two registers (read buffer and interrupt enable) update the low and high bytes of the divisor latch respectively. • Writing the transmit hold register (when DLAB=0) triggers a new transfer. The flags are set to indicate data is in the register, the transmit buffer empty interrupt is cleared, and the bus thread (busThread) notified via the SystemC event txReceived. If no interrupts remain pending, then the interrupt pending flag is cleared. • If the modem loopback bit is set by a write to the modem control register, then the modem status bits are set appropriately by a call to modemLoopback. If enabled a modem status interrupt may be generated. 6.5.6. UART Utility Functions setIntrFlags determines the setting of the interrupt identification register according to which interrupts are currently pending (in intrPending). genIntr generates an interrupt by marking the corresponding interrupt as pending if the interrupt is enabled and setting the interrupt identification register flags appropriately. In this implementation, no external signal is generated (see Chapter 10 for details of generating an interrupt signal). clrIntr clears the interrupt pending flag (no need to check if the interrupt is enabled in this case) and sets the appropriate interrupt identification register flags. Again there is no external signal generated in this implementation. A set of functions are provided to set, clear and test bits in registers. Using these makes the code much more readable2. 2 Many programmers use #defined macros for functions such as these. However such macros have no encapsulation (they can be used by anyone including the header) and have a nasty habit of clashing with other programs macros. By using functions, the functions can be made private to the UartSC class alone. A modern C++ compiler will often generate code in line for such small functions, so they will be implemented as efficiently as if they had been #defined as macros. Indeed the added type information gives the potential for greater optimization. 39 Copyright © 2008, 2010 Embecosm Limited Chapter 7. Adding a Terminal as a Test Bench The Or1ksim ISS described in Chapter 4 and the UART described in described in Chapter 6 can be put together as a minimal SoC. However a test bench is needed to exercise that SoC The usual way of exercising a SoC with a UART is to connect a terminal to the UART. This section describes a suitable SystemC model of a terminal and how to connect it to create the complete SoC. This is not a TLM 2.0 component—the interfaces are standard SystemC buffers, so the description is less detailed. However it serves to illustrate an important general technique when using SystemC—how to interact with the operating system functions. The problem is that many operating system calls block. Consider modeling the terminal as a thread which reads characters from a console window. This will block until characters are typed. However the block does not use the SystemC wait call, so SystemC is not aware that the thread has yielded. The simulation will hang until characters are received. This implementation of the terminal will show how to wrap non-blocking versions of operating system functions with SystemC events, to give versions that block correctly using SystemC wait, so allowing the thread to yield. The code for the terminal module (TermSC.cpp and TermSC.h) and the main program (simpleSocMainSC.cpp may be found with the UART module and extended Or1ksim ISS wrapper code in the sysc-models/simple-soc directory of the distribution. 7.1. Overall Design of the Simple SoC Model The key aspects of the overall simple SoC model are captured in a UML class diagram and a UML sequence diagram, showing how a write transaction transfers a character to the modeled terminal. 7.1.1. Class Structure The overall class diagram for the simple SoC design incorporating a UART and terminal is shown in Figure 7.1. Elements from the earlier logger example (see Chapter 5) are shown in less detail. The UART replaces the logger class, and links to a terminal/keyboard emulator via byte wide sc_buffer buffers. The txReceived SystemC event is used by the TLM 2.0 target socket handler of the UART (which is executed in the thread of the calling initiator socket) to notify the bus handling thread of the UART that there is a byte to be passed on to the terminal. Or1ksimSC,32 uchar Or1ksimSC simple_initiator_socket sc_out tx tx 1 1 or1ksim UartSC,32 uchar Or1ksimExtSC simple_target_socket UartSC sc_buffer TermSC bus rx rx 1 1 1 xterm tlm_generic_payload sc_event txReceived ioevent 1 1 Figure 7.1. Class diagram for the simple Or1ksim SoC. 7.1.2. Behavioral Diagrams A sequence diagram, illustrating the handling of a write transaction for the design is shown in Figure 7.2. For simplification, the setting up of the transport call by the Or1ksim wrapper 40 Copyright © 2008, 2010 Embecosm Limited is not shown, since this is the same as for the logger example (see Figure 5.2). As a further simplification the UART is shown writing to the receive buffer of the terminal directly, whereas in detail this is via the sc_out port of the UART and a connecting sc_signal. When a sequence of memory mapped reads and write lead to a byte being received in the UART's transmit buffer, the UART target port handler signals the bus handling thread using the txReceived SystemC event. The UART's bus handling thread then passes that byte to the terminal's buffer, where it can be written to the screen. bus: txReceived: uart:UartSC rx:sc_buffer term:TermSC simple_target_socket sc_event :xterm read() busReadWrite() notify() wait() Bus handling thread wakes write() write() read() Figure 7.2. Sequence diagram for a write transaction with the Or1ksim simple SoC. Note The notification of the byte arrival is an asynchronous activity. It triggers behavior in a separate thread of the UART. Although not conventional UML notation, the two threads are shown as separate lines under the UART to make this clear. Similarly the transfer to the terminal's receive buffer is an asynchronous activity, with a new thread of control (a SystemC SC_METHOD). It is the existence of these separate threads of control which requires the Or1ksim wrapper to execute wait, to allow those threads a chance to execute. 7.2. SystemC Terminal Module Design The terminal provides a SystemC buffer to model the Rx and a port to model the Tx pins of a serial connection. The visualization is provided by a Linux xterm running in a child process, with communication through a pseudo-TTY1. Two SystemC processes are used, one a method waiting for bytes from the UART in the Rx buffer, the other a thread waiting for bytes from the xterm. When bytes are received in the Rx buffer, they are written to the xterm. When bytes are received from the xterm they are written to the Tx port. The key interfaces are shown in Figure 7.3. Read Tx Pseudo-TTY Port xterm Terminal Module (child process) (parent process) Write Rx Pseudo-TTY Buffer Figure 7.3. SystemC terminal model using a xterm child process. 1 The description here is specific to Linux. A future version of this application note will describe use under Microsoft Windows. 41 Copyright © 2008, 2010 Embecosm Limited The difficulty is in waiting for the xterm. As described above, reading from the pseudo-TTY is an operating system call, and does not use the SystemC wait, so the thread will not yield and the simulation will block. Instead the pseudo-TTY is set up to use asynchronous I/O, which will cause a Linux SIGIO to be raised whenever data is available to read. The event handler for SIGIO will then notify a SystemC event, and it is this SystemC event on which the thread can safely wait. 7.3. Terminal Module Class Definition The terminal module class, TermSC definition may be found in sys-models/simple-soc/ TermSC.h in the distribution. 7.3.1. Mapping Signals to Class Instances The operating system signal handlers require C style linkage, so cannot be used with C++ member functions (the same issue addressed by the Or1ksim wrapper in Section 4.2.6). Thus the SIGIO handler will be a static function. However each instance (there could be multiple terminals in a simulation) will have a different file descriptor, which can be used to identify the owning class instance. The set of mappings from file descriptor to class instance is held in a linked list with static head pointer. The struct Fd2Inst is provided for that list, with entries for the file descriptor, instance and a pointer to the next in the list. 7.3.2. The SystemC Class TermSC is declared as a standard SystemC class, with a buffer for bytes coming in, and a port for bytes out (which will connect to a buffer in the UART). In this case it has a custom destructor as well as constructor, which will be used to kill the child process running the xterm when the class is deleted. 7.3.3. Setting up the xterm A set of utility functions are provided to set up the xterm. A function, xtermRead, is provided to read from the xterm and a function, xtermWrite to write to the xterm. Both these functions are blocking on the operating system. The write function should always be able to write with minimal delay. However the read function must only be called when the SIGIO signal handler has determined input is available, in order to avoid blocking the SystemC simulation. There is some internal state to hold the pseudo-TTY file descriptors and the process ID of the xterm (so it can be killed by the destructor). It is the slave file descriptor that is used for both input and output. 7.3.4. Signal and event handling The SIGIO signal handler (ioHandler) is declared static as noted above. The static instList of type Fd2Inst points to the list of mappings from file descriptor to class instance. The SystemC event used to signal when input is available is pointed to by ioEvent. Caution ! It is essential that the event is declared as a pointer. If the event itself were declared here, it would be available at elaboration, and would crash the system (try it!). The solution is to declare the pointer and allocate the event instance dynamically when the xterm is created. The memory can be freed from the destructor on termination. 7.4. Terminal Module Class Implementation The implementation is a standard SystemC module communicating via the Rx buffer and Tx port. It has a SystemC method sensitive to writes to the Rx buffer and a SystemC thread listening to the xterm. 42 Copyright © 2008, 2010 Embecosm Limited The setup of the pseudo-TTYs and the xterm in a separate process uses standard operating system functions, not described further here. The key factor is that the file descriptor for the pseudo-TTY to the xterm is set up to be asynchronous, with Linux signal SIGIO raised when input is available and handled by the ioHandler() function. The terminal module class, TermSC implementation may be found in sys-models/simple-soc/ TermSC.cpp in the distribution. 7.4.1. SystemC Processes The method listening to the UART, rxMethod is sensitive to writes to the rx buffer. When triggered, the character is read from the buffer and immediately copied to the xterm. Although this is a blocking operating system write, it should return with minimal delay. In an environment where any blocking were a concern, a non-blocking write could be used instead. The thread listening to the xterm, xtermThread sits in a perpetual loop, waiting on the SystemC event pointed to by ioEvent. This will safely allow the thread to yield to the SystemC scheduler until a character is ready. When input is available, the event is notified (see Section 7.4.2). The thread can safely make an operating system read to get the character, knowing that data is definitely available. 7.4.2. Signal and event handling During initialization of the xterm the SystemC event, ioEvent is allocated: ioEvent = new sc_core::sc_event(); When ioHandler is called in response to a Linux SIGIO event, it does not know which pseudo- TTY was responsible. The file descriptor responsible is identified by using an operating system select call. Using the mappings in instList, the corresponding class instance can be identified and its ioEvent notified. for( Fd2Inst *cur = instList; cur != NULL ; cur = cur->next ) { if( FD_ISSET( cur->fd, &readFdSet )) { (cur->inst)->ioEvent->notify(); } } This event then allows the xtermThread to run and read a character. 7.5. The Complete SoC 7.5.1. The Model Main Program The structure of the main program (simpleSocMainSC.cpp) is similar to that for the logger test program (see Section 5.4). The TLM 2.0 header and the headers for each module (Or1ksim ISS, UART and terminal) are included. #include "tlm.h" #include "Or1ksimExtSC.h" #include "UartSC.h" #include "TermSC.h" 43 Copyright © 2008, 2010 Embecosm Limited As before the main program (sc_main) takes as arguments the Or1ksim configuration file and OpenRISC 1000 image. Instances of the three modules are declared. Or1ksimExtSC iss( "or1ksim", argv[1], argv[2] ); UartSC uart( "uart", iss.isLittleEndian() ); TermSC term( "terminal" ); The endianness for the UART is set using the public utility function in Or1ksimExtSC. The TLM sockets of UART and ISS can be connected: iss.dataBus( uart.bus ); The Rx buffer in the UART is connected to the Tx port in the terminal and the Rx buffer in the terminal is connected to the Tx port in the UART. uart.tx( term.rx ); term.tx( uart.rx ); The simulation can then be started with a call to sc_start. 7.5.2. Test Program to Run on the Or1ksim ISS The test program, uart-loop.c is a simple polling loop back driver of the UART. Characters are read and immediately echoed back. A volatile structure is declared for the UART registers, with #defined constants for the base address and the register bits of interest. #define BASEADDR 0x90000000 #define BAUD_RATE 9600 #define CLOCK_RATE 100000000 // 100 Mhz struct uart16450 { volatile unsigned char buf; // R/W: Rx & Tx buffer when DLAB=0 volatile unsigned char ier; // R/W: Interrupt Enable Register volatile unsigned char iir; // R: Interrupt ID Register volatile unsigned char lcr; // R/W: Line Control Register volatile unsigned char mcr; // W: Modem Control Register volatile unsigned char lsr; // R: Line Status Register volatile unsigned char msr; // R: Modem Status Register volatile unsigned char scr; // R/W: Scratch Register }; #define UART_LSR_TEMT 0x40 // Transmitter serial register empty #define UART_LSR_THRE 0x20 // Transmitter holding register empty #define UART_LSR_DR 0x01 // Receiver data ready #define UART_LCR_DLAB 0x80 // Divisor latch access bit #define UART_LCR_8BITS 0x03 // 8 bit data bits 44 Copyright © 2008, 2010 Embecosm Limited The utility functions to set and clear flags in the UART (see Section 6.5) are reused here, modified for C rather than C++ and volatile register arguments. They are included from the file binutils.c #include "bitutils.c" The main program declares a pointer to the UART register structure, uart, at the base address. Initialization requires setting the divisor latch, to divide the main clock down to 16 x the baud rate and setting 8-bit data. volatile struct uart16450 *uart = (struct uart16450 *)BASEADDR; unsigned short int divisor; divisor = CLOCK_RATE/16/BAUD_RATE; // DL is for 16x baud rate set( &(uart->lcr), UART_LCR_DLAB ); // Set the divisor latch uart->buf = (unsigned char)( divisor & 0x00ff); uart->ier = (unsigned char)((divisor >> 8) & 0x00ff); clr( &(uart->lcr), UART_LCR_DLAB ); set( &(uart->lcr), UART_LCR_8BITS ); // Set 8 bit data packet The remainder of the program is a perpetual loop: • Wait for a character in the read buffer (flag DR of the line status register is set). • Read the character from the buffer and print it. • Wait for the transmit buffer to clear (flags TEMT and THRE of the line status register are set). • Write the character back. while( 1 ) { unsigned char ch; do { // Loop until a char is available ; } while( is_clr(uart->lsr, UART_LSR_DR) ); ch = uart->buf; simputs( "Read: '" ); // Log what was read simputc( ch ); simputs( "'\n" ); do { // Loop until the transmit register is free ; } while( is_clr( uart->lsr, UART_LSR_TEMT | UART_LSR_THRE ) ); uart->buf = ch; } 45 Copyright © 2008, 2010 Embecosm Limited The source code for the UART loopback program may be found in progs-or32/uart-loop.c in the distribution. It will be built using the OpenRISC 1000 tool chain as part of the overall system build. 7.5.3. Compiling and Running the Model The complete program is compiled from the top level make file. Both a standalone program (simple-soc) and a libtool compliant library (libsimple-soc.la) are created, and both incorporate the library created when building the logger test (see Section 5.6). The library provides a convenient mechanism for reusing the code from this model, when creating subsequent models which use derived classes. The Or1ksim configuration is also unchanged. Like the logger, the UART registers start at address 0x90000000 and are a total of 8 bytes in length. Running the model requires specifying the configuration file (unchanged) and the binary executable (this time the UART loop back program). Assuming the programs have been built in a directory named build, the following command line is suitable. ./build/sysc-models/simple-soc simple.cfg progs_or32/uart-loop The xterm terminal should appear. Select it and type some characters. The window running the model, will show the logged output from the terminal, reporting the same characters being written, as shown in Figure 7.4. $ ./build/sysc-models/simple-soc simple.cfg progs_or32/uart-loop SystemC 2.2.0 --- May 16 2008 10:30:46 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED ... <Or1ksim initialization messages> Read: 'F' Read: 'a' Read: 'r' ... <more Or1ksim output> Read: '!' Read: '!' Read: '!' Figure 7.4. UART loop back program log output. At the same time the characters will be echoed on the xterm, as shown in Figure 7.5. 46 Copyright © 2008, 2010 Embecosm Limited Figure 7.5. xterm with the UART loop back program running. Well it makes a change from "Hello World!". As an exercise, rebuild the model, removing the call to wait in the Or1ksimExtSC::doTrans function. Observe that the program hangs without accepting any characters. The reason for this is given in the description of doTrans in Section 6.3. A debugger connected to the model will show that execution is stuck in Or1ksim ISS, waiting for the data ready flag to be set in the UART. This can never occur, since neither UART nor terminal are given the chance to execute the threads that would set this flag. 7.5.4. Model Timing This model is completely untimed. It executes the behavior of the design, and for that reason such models are useful in system verification. The next stages will add timing to this model. To allow this to be demonstrated, add some logging to the UART and terminal to report the timing of reads and writes. Edit the rxMethod in UartSC, to print out the time when a character is received from the terminal. 47 Copyright © 2008, 2010 Embecosm Limited void UartSC::rxMethod() { regs.rbr = rx.read(); sc_core::sc_time now = sc_core::sc_time_stamp(); cout << "Char " << (char)(regs.rbr) << " read at " << sc_time_stamp () << endl; set( regs.lsr, UART_LSR_DR ); // Mark data ready genIntr( UART_IER_RBFI ); // Interrupt if enabled } // rxMethod() Similarly edit the rxMethod function in TermSC, to print out the time when a character is received from the UART. void TermSC::rxMethod() { xtermWrite( rx.read() ); // Write it to the screen cout << "Char written at " << sc_time_stamp() << endl; } // rxMethod() In both cases the C++ iostream header will be needed at the top of the file (UartSC.cpp and TermSC.cpp), and the entities used will need to be brought into the local namespace. #include <iostream> using sc_core::sc_time_stamp; using std::cout; using std::endl; Note For convenience these changes are already made in the files in the distribution, but the two cout invocations are commented out. All that is needed is to remove the commenting. Once removed, the commenting should stay removed for all the future examples, since they all need to show timing details. The model can now be rerun as before, and will print out precise timing. The output is shown in Figure 7.6. 48 Copyright © 2008, 2010 Embecosm Limited $ ./build/sysc-models/simple-soc simple.cfg progs_or32/uart-loop SystemC 2.2.0 --- May 16 2008 10:30:46 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED ... <Or1ksim initialization messages> Char read at 0 s Read: 'F' Char written at 0 s Char read at 0 s Read: 'a' Char written at 0 s Char read at 0 s Read: 'r' ... <Lots more output> Figure 7.6. UART loop back program log output with timing annotation. As can be seen all the reads and writes occur at time zero. 49 Copyright © 2008, 2010 Embecosm Limited Chapter 8. Adding Synchronous Timing to the Model The current models are all untimed. In the TLM 2.0 components (Or1ksimExtSC and UartSC) the delay parameter to the blocking transport function has been ignored by setting it to zero. In this section, the models are extended to synchronize explicitly with the SystemC clock. The synchronization is not perfect—the underlying Or1ksim ISS executes outside the SystemC world. Synchronization is only possible when it makes an upcall for read or write. In Chapter 9 this model will be further extended to add control over the underlying ISS and its interaction with SystemC time. The code for the timed UART module (UartSyncSC.cpp and UartSyncSC.h), The code for the timed terminal module (TermSyncSC.cpp and TermSyncSC.h), the code for the timed Or1ksim ISS wrapper (Or1ksimSyncSC.cpp and Or1ksimSyncSC.h) and the main program for the complete model (syncSocMain.cpp) may be founded in the sysc-models/sync-soc directory of the distribution. 8.1. Summary of Changes Required for Synchronous Timing Each module of the existing SoC requires some changes. New classes, Or1ksimSyncSC, UartSyncSC and TermSyncSC are derived from the existing classes to provide added functionality. In addition the underlying Or1ksim ISS library will need extending. The main program will need modifying to use these new classes. • Or1ksimSyncSC. A public function to report the clock rate of the underlying Or1ksim ISS is added (requiring an extension to the Or1ksim library), and the transport function, doTrans modified to add timing information. • UartSyncSC. This now models the time taken to put a character out on the Tx wire, so must know its input clock rate (in this SoC, the Or1ksim clock rate), so that baud rate can be calculated from the divisor latch. Also models the true time to process a read or write on the bus and returns this with the transaction response. • TermSyncSC. This now models the time taken to put a character out to the UART, so must know its baud rate. This requires an updated thread listening to the xterm, so that the baud rate delay can be added. • Or1ksim ISS library. Information functions are added to return the model clock rate (used as input clock rate for the UART) and to determine the time spent executing instructions (so Or1ksimSyncSC can determine the synchronization time with SystemC). • A new main program syncSocMainSC.cpp to build the new classes into a synchronized SoC. Information functions are added to return the model clock rate (used as input clock rate for the UART) and the time spent executing instructions (so Or1ksimSyncSC can determine the synchronization time with SystemC. 8.2. Overall Design of the Synchronized SoC Model The key aspects of the overall synchronized SoC model are captured in a UML class diagram and a UML sequence diagram, showing how the timing information is added when processing a transaction. 50 Copyright © 2008, 2010 Embecosm Limited 8.2.1. Class Structure The overall class diagram for the synchronized SoC design incorporating a UART and terminal is shown in Figure 8.1. The design is almost identical to that for the simple SoC (see Section 7.1.1). The only difference is that the Or1ksim ISS wrapper, UART and terminal modules are all subclassed to add the behavior needed for synchronized timing. Or1ksimSC,32 uchar Or1ksimSC simple_initiator_socket sc_out tx tx 1 1 or1ksim UartSC,32 uchar Or1ksimExtSC simple_target_socket UartSC sc_buffer TermSC bus rx rx 1 1 1 xterm Or1ksimSyncSC tlm_generic_payload sc_event txReceived ioevent 1 1 UartSyncSC TermSyncSC Figure 8.1. Class diagram for the Or1ksim SoC with synchronized timing. 8.2.2. Behavioral Diagrams A sequence diagram, illustrating the handling of a transaction for the design is shown in Figure 8.2. Only the handling of the transaction by the wrapper is shown, since there is no significant change in the interactions of the UART and terminal (see Section 7.1.2). Before each upcall transaction, the Or1ksim wrapper class waits for the period of time used by the underlying Or1ksim ISS. This brings all other threads into synchronization, giving them the opportunity to catch up. After each upcall transaction is complete, the timing point of the underlying Or1ksim ISS is reset to zero. dataBus: iss:Or1ksimSyncSC simple_initiator_socket :or1ksim set_time_point() Set initial time stamp run() staticReadUpcall() readUpcall() get_time_period() Wait for time wait() used so far b_transport() set_time_point() Restart ISS timer Figure 8.2. Sequence diagram for the Or1ksim SoC with synchronized timing, showing the timing calls. 51 Copyright © 2008, 2010 Embecosm Limited 8.3. Extending the Or1ksimExtSC Wrapper Module 8.3.1. Adding Clock Rate and Timing Functions to the Or1ksim Library Three additional functions are needed in the Or1ksim library to support synchronized timing. The UART will need to know the clock rate of the model (to work out the baud rate from the value of the divisor latch). The Or1ksimSyncSC class itself will need a pair of functions, one to set a timing point in the ISS the second to return the amount of time since the last timing point. This the amount of time the underlying ISS has used when synchronizing with SystemC. The three additional functions are simple additions. The clock rate is a configuration parameter, while a run time count of instructions executed is already maintained. An extra record in the run-time structure allows a time to be recorded (in seconds through dividing the count by the clock rate), which can be compared in subsequent calls to give the ISS time used since the last time point1. • unsigned long int or1ksim_clock_rate(); or1ksim_clock_rate returns the Or1ksim ISS clock rate in Hz. This information will be used by the UART to allow it to set its baud rate. • void or1ksim_set_time_point(); or1ksim_set_time_point records the current ISS simulation time (clock cycles divided by clock rate) in the run-time data structure. • double or1ksim_get_time_period(); or1ksim_get_time_period returns the time in seconds since the last time point was set. This function is needed to keep the SystemC model of time due to instruction set processing accurate, both in the synchronous SoC and when temporal decoupling is added later (see Chapter 9. These functions are a standard part of the Or1ksim 0.3.0 and Or1ksim 0.4.0 libraries. 8.3.2. Or1ksimSyncSC Module Class Definition The new module class, Or1ksimSyncSC is derived from the existing Or1ksimExtSC module class. The header of the base class, Or1ksimExtSC is included and the new class derived from that base class. #include "Or1ksimExtSC.h" class Or1ksimSyncSC : public Or1ksimExtSC { A custom constructor must be defined, but has the same arguments as the base class constructor, to which it will pass its arguments. 1 This is a loosely timed model. The timing from the ISS is approximate—it does not model the microarchitecture in detail. Cycle estimates will not be exact—that requires a fully cycle accurate model. 52 Copyright © 2008, 2010 Embecosm Limited The new Or1ksim library call to give the clock rate is wrapped by a public function2. unsigned long int getClockRate(); The virtual function, doTrans function is reimplemented—it will replace the call to doTrans in the base class to add timing synchronization. The definition of the Or1ksim ISS wrapper module class with synchronized timing, Or1ksimSyncSC may be found in sys-models/sync-soc/Or1ksimSyncSC.h in the distribution. 8.3.3. Or1ksimSyncSC Module Class Implementation The custom constructor passes its arguments directly to the base class constructor. It then uses the Or1ksim library function, or1ksim_set_time_point to set an initial time point at the start of simulation. The first call to or1ksim_get_time_period will return the time since the ISS started. The doTrans function (which is used for both read and write) is extended from the version used with Or1ksimExtSC to synchronize with the SystemC clock. There are two components to the time taken in this model, the time taken by the Or1ksim ISS and the time taken in any peripherals. At the time of an upcall, the SystemC wrapper thread will not have yielded control since either initialization or the last upcall, when a time point was set in the ISS using or1ksim_set_time_point. A call to or1ksim_get_time_period gives the time used by the ISS in this period. This is used as the argument to wait, allowing any other threads in the SystemC world to run until the calculated simulation time is reached. wait( sc_core::sc_time( or1ksim_get_time_period(), sc_core::SC_SEC )); At this time the blocking transport function of the simple initiator socket is called with the payload and specifying a zero time offset (since the call to wait means the thread is synchronized with the SystemC clock). sc_core::sc_time delay = sc_core::SC_ZERO_TIME; dataBus->b_transport( trans, delay ); On return, the delay parameter will have been updated with any additional delay due to the transaction—in this case an estimate of the number of cycles to read or write the relevant UART register. This delay represents the additional time modeled since this thread last called wait. The thread should wait for this time, to allow other threads to catch up. However, since this is a synchronized model, the target (which is still part of this thread of control, just in a different object) will have already called wait to model the time taken to read or write. So in this case, delay will still be zero on return. The read or write is now complete. A new time point is set with set_time_point before control is returned to the ISS. The ISS will start measuring time from this start point, ready for use in the next upcall. 2 The use of unsigned long int reflects the usage in the Or1ksim ISS. The designers do not anticipate usage to model designs in excess of 4GHz! 53 Copyright © 2008, 2010 Embecosm Limited or1ksim_set_time_point(); The utility getClockRate is a simple wrapper for the underlying Or1ksim library function (see Section 8.3.1). It will be used in the main program (see Section 8.6). unsigned long int Or1ksimSyncSC::getClockRate() { return or1ksim_clock_rate(); } // getClockRate() The definition of the Or1ksim ISS wrapper module class with synchronized timing, Or1ksimSyncSC may be found in sys-models/sync-soc/Or1ksimSyncSC.cpp in the distribution. 8.4. Extending the UartSC Module Class A new class, UartSyncSC derived from UartSC implements the additional functionality for synchronized timing. The time taken for the serial pulses (start, data, parity, stop bits) on the real UART will be modeled as a delay before writing data onto the Tx output port. The corresponding delay on the Rx buffer port will be modeled by the terminal writing into that port3. The TLM 2.0 socket modeling the bus is extended to model the time taken for reads to and writes from the bus. 8.4.1. UartSyncSC Module Class Definition The class definition (in UartSyncSC.h) includes the header of the base class and defines two new constants to represent the delay in reading and writing in nanoseconds. #define UART_READ_NS 60 // Time to access the UART for read #define UART_WRITE_NS 60 // Time to access the UART for write The class is derived directly from the base class, UartSC. A new custom constructor is needed, with an additional parameter specifying the input clock rate. This is used in conjunction with the divisor latch to specify the baud rate. UartSyncSC( sc_core::sc_module_name name, unsigned long int _clockRate, bool _isLittleEndian ); The busThread thread is reimplemented to add the timing delay (as a call to wait in transmitting a character as described above). The blocking transport function, busReadWrite is reimplemented to add in the bus delays in reading and writing. Again this will be achieved by calls to wait, so keeping the model synchronous. 3 This is not the ideal solution. The delay is really a property of the channel, so should be modeled by a derived class of the standard SystemC buffer which provides a defined delay between data being written and data availability being signaled. The approach used here (transmitter models the delay) represents a practical compromise. 54 Copyright © 2008, 2010 Embecosm Limited The busWrite must also be reimplemented, since any change to the divisor latch or the line control register (which specifies the bit format being sent on the wire) could affect the baud rate and timing for busThread A new utility function, resetCharDelay is defined to compute the delay in putting a character on the Tx port from the clock rate, divisor latch and line control register. Two new member variables are declared, to hold the clock rate and the calculated delay to put a character on the Tx port. The implementation of the UART module class with synchronized timing, UartSyncSC may be found in sys-models/sync-soc/UartSyncSC.h in the distribution. 8.4.2. UartSyncSC Module Class Implementation The custom constructor passes the name and _isLittleEndian flag to the base class constructor. The clock rate is saved in the state variable, clockRate. UartSyncSC::UartSyncSC( sc_core::sc_module_name name, unsigned long int _clockRate, bool _isLittleEndian ) : UartSC( name, _isLittleEndian ), clockRate( _clockRate ) { } /* UartSyncSC() */ The new version of busThread adds only one line to the version in the base class. A call to wait( charDelay ) is added when the transmit request is received (notified on the SystemC event, txReceived). wait( txReceived ); // Wait for a Tx request wait( charDelay ); // Wait baud delay tx.write( regs.thr ); // Send char to terminal The new version of busReadWrite draws most of its functionality from the base class version. However it then synchronizes with a time delay for the read or write access. Since the thread is now synchronous, a time delay of zero is returned with the transaction. void UartSyncSC::busReadWrite( tlm::tlm_generic_payload &payload, sc_core::sc_time &delay ) { UartSC::busReadWrite( payload, delay ); // base function switch( payload.get_command() ) { case tlm::TLM_READ_COMMAND: wait( sc_core::sc_time( UART_READ_NS, sc_core::SC_NS )); delay = sc_core::SC_ZERO_TIME; break; <code for write commands etc> 55 Copyright © 2008, 2010 Embecosm Limited The new version of busWrite similarly relies on the base class for most of its functionality. void UartSyncSC::busWrite( unsigned char uaddr, unsigned char wdata ) { UartSC::busWrite( uaddr, wdata ); However any change to the divisor latch or line control register could change the baud rate or the number of bits in each Tx transmission, and hence the modeled delay to send a character. The function identifies if this has happened and if so calls resetCharDelay to recalculate the delay. switch( uaddr ) { case UART_BUF: // Only change if divisorLatch update (DLAB=1) case UART_IER: if( isSet( regs.lcr, UART_LCR_DLAB ) ) { resetCharDelay(); } break; case UART_LCR: resetCharDelay(); // Could change baud delay break; The time taken to put a character on the Tx line is the product of the time taken to put one bit on the line (the inverse of the baud rate) and the bits required for the character (start bit, data bits, optional parity bit, stop bit(s)). The baud rate is determined by the input clock rate and the 16-bit divisor latch. Note The divisor latch for a 16450 divides the input clock to yield an internal clock 16x the baud rate (i.e. not the actual baud rate itself). The 16450 specification supports an input clock up to 24 MHz, so the 16 bit divisor latch can yield an internal clock for rates down to 50 baud. However for a software model this limitation can be ignored. Faster input clocks can be specified, but it will not be possible to configure a 16-bit divisor latch for very low baud rates. The number of bits to send a character is determined by the line control registers. There is always a stop bit, there can be 5-8 data bits, an optional parity bit and 1, 1.5 or 2 stop bits. The resetCharDelay function calculates the total delay. The implementation of the UART module class with synchronized timing, UartSyncSC may be found in sys-models/sync-soc/UartSyncSC.cpp in the distribution. 8.5. Extending the TermSC Module Class A new class, TermSyncSC derived from TermSC implements the additional functionality for synchronized timing. As with the UART (see Section 8.4), the terminal will model the time taken to put the bits of a character on its Tx port. This mirrors the arrangement with the UART, so when the two are connected, delays in both directions are correctly modeled. 56 Copyright © 2008, 2010 Embecosm Limited 8.5.1. TermSyncSC Module Class Definition The new class, TermSyncSC is derived from TermSC. The header for that class is included and the new class derived from it. #include "TermSC.h" class TermSyncSC : public TermSC { A new custom constructor is needed, which takes a second argument to specify the baud rate. TermSyncSC( sc_core::sc_module_name name, unsigned long int baudRate ); The xtermThread thread will be reimplemented. No further derived classes are anticipated, so this function is declared private and not marked as virtual. A variable is needed to hold the baud rate. For convenience the class does not hold the baud rate, but the corresponding delay that this represents in sending a character. sc_core::sc_time charDelay; The definition of the terminal module class with synchronized timing, TermSyncSC may be found in sys-models/sync-soc/TermSyncSC.h in the distribution. 8.5.2. TermSyncSC Module Class Implementation The custom constructor calls the base class constructor to set the module name. The body of the constructor calculates the delay due to the baud rate. There is no configurability (this terminal supports 1 start, 8 data, 0 parity and 1 stop bits only), so this is a one off calculation. TermSyncSC::TermSyncSC( sc_core::sc_module_name name, unsigned long int baudRate ) : TermSC( name ) { charDelay = sc_core::sc_time( 10.0 / (double)baudRate, sc_core::SC_SEC ); } /* TermSyncSC() */ The xtermThread thread is almost identical to the base class version. A single line is added after the character is read from the xterm and before it is written to the port to add the modeled baud rate delay. int ch = xtermRead(); // Should not block wait( charDelay ); // Model baud rate delay tx.write( (unsigned char)ch ); // Send it 57 Copyright © 2008, 2010 Embecosm Limited The implementation of the terminal module class with synchronized timing, TermSyncSC may be found in sys-models/sync-soc/TermSyncSC.cpp in the distribution. 8.6. Main Program for the Synchronous Model As with the untimed SoC (see Section 7.5.1), the main program includes the headers for TLM 2.0 and the component modules, but this time using the synchronously timed versions. #include "tlm.h" #include "Or1ksimSyncSC.h" #include "UartSyncSC.h" #include "TermSyncSC.h" The baud rate for the terminal is defined as a constant for convenience. #define BAUD_RATE 9600 As before the main program (sc_main) takes as arguments the Or1ksim configuration file and OpenRISC 1000 image. Instances of the three modules are declared, but now have additional arguments. The UART requires an input clock rate—obtained from the ISS via the Or1ksimSyncSC public utility function, getClockRate (see Section 8.3.3). The Terminal requires its baud rate to be set. Or1ksimSyncSC iss( "or1ksim", argv[1], argv[2] ); UartSyncSC uart( "uart", iss.getClockRate(), iss.isLittleEndian() ); TermSyncSC term( "terminal", BAUD_RATE ); The remainder of the program, connecting components and starting the simulation is identical to the untimed version. The implementation of the main program for the SoC model with synchronized timing may be found in sys-models/sync-soc/syncSocMainSC.cpp in the distribution. 8.7. Compiling and Running the Synchronous Model The complete program is compiled from the top level make file. Both a standalone program (simple-soc) and a libtool compliant library (libsimple-soc.la) are created, and both incorporate the library created when building the logger test (see Section 5.6). The library provides a convenient mechanism for reusing the code from this model, when creating subsequent models which used derived classes. The Or1ksim configuration is also unchanged. Like the logger, the UART registers start at address 0x90000000 and are a total of 8 bytes in length. Running the model requires specifying the configuration file (unchanged) and the binary executable (this time the UART loop back program). Assuming the programs have been built in a directory named build, the following command line is suitable. .build/sysc-models/sync-soc simple.cfg progs_or32/uart-loop Once again the xterm terminal should appear. Select it and type some characters. The window running the model, will show the logged output from the terminal, reporting the same 58 Copyright © 2008, 2010 Embecosm Limited characters being written and timing of the reads and writes. However this time, the time progresses as the characters are written, as shown in Figure 8.3. $ .build/sysc-models/sync-soc simple.cfg progs_or32/uart-loop SystemC 2.2.0 --- May 16 2008 10:30:46 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED ... <Or1ksim initialization messages> Char F read at 415740466667 ps Read: 'F' Char written at 416796660 ns Char a read at 451075036667 ps Read: 'a' Char written at 452131230 ns Char r read at 516688386667 ps Read: 'r' Char written at 517744580 ns ... <Lots more output> Figure 8.3. UART loop back program log output. The read timing is as the character leaves the terminal, after the terminal has added the baud rate delay. The write timing is as the character leaves the UART after the echo loop in the embedded application on the Or1ksim ISS and after the UART has added the baud-rate delay. So the timing from the read message to the write message should be the time for the UART delay for the current baud rate and packet bits, plus the execution time for the code to echo the character on the Or1ksim ISS. The UART was initialized to use 1 start bit, 8 data bits and 1 stop bit, which at 9600 baud takes around 1040μs. The time shown in Figure 8.3 for the first character to be read and written back is approximately 1056μs. This seems reasonable, allowing approximately 1600 cycles (16μs at 100MHz) for the Or1ksim ISS to process the read and write code. 59 Copyright © 2008, 2010 Embecosm Limited Chapter 9. Adding Temporal Decoupling to the Model In this case study temporal decoupling is added to the TLM 2.0 model of a SoC. The SoC model with arbiter from the previous example is reused. The code for the decoupled Or1ksim ISS wrapper (Or1ksimDecoupSC.cpp and Or1ksimDecoupSC.h), the code for the decoupled UART module (UartDecoupSC.cpp and UartDecoupSC.h) and the main program for the complete model (decoupSocMainSC.cpp) may be founded in the sysc-models/decoup-soc directory of the distribution. 9.1. What is Temporal Decoupling The idea of temporal decoupling is very simple and has been around for a long time (see for example A loosely coupled parallel LISP execution system. ). In a parallel system, the various threads keep their own local time, and only synchronize when they need to communicate with each other. It is particularly suited to timed-based modeling, since it ensures that no one thread hogs the execution. It is worth noting that temporal decoupling does not improve overall model performance per se. All the same elements will need to be modeled. However it does ensure that the various threads in the model stay approximately in step over the duration of the run, making for a more realistic model. In our example it ensures that the Or1ksim model yields control regularly to allow the UART and terminal models to keep up. TLM 2.0 provides some convenience classes to help threads implement temporal decoupling. The nomenclature used by these classes can be more than a little confusing—the following should help to explain how the technique works. There are two key points about temporal decoupling. 1. Temporal decoupling is a property of threads, not module classes. So it is each thread that must keep track of its local view of time. 2. Nothing in the TLM 2.0 system checks a program is following the rules. It is up to each thread to ensure it is compliant. Not all threads need use temporal decoupling, although the more that do, the greater the potential benefit. In general temporal decoupling is only appropriate for threads using TLM 2.0 blocking interfaces for their communication—typically loosely timed models. Where temporal decoupling is implemented it is managed by the threads driving initiator sockets. 9.1.1. Timing Concepts TLM 2.0 defines four different timing entities to describe temporal decoupling. These are illustrated in Figure 9.1. 60 Copyright © 2008, 2010 Embecosm Limited system global quantum = 100μs = thread global quantum local quantum = 65μs TLM Thread 2 local time offset = 30μs local effective time = 265μs local quantum = 65μs TLM Thread 1 local time offset = 45μs local effective time = 280μs Synchronous Thread sc_time_stamp() = 235μs Time 0 50μs 100μs 150μs 200μs 250μs 300μs Figure 9.1. Diagram illustrating temporal decoupling (System) Global Quantum This represents the time unit on which all threads synchronize. For example a Global Quantum of 100μs means that all threads synchronize on 100μs 200μs, 300μs etc. Although the TLM 2.0 standard refers to this as just the Global Quantum, it is a system wide concept and for clarity this application note refers to it as the System Global Quantum. (Thread) Global Quantum This represents the time unit on which a particular thread synchronizes. The TLM 2.0 standard allows different threads to have their own private time unit of synchronization, which is very confusingly also referred to in the standard as the Global Quantum. To avoid confusion, in this application note, the term Thread Global Quantum is used to mean the global quantum used by a particular thread. Having different values for the global quantum in different threads is a recipe for complete confusion, while offering few advantages. The user is strongly recommended to set the Thread Global Quantum to the same value as the System 61 Copyright © 2008, 2010 Embecosm Limited Global Quantum when the thread is created and not change it. Local Quantum For each thread, this represents the time remaining from the current SystemC time (as returned by sc_time_stamp) until the end of the current Thread Global Quantum. For example if the current SystemC time stamp is 235μs and the Thread Global Quantum is 100μs, then the Local Quantum will be 65μs—the time until the 300μs Thread Global Quantum synchronization is due. If the recommendation that all threads set their Thread Global Quantum to be the same as the System Global Quantum is followed, then the value of the Local Quantum will be the same in all threads. Local Time Offset Each thread is allowed to hold a local view of time, which runs ahead of the current SystemC time. This is known as the Local Time Offset The Local Time Offset must not take the thread's local view of time past the next Thread Global Quantum, i.e. it cannot exceed the Local Quantum. For example if the current SystemC time stamp is 235μs and the Thread Global Quantum is 100μs, then a local time offset of 45μs would represent a thread local effective time of 280μs. 9.1.2. The Global Quantum Class, tlm_global_quantum TLM 2.0 defines a singleton class1 which can be used to hold the system global quantum. A set of functions to manipulate the system global quantum are provided. instance Returns a reference to the singleton global quantum object set Sets the system global quantum (as a SystemC sc_time object) get Returns the value of the system global quantum compute_local_quantum Returns the local quantum, i.e. the time from the current SystemC time stamp to the next multiple of the system global quantum. 1 A singleton is a class of which only one instance can be created. The constructor is declared private (so no other class can create it), and a static function is provided to return the single instance. This static function will create the single instance the first time it is called, and thereafter just return a reference to that same instance. Singleton classes are useful for holding centrally required values and providing centrally required functions in a system, where having duplicate provision would lead to incorrect behavior. 62 Copyright © 2008, 2010 Embecosm Limited The intention is that at start up the main program should set the system global quantum in the singleton tlm_global_quantum object. All threads can then set their thread global quantum by getting the value from the tlm_global_quantum object. 9.1.3. TLM 2.0 Quantum Keepers TLM 2.0 provides a utility class for threads to keep track of their thread global quantum, local quantum and local time offset. This is in the tlm_utils namespace (like the convenience sockets) with a header in tlm_utils/tlm_quantumkeeper.h. A module will instantiate one quantum keeper for each thread that uses temporal decoupling, initializing them in the constructor. Two functions are provided to manage the thread global quantum: set_global_quantum to set the value and get_global_quantum. Typically a module constructor will get the system global quantum with a call to the singleton tlm_global_quantum and immediately use that to set the thread global quantum for each thread's quantum keeper. One function is provided to manage the local quantum. The reset function calls compute_local_quantum to calculate the local quantum from the time stamp and the global quantum (which is done by calling the compute_local_quantum in the singleton tlm_global_quantum object) and sets the local time offset to zero. Typically a constructor will call reset for each thread immediately after setting the thread global quantum. The compute_local_quantum in the quantum keeper is protected, so cannot be called directly (which seems to be an omission). If the value of the local quantum is needed, this can be obtained using the compute_local_quantum function in the singleton tlm_global_quantum object. Four functions are provided to manage the local time offset. set sets the local time offset to a particular value, inc increments by a given value and get_local_time returns the current value of the local time offset. get_current_time computes the local effective time, i.e. the SystemC time stamp plus the local time offset2. The intention is that a thread advances model time, it will call set and inc to update the local decoupled view of time. Two functions are provided to handle synchronization. The test need_sync returns true if the local time offset exceeds the local quantum. sync calls wait for the local time offset, synchronizing the thread with the global SystemC view of time, and allowing other threads to catch up. It then calls reset to update the local quantum and zero the local time offset. sync should always be called when need_sync is true, but may be called at any other time if required. 9.1.4. Other Styles of Temporal Decoupling TLM 2.0 presents one model of temporal decoupling, with an explicit regular synchronization time. Other temporal decoupling models can build on the TLM 2.0 infrastructure, for instance to remove the regular synchronization time, and instead only synchronize when the local time offset reaches some prescribed maximum. A class derived from the tlm_gatekeeper class can modify the control and synchronization functions, to allow different approaches to be tried. 9.2. Guidelines for Using TLM 2.0 Temporal Decoupling Temporal decoupling is not for use everywhere. These guidelines may help. 2 The naming is not consistent. get_local_time should have been just get for consistency with set and inc. get_current_time would be better named get_effective_time, to match its description in the standard. 63 Copyright © 2008, 2010 Embecosm Limited 1. Use temporal decoupling for models based on blocking transactions, as used for loosely timed models. There is no obvious value to temporal decoupling in non-blocking models. 2. Only apply temporal decoupling to threads that are communicating via TLM 2.0 transactions. Other SystemC protocols (for example via FIFO) have no way of communicating delays between threads (the equivalent of the delay parameter in TLM 2.0 transport functions). 3. Let the thread controlling the initiator manage the temporal decoupling and synchronization. Targets should just return the incremented delay, and avoid synchronizing if possible. 4. Allocate one quantum keeper for each thread that drives an initiator socket and is implementing temporal decoupling. 5. Ensure that the thread global quantum is always the same as the system global quantum. 6. Select a global quantum that is small enough not to swamp timing behavior of the system. For example in the SoC used in this application note, the finest time granularity that matters is the time to put a character over a 9600 baud link, approximately 1ms. A time around 10-50% of this would be a reasonable time to use as a global quantum. 9.3. Overall Design of the Temporally Decoupled SoC Model The key aspects of the overall decoupled SoC model are captured in a UML class diagram and a UML sequence diagram, showing interaction with the quantum keeper during processing. 9.3.1. Class Structure The overall class diagram for the decoupled SoC design incorporating a UART and terminal is shown in Figure 9.2. The design is similar to that for the synchronized SoC (see Section 8.2.1). The Or1ksim ISS wrapper and UART are both subclassed to add the behavior needed for decoupled timing. There is no need to subclass the terminal module, since it has no TLM interface, and so therefore cannot use decoupling. The new Or1ksimDecoupSC class is associated with both the system global quantum keeper (tgq) and the quantum keeper for the ISS thread (issQk). Or1ksimSC,32 uchar Or1ksimSC simple_initiator_socket sc_out tx tx 1 1 or1ksim UartSC,32 uchar Or1ksimExtSC simple_target_socket UartSC sc_buffer TermSC bus rx rx 1 1 1 xterm Or1ksimSyncSC tlm_generic_payload sc_event txReceived ioevent 1 1 UartSyncSC TermSyncSC Or1ksimDecoupSC <<singleton>> tgq tlm_global_quantum 1 UartDecoupSC tlm_quantumkeeper issQk 1 Figure 9.2. Class diagram for the Or1ksim SoC with decoupled timing. 64 Copyright © 2008, 2010 Embecosm Limited 9.3.2. Behavioral Diagrams A sequence diagram, illustrating the behavior of the Or1ksim wrapper and its interaction with the quantum keepers for the design is shown in Figure 9.3. Only the operations of the wrapper and quantum keepers are sown, since there is no significant change in the interactions of the UART and terminal (see Section 7.1.2). Where before, calls to wait were used to enforce synchronized timing, this time the sync function of the ISS gatekeeper is used to ensure a consistent view of time. Rather than being held in strict synchronization, the threads are allowed to catch up at least at each system global quantum boundary. 65 Copyright © 2008, 2010 Embecosm Limited issQk: tgk: iss:Or1ksimDecoupSC tlm_quantumkeeper tlm_global_quantum :or1ksim set_time_point() Start of loop running set_global_quantum() quanta of execution reset() compute_local_quantum() Start quantum of ISS execution get_local_time() set_time_point() run() staticWriteUpcall() Start of upcall get_time_period() inc() set_time_point() get_local_time() b_transport() set() need_sync() sync() compute_local_quantum() get_local_time() reset_duration() End of upcall End of one quantum get_time_period() of ISS execution inc() need_sync() sync() compute_local_quantum() New quantum of ISS execution starts Figure 9.3. Sequence diagram for the Or1ksim SoC with decoupled timing, showing interaction with the quantum keepers. 9.4. Temporal Decoupling the Or1ksim Wrapper Class The only thread that can be decoupled in the current model is the Or1ksim wrapper class, Or1ksimDecoupSC, since it is the only thread with a TLM 2.0 initiator socket. 66 Copyright © 2008, 2010 Embecosm Limited ISS are natural candidates for temporal decoupling, since they often can run large blocks of code without any need for hardware interaction. This is particularly important for modern compiling ISS (e.g ARM SystemGenerator, ARC xISS), which achieve their performance by executing thousands of instructions at a time. The changes needed to add temporal decoupling are: • Change the main thread, run so that it only tries to execute instructions up to the end of the current global quantum. • Change the upcall transport function, doTrans, so that it increments the local time offset, rather than synchronizing via wait. • Updates to the Or1ksim ISS library to support running to a fixed time point. A new class, Or1ksimDecoupSC is derived from Or1ksimSyncSC to implement the required functionality. 9.4.1. Adding a Function to the Or1ksim Library to Support Temporal Decoupling One additional function is needed in the Or1ksim library to support temporal decoupling. The or1ksim_run already allows the user to specify a duration for which the simulation will run. A function, is added to change the duration of a run already in progress. • void or1ksim_reset_duration( double duration ); or1ksim_reset_duration resets the duration of a call to or1ksim_run which is already in progress. The argument is the duration for which the run should continue from the current time (i.e. not from the time of the original call to or1ksim_run). This function is needed because upcalls may lead to a synchronization, increasing the time for which the ISS may run before needing resynchronization. This function is a standard part of the Or1ksim 0.3.0 and Or1ksim 0.4.0 libraries. 9.4.2. Or1ksimDecoupSC Module Class Definition The new class, Or1ksimDecoupSC is derived from or1ksimSyncSC, whose header it includes. A custom constructor is defined with the same arguments as the base class constructor. The ISS thread, run and the transport function, doTrans are both reimplemented to add temporal decoupling. A pointer to the system global quantum, tgq, and a quantum keeper for the ISS thread, issQk are defined. tlm::tlm_global_quantum *tgq; tlm_utils::tlm_quantumkeeper issQk; The definition of the Or1ksim ISS wrapper module class with decoupled timing, Or1ksimDecoupSC may be found in sys-models/decoup-soc/Or1ksimDecoupSC.h in the distribution. 9.4.3. Or1ksimDecoupSC Module Class Implementation The constructor passes its arguments to the base class, Or1ksimSyncSC. The quantum keeper for the ISS thread is then initialized with the system global quantum and the local quantum calculated and local time offset zeroed with a call to reset. 67 Copyright © 2008, 2010 Embecosm Limited tgq = &(tlm::tlm_global_quantum::instance()); issQk.set_global_quantum( refTgq.get() ); issQk.reset(); Note The global quantum accessor function, instance returns a reference to the global quantum. We convert it to a pointer, since C++ does not allow initialization of a reference instance variable in the constructor. The main thread function, run is reimplemented to ensure that the ISS simulation does not run past the end of the current quantum. Instead of running for ever (or1ksim_run( -1.0 );), the ISS is run for the local time quantum, less the local time offset. This means the ISS will return exactly at the point when it should need to synchronize again. The body of the program is a perpetual loop, which calculates the time left until the next global quantum then calls the ISS for that period. while( true ) { sc_core::sc_time timeLeft = tgq->compute_local_quantum() - issQk.get_local_time(); On return, or1ksim_get_time_period is used to find out how much computation has actually been carried out and advance local time accordingly. This may be different to the duration requested, since an upcall may set a new time point and adjusted the duration. A new time point is immediately set ready for the next loop. (void)or1ksim_run( timeLeft.to_seconds()); issQk.inc( sc_core::sc_time( or1ksim_get_time_period(), sc_core::SC_SEC )); or1ksim_set_time_point(); If the local time offset has reached the end of the global quantum, the thread synchronizes. This replaces the call to wait in the synchronized version of the model (Chapter 8). if( issQk.need_sync() ) { issQk.sync(); The transport function, doTrans has the same structure as the synchronous version in the base class. However instead of calling wait to delay calculation, it updates the local time offset. The time offset is advanced for the ISS simulation since the last time point and a new time point is set. issQk.inc( sc_core::sc_time( or1ksim_get_time_period(), sc_core::SC_SEC )); or1ksim_set_time_point(); The delay argument to the blocking transport is the local time offset. This may be increased by the target (to model read/write delay), and the new value becomes the local time offset on return. 68 Copyright © 2008, 2010 Embecosm Limited sc_core::sc_time delay = issQk.get_local_time(); dataBus->b_transport( trans, delay ); issQk.set( delay ); At this point synchronization could be required—the read/write delay could have pushed the local time offset past the global quantum. if( issQk.need_sync() ) { issQk.sync(); } The duration remaining for the ISS simulation is reset in the same way as in the main thread to be the local quantum less the local time offset. On return the ISS will continue for that period. sc_core::sc_time timeLeft = tgq->compute_local_quantum() - issQk.get_local_time(); or1ksim_reset_duration ( timeLeft.to_seconds() ); The implementation of the Or1ksim ISS wrapper module class with decoupled timing, Or1ksimDecoupSC may be found in sys-models/decoup-soc/Or1ksimDecoupSC.cpp in the distribution. 9.5. Modifying the UART to Support Temporal Decoupling Although the threads in the UART class are not temporarily decoupled, a small modification is needed. The callback for the target socket is part of this class, and it must handle delay data for the initiator in Or1ksimDecoupSC suitably. A new class, UartDecoupSC, derived from UartSyncSC is defined to provide a modified TLM 2.0 convenience target socket blocking callback function. 9.5.1. uartDecoupSC Module Class Definition The class definition includes the header of the base class and is derived from it. The constructor has the same parameters as the base class, UartSyncSC. A reimplemented version of the TLM 2.0 convenience callback, busReadWrite is defined with the same parameters as the base class function. The definition of the UART module class with decoupled timing, UartDecoupSC may be found in sys-models/decoup-soc/UartDecoupSC.h in the distribution. 9.5.2. uartDecoupSC Module Class Implementation The constructor just calls the base class constructor, passing on all its arguments. The BusReadWrite callback has the same structure as the version in the base class. Like the base class it calls the original UartSC version to carry out most of the functionality. Caution ! The call is therefore to the base class of the base class of this class. The call cannot be to the base class, since that would call wait, defeating the temporal decoupling. The difference is in updating the delay. The synchronous base class waited to model the timing delay and set the delay in the response to zero. In this version the code just increments the delay (which is the local time offset) by the additional time to carry out the read or write. 69 Copyright © 2008, 2010 Embecosm Limited switch( payload.get_command() ) { case tlm::TLM_READ_COMMAND: delay += sc_core::sc_time( UART_READ_NS, sc_core::SC_NS ); break; The implementation of the UART module class with decoupled timing, UartDecoupSC may be found in sys-models/decoup-soc/UartDecoupSC.cpp in the distribution. 9.6. Main Program for Temporal Decoupling The main program, decoupSocMainSC.cpp is similar in structure to the main program used for the synchronous version (see Section 8.6). This time the headers for the versions of the Or1ksim wrapper and UART implementing temporal decoupling are used and the time to use as the system global quantum is defined as a parameter. #include "Or1ksimDecoupSC.h" #include "UartDecoupSC.h" #include "TermSyncSC.h" #define QUANTUM_US 100 Before any modules are instantiated, the system global quantum must be set. For the initial version a value of 100μs is selected, 10% of the time taken to transmit a character at 9600 baud, so there should be no awkward timing interactions. tgq->set( sc_core::sc_time( QUANTUM_US, sc_core::SC_US )); Thereafter the program follows the same structure (but using the versions of the Or1ksim wrapper and UART with temporal decoupling). The implementation of the SystemC main program for the decoupled SoC may be found in sys-models/decoup-soc/decoupSocMainSC.cpp in the distribution. 9.7. Compiling and Running the Decoupled Model The complete program is compiled from the top level make file. Both a standalone program (simple-soc) and a libtool compliant library (libsimple-soc.la) are created, and both incorporate the library created when building the logger test (see Section 5.6). The library provides a convenient mechanism for reusing the code from this model, when creating subsequent models which used derived classes. The Or1ksim configuration is also unchanged. Like the logger, the UART registers start at address 0x90000000 and are a total of 8 bytes in length. Running the model requires specifying the configuration file (unchanged) and the binary executable (this time the UART loop back program). Assuming the programs have been built in a directory named build, the following command line is suitable. .build/sysc-models/decoup-soc simple.cfg progs_or32/uart-loop The results look very similar to those for the synchronized version, as shown in Figure 9.4. 70 Copyright © 2008, 2010 Embecosm Limited $ .build/sysc-models/decoup-soc simple.cfg progs_or32/uart-loop SystemC 2.2.0 --- May 16 2008 10:30:46 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED ... <Or1ksim initialization messages> Char F read at 554441676667 ps Read: 'F' Char written at 555541610 ns Char a read at 604641666667 ps Read: 'a' Char written at 605741610 ns Char r read at 666641666667 ps Read: 'r' Char written at 667741600 ns ... <Lots more output> Figure 9.4. UART loop back program log output with temporal decoupling. The timing reported for the first character, 'F', is 1100μs—in the synchronized version it was 1056μs. The global quantum was set to 100μs, which means that other threads may have a delay of up to 100μs before they can run, affecting the time they will report for their actions. If the quantum is changed from 100μs to 10ms, the change is more dramatic, as shown in Figure 9.5. $ .build/sysc-models/decoup-soc simple.cfg progs_or32/uart-loop SystemC 2.2.0 --- May 16 2008 10:30:46 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED ... <Or1ksim initialization messages> Char F read at 541041666667 ps Read: 'F' Char written at 551041600 ns Char a read at 641041686667 ps Read: 'a' Char written at 651041620 ns Char r read at 1471041676667 ps Read: 'r' Char written at 1481041600 ns Figure 9.5. UART loop back program log output with temporal decoupling and 10ms global quantum. The time taken to write the first character is now 10ms, completely dominated by the quantum. The typing of characters at the xterm is notably sluggish. 71 Copyright © 2008, 2010 Embecosm Limited This is characteristic of loosely timed models with temporal decoupling. The objective is to model the gross behavior of the system with a reasonable view of the timing, such that events happen in the correct sequence. However detailed timing can be sacrificed in the interest of greater model performance. The value for the global quantum is a subjective choice. In this case, with a busy polling UART loop back function, any delays were wasted in additional polling cycles, so a small quantum was appropriate. In a more realistic scenario, the UART would be interrupt driven (or at least not polled continuously). Very likely the UART would only be lightly used, while other parts of the system were working. Under such circumstances, a global quantum of 100-500μs (10%-50% of the time to put one character on the UART) would be reasonable. The timing of characters output would be out by up to 100%, but the model would gain from fewer synchronizations. In other scenarios an even higher quantum could be justified—for example if the UART were only for occasional diagnostic output, where sluggishness did not matter. However when modeling a 100MHz ISS as part of the SoC, the benefits of such large global quantum values would be minimal. Beware that an excessively large quantum may break software with timing dependencies. It may mean that interrupt sequences do not arrive in a reasonable order, or flood in all at once. An example of this is shown in Chapter 10. The other step to take to improve the system would be to move to an exclusively TLM 2.0 model. The SystemC buffer is a good way to model the UART to terminal connection. However by using a TLM 2.0 socket in each direction, the UART could adopt temporal decoupling, giving further improvement in the overall model. 72 Copyright © 2008, 2010 Embecosm Limited Chapter 10. Modeling Interrupts and Running Linux on the Example SoC The Simple SoC used in the previous sections is not sufficient to run Linux. Two significant extensions are needed. • Memory management must be added to support Linux virtual memory. This is provided by enabling the internal MMUs (instruction and data) of the Or1ksim ISS. • The SystemC UART peripheral must be extended to handle interrupts. The example design was shown in Section 3.1.3, but for convenience the diagram is repeated here in Figure 10.1. Or1ksim Debug Unit Tx Flash IMMU xterm UART IRQ Rx CPU SRAM DMMU RAM PIC TICK Data Bus Figure 10.1. Simple SoC based on the OpenRISC 1000 Or1ksim with interrupts and MMU. Enabling memory management is a matter of modifying the configuration file for Or1ksim. The Linux port used here expects to boot from flash memory, so the internal memory of Or1ksim is also extended to provide this. The UART model, UartDecoupSC is further extended by a new derived class, UartIntrSC providing a SystemC sc_out<bool> port through which the interrupt signal is driven. The code for the Or1ksim ISS wrapper with interrupts enabled (Or1ksimIntrSC.cpp and Or1ksimIntrSC.h), the code for the interrupt enabled UART module (UartIntrSC.cpp and UartIntrSC.h) and the main program for the complete model (intrSocMainSC.cpp) may be found in the sysc-models/intr-soc directory of the distribution. 10.1. Overall Design of the SoC Model with Interrupts The key aspects of the overall decoupled SoC model are captured in a UML class diagram and a UML sequence diagram, showing how an interrupt is processed during a write transaction to the UART. 10.1.1. Class Structure The overall class diagram for the SoC with interrupts incorporating a UART and terminal is shown in Figure 10.2. The design is similar to that for the temporally decoupled SoC (see 73 Copyright © 2008, 2010 Embecosm Limited Section 9.3.1). The Or1ksim ISS wrapper and UART are both subclassed to add the behavior needed for interrupt handling. There is no need to subclass the terminal module, since it has no interrupts to be modeled. The new Or1ksimIntrSC class is associated with an array of 32 signals, which may be connected to peripherals wishing to raise an interrupt. The new UartIntrSC class is associated with a SystemC FIFO used to collect interrupts raised from both Rx and Tx ports. It also has a SystemC output port, intr on which it drives any interrupt it raises. Or1ksimSC,32 Or1ksimSC simple_initiator_socket sc_event txReceived ioevent 1 1 or1ksim UartSC,32 uchar Or1ksimExtSC simple_target_socket UartSC sc_buffer TermSC bus rx rx 1 1 1 xterm uchar Or1ksimSyncSC tlm_generic_payload sc_out tx tx 1 1 1 intr UartSyncSC TermSyncSC Or1ksimDecoupSC tgq <<singleton>> 1 tlm_global_quantum UartDecoupSC tlm_quantumkeeper issQk 1 bool UartIntrSC sc_fifo bool intrQueue Or1ksimIntrSC sc_signal intr 1 32 Figure 10.2. Class diagram for the Or1ksim SoC with interrupts. 10.1.2. Behavioral Diagrams A sequence diagram, illustrating how the Or1ksim wrapper handles an interrupt when a character is written to the UART is shown in Figure 10.3. Only the interaction between the wrapper and the UART is shown, since the other components largely retain their existing functionality. The model is fully decoupled, but for compactness the actions to handle decoupled timing are omitted. The Or1ksim wrapper maintains a separate process (a SystemC SC_METHOD) to handle interrupts. Similarly the UART adds a new thread to handle interrupts. Although not standard UML separate threads of control are shown for each of these objects in the sequence diagram. 74 Copyright © 2008, 2010 Embecosm Limited iss:Or1ksimIntrSC intr[2]:sc_signal intr:sc_out uart:UartIntrSC intrQueue:sc_fifo :or1ksim { { run() staticWriteUpcall() busReadWrite() write() genIntr() write() Temporal decoupling not shown read() write() event() or1ksim_interrupt() run() Figure 10.3. Sequence diagram for a write transaction on the Or1ksim SoC with interrupts. 10.2. Extending the Or1ksimDecoupSC Module Class The Or1ksim ISS library is extended to provide API calls to generate an interrupt. The Or1ksim includes a programmable interrupt controller (PIC), which is enabled. The new API call, or1ksim_interrupt, provides an edge-triggered interrupt, and takes as parameter the interrupt number to be triggered. The new API calls, or1ksim_interrupt_set and or1ksim_interrupt_set, provide for setting and clearing level sensitive interrupts. The choice of interrupt type to use is made in the Or1ksim configuration file. The Or1ksim wrapper, Or1ksimDecoupSC is further extended by a new derived class, Or1ksimIntrSC, which provides an array of signal ports to connect to external devices which wish to generate interrupts. 10.2.1. Adding Interrupt Generation Functions to the Or1ksim Library The additional function allows the external SystemC model to call into the Or1ksim ISS to request an interrupt. The ISS requires that interrupts are not taken mid-instruction (for example while a peripheral memory access upcall is in progress), so a flag is set internally, allowing the ISS to trigger the interrupt at the start of the next instruction. The standard version of Or1ksim uses edge triggered interrupts, and they are used in this example. However Or1ksim can support level triggered interrupts. For this additional interface functions are provided, although they are not used in this example. • void or1ksim_interrupt( int i ); or1ksim_interrupt requests the the interrupt given by its argument be taken at the start of the next instruction cycle. This is edge-triggered interrupt functionality, and there is no need to clear the interrupt. 75 Copyright © 2008, 2010 Embecosm Limited • void or1ksim_interrupt_set( int i ); or1ksim_interrupt_set asserts the interrupt given by its argument for consideration by Or1ksim at the start of the next instruction cycle. This is for level triggered interrupt handling, and must be explicitly cleared when the interrupt handling is complete. • void or1ksim_interrupt_clear( int i ); or1ksim_interrupt_clear deasserts the interrupt given by its argument for consideration by Or1ksim at the start of the next instruction cycle. This is to clear an interrupt previously asserted with void or1ksim_interrupt_set when using level triggered interrupt handling. or1ksim_interrupt requests the interrupt given by its argument be taken at the start of the next instruction cycle. These functions are a standard part of the Or1ksim 0.3.0 and Or1ksim 0.4.0 libraries. 10.2.2. Or1ksimIntrSC Module Class Definition The new module class, Or1ksimIntrSC is derived from the existing Or1ksimDecoupSC module class, whose header, Or1ksimDecoupSC.h, is included. The number of interrupts to be supported is given by the constant, NUM_INTR. #define NUM_INTR 32 The new class derived from the base class and a custom constructor defined. The possible interrupts are represented by an array of sc_signal. sc_core::sc_signal<bool> intr[NUM_INTR]; Tip It would have been possible to define an array of signal input ports, sc_in<bool>. However these ports must then be explicitly connected (bound), requiring tie-off signals to be created in the main program. By creating actual signals, interrupts that are unused can be left unbound and ignored. A SystemC method is required to handle the interrupts (since it never waits, a thread is not needed). This can respond to interrupts in parallel with the main ISS execution thread. void intrMethod(); The definition of the Or1ksim ISS wrapper module class with interrupts, Or1ksimIntrSC may be found in sys-models/intr-soc/Or1ksimIntrSC.h in the distribution. 10.2.3. Or1ksimIntrSC Module Class Implementation The constructor passes its arguments to the base class constructor for processing. It then sets up intrMethod as a SystemC method process, sensitive to the positive edge of each interrupt signal. There is no need to initialize this function. 76 Copyright © 2008, 2010 Embecosm Limited SC_METHOD( intrMethod ); for( i = 0 ; i < NUM_INTR ; i++ ) { sensitive << intr[i].posedge_event(); } dont_initialize(); The interrupt method is triggered by a positive edge on one of the signals. It loops through to find which interrupt was triggered and generates a call to or1ksim_interrupt for that interrupt number. In principle more than one could be triggered in the same cycle, so all are checked. for( i = 0 ; i < NUM_INTR ; i++ ) { if( intr[i].event()) { or1ksim_interrupt( i ); } } The implementation of the Or1ksim ISS wrapper module class with interrupts, Or1ksimIntrSC may be found in sys-models/intr-soc/Or1ksimIntrSC.cpp in the distribution. 10.3. Extending the UartDecoupSC Module Class The existing UART module processes interrupts, but does not generate an external interrupt signal. To generate an interrupt signal, UartDecoupSC is further extended by a new derived class, UartIntrSC, which provides a signal port and a new thread to drive that signal port An extra thread is required, because both the rxMethod and busThread processes may wish to drive signals, but SystemC requires that a signal is driven by a single process. Just as in hardware design a simple wire would not normally have more than one driver. The new process communicates with the existing processes via a FIFO internal to the UART, allowing rxMethod and busThread to both request interrupt activity and for those requests to be processed in the order they were generated. 10.3.1. UartIntrSC Module Class Definition The new module class, UartIntrSC is derived from the existing UartDecoupSC module class, whose header, UartDecoupSC.h, is included. A custom constructor is declared, and a signal output port, sc_out<bool> intr through which the interrupt will be driven. The new thread, intrThread is declared. It will use re-implemented versions of the genIntr and clrIntr functions from the base class, UartSC. A Boolean FIFO is used to hold the queue of requests from the existing processes, rxMethod and busThread. sc_core::sc_fifo<bool> intrQueue; The definition of the UART module class with interrupts, UartIntrSC may be found in sys- models/intr-soc/UartIntrSC.h in the distribution. 77 Copyright © 2008, 2010 Embecosm Limited 10.3.2. UartIntrSC Module Class Implementation Since this class declares a new SystemC process, SC_HAS_PROCESS is used. The constructor passes its arguments to the base class, UartDecoupSC and sets the FIFO queue size to 1. UartIntrSC::UartIntrSC( sc_core::sc_module_name name, unsigned long int _clockRate, bool _isLittleEndian ) : UartDecoupSC( name, _clockRate, _isLittleEndian ), intrQueue( 1 ) { Note The choice of FIFO size means that there should be only one request for interrupt pending. In principle this could block an attempt by the rxMethod to write to the FIFO, and since SystemC methods may not wait (unlike threads) a run time error will occur. This is an explicit model design decision. If there is interrupt congestion, then it would be useful to know—indicating design issues over the UART capacity. If this were not an issue, then it would be quite valid to use a larger FIFO capacity. The constructor then creates the new SystemC method for intrThread. intrThread has a very simple API. If true is read it asserts an interrupt (drives the interrupt port true), otherwise it deasserts the interrupt port (drives the interrupt port false). On initialization, the interrupt port is deasserted (false). The thread then sits in a perpetual loop, copying requests from the FIFO to the interrupt signal output port. while( true ) { intr.write( intrQueue.read() ); } The interrupt generator, genIntr is almost identical to the version in the base class, UartSC. The only difference is that if an interrupt is generated, a request to drive the signal is written onto the internal interrupt FIFO for processing by the intrThread thread. setIntrFlags(); // Show highest priority intrQueue.write( true ); // Request an interrupt signal The interrupt clear routing is a similar modification, this time requesting the interrupt signal to be cleared by writing false on the FIFO queue. if( isSet( regs.iir, UART_IIR_IPEND )) { // 1 = not pending intrQueue.write( false ); // Deassert if none left The implementation of the UART module class with interrupts, UartIntrSC may be found in sys-models/intr-soc/UartIntrSC.cpp in the distribution. 78 Copyright © 2008, 2010 Embecosm Limited 10.4. Main Program for the Interrupt Driven Model The main program for the model supporting interrupts is in intrSocSC.cpp. It has a very similar structure to the main program used with the temporal decoupling example in Section 9.6, but uses the new versions of the Or1ksim wrapper class and UART module, Or1ksimIntrSC and UartIntrSC. A baud rate of 115,200 is expected for the Linux kernel serial port and a global quantum of 10μs is appropriate for this. A constant is defined to hold the interrupt port number used by the UART (2). #define BAUD_RATE 115200 #define QUANTUM_US 10 #define INTR_UART 2 The main program structure is unchanged, except that the UART interrupt output port needs to be connected to the correct signal in the Or1ksim wrapper: uart.intr( iss.intr[INTR_UART] ); The code for the SystemC main program for the SoC with interrupts may be found in sys- models/intr-soc/intrSocMainSC.h in the distribution. 10.5. Running the Interrupt Driven Model Compilation and linking of the program follows the same procedure as previous examples. As a simple test, the interrupt loop program used in earlier examples is extended to demonstrate basic interrupt handling. However the main test is booting a Linux kernel. 10.5.1. Simple Test for the Interrupt Driven SoC Model A simple test is provided in uart-loop-intr.c as an extension of uart-loop.c. After a character is read, the program loops to wait until the interrupt pending flag is clear (indicating the transmit buffer is empty). do { /* Wait for interrupts to clear */ ; } while( is_set( uart->iir, UART_IIR_IPEND ) ); This is a very basic test—if all is well it behaves identically to the existing loop program. If there is a problem clearing the transmit buffer empty interrupt, or the received data available interrupt is not cleared when data is read, then the program will lock up waiting for the interrupt pending flag to clear. The source code for the interrupt driven UART program may be found in progs-or32/uart- loop-intr.c in the distribution. It is built using the standard OpenRISC 1000 tool chain as part of the main system build. 10.5.2. Running Linux This test uses a Linux 2.6.19 kernel built for the standalone Or1ksim as described in Embecosm Application Note 2. The OpenCores OpenRISC 1000 Simulator and Tool Chain: 79 Copyright © 2008, 2010 Embecosm Limited Installation Guide. [4]. A configuration file, which enables the internal memory management units (MMUs) and Programmable Interrupt Controller (PIC) of the Or1ksim is provided, linux.cfg. This also declares additional internal memory space in Or1ksim for flash and SRAM. The SystemC model is then run with this configuration file and the Linux kernel binary. ./IntrSocSC linux.cfg ../linux-2.6.19/vmlinux Initially Linux copies itself from flash memory to RAM. Copying Linux... Ok, booting the kernel. After a pause while initial booting is taking place the serial interface is ready, allowing the normal kernel boot messages to appear: Linux version 2.6.19-or32 (jeremy@thomas) (gcc version 3.4.4) #59 Wed Jun 25 18: 48:06 BST 2008 Detecting Processor units: Signed 0x391 Setting up paging and PTEs. write protecting ro sections (0xc0002000 - 0xc024c000) Setting up identical mapping (0x80000000 - 0x90000000) Setting up identical mapping (0x92000000 - 0x92002000) Setting up identical mapping (0xb8070000 - 0xb8072000) Setting up identical mapping (0x97000000 - 0x97002000) Setting up identical mapping (0x99000000 - 0x9a000000) Setting up identical mapping (0x93000000 - 0x93002000) Setting up identical mapping (0xa6000000 - 0xa6100000) Setting up identical mapping (0x1e50000 - 0x1fa0000) dtlb_miss_handler c00040c8 itlb_miss_handler c00041a8 Built 1 zonelists. Total pages: 3953 Kernel command line: root=/dev/ram console=ttyS0 <Lots more Linux kernel messages...> Serial: 8250/16550 driver $Revision: 1.90 $ 4 ports, IRQ sharing disabled serial8250.0: ttyS0 at MMIO 0x90000000 (irq = 2) is a 16450 <Lots more Linux kernel messages...> VFS: Mounted root (ext2 filesystem) readonly. Freeing unused kernel memory: 104k freed init started: BusyBox v1.4.1 (2007-03-22 18:53:56 EST) multi-call binary init started: BusyBox v1.4.1 (2007-03-22 18:53:56 EST) multi-call binary Starting pid 22, console /dev/ttyS0: '/etc/init.d/rcS' Please press Enter to activate this console. 80 Copyright © 2008, 2010 Embecosm Limited This takes a simulated time of about 37 seconds, and on a modern PC an elapsed time of around 20-25 seconds (the Or1ksim ISS in this minimal configuration runs at 150-200MHz 1). At this point hitting return will start up a Linux shell, running some basic commands and in this example the BusyBox utilities (see the website for more details). Please press Enter to activate this console. Startingpid 25, console /dev/ttyS0: '/bin/sh' BusyBox v1.4.1 (2007-03-22 18:53:56 EST) Built-in shell (ash) Enter 'help' for a list of built-in commands. # ls /proc 1 2 bus iomem self 10 25 cmdline ioports slabinfo 11 26 cpuinfo kcore stat 12 3 crypto kmsg sys 13 4 devices loadavg sysrq-trigger 14 5 diskstats locks sysvipc 15 6 driver meminfo tty 16 7 execdomains misc uptime 17 8 filesystems mounts version 18 9 fs net vmstat 19 buddyinfo interrupts partitions zoneinfo # busybox mount rootfs on / type rootfs (rw) /dev/root on / type ext2 (ro) proc on /proc type proc (rw) # The importance of choosing a suitable value for the global quantum is well illustrated here. Rebuild the model with a global quantum of 100μs—rather longer than the time it takes to transmit one character at 115,200 baud. #define QUANTUM_US 100 The time taken to boot is marginally faster (19s), but this time the terminal cannot cope with the erratic interrupt behavior. VFS: Mounted root (ext2 filesystem) readonly. Freeing unused kernel memory: 104k freed init started: BusyBox v1.4. Please press Ent The Linux serial driver loses interrupts and the system locks up and will eventually crash with an unhandled interrupt exception. 1 This may seem exceptionally fast for an interpreting ISS, but this model is configured with slow RAM with a 20-25 cycle access time and no caches. So 150-200MHz represents only 5-10 MIPS. That's why booting a basic Linux kernel takes 37s of simulated time, rather than the 2-3s that might reasonably be expected! 81 Copyright © 2008, 2010 Embecosm Limited Chapter 11. Adding a JTAG Interface to the Model All the models in previous chapters have considered only the main WishBone bus interface to the OpenRISC 1000. However the processor also provides a debug interface, which at the hardware level is implemented via a IEEE 1149.1 JTAG. At the simplest level, it is easy to have a transactional view of JTAG. Registers are shifted in and registers are shifted out. A simple read-modify-write transaction. The difficulty is that JTAG is a bit serial interface, whereas TLM 2.0 really models simple reads and writes over bus interfaces (such as WishBone). The solution is to represent the JTAG register in a byte vector, and use a TLM 2.0 generic payload extension to describe the JTAG specific characteristics of bit length and target action (reset, shift through the instruction register or shift through the data register). This is described in Section 11.2. The example design extended to support JTAG was shown in Section 3.1.4, but for convenience the diagram is repeated here in Figure 11.1. Or1ksim Debug JTAG GNU Debugger Debug Unit Interface Flash IMMU CPU SRAM xterm Tx IRQ DMMU RAM Rx UART PIC TICK Data Bus Figure 11.1. Simple SoC based on the OpenRISC 1000 Or1ksim with interrupts, MMU and JTAG debug interface. For this example, a full debugger is not used to drive the JTAG interface. Instead a simple JTAG logger, JtagLoggerSC, is used. This initializes the JTAG interface, then reads the Next Program Counter (NPC) SPR once per second. This is achieved by shifting a JTAG register for a debug unit WRITE_COMMAND to specify the SPR to read, followed by shifting a JTAG register for a debug unit GO_COMMAND to read the actual register. This simplified design is shown in Figure 11.2. Or1ksim JTAG JTAG Debug Unit Logger Flash IMMU CPU SRAM xterm Tx IRQ DMMU RAM Rx UART PIC TICK Data Bus Figure 11.2. Simple SoC based on the OpenRISC 1000 Or1ksim with interrupts, MMU and JTAG logger. 82 Copyright © 2008, 2010 Embecosm Limited The Or1ksimIntrSC is extended with a new TLM 2.0 target port and handler for JTAG. This in turn requires a new TLM 2.0 generic payload extension class, JtagExtensionSC. The code for the Or1ksim wrapper with JTAG interface (Or1ksimJtagSC.cpp, Or1ksimJtagSC.h), the code for the generic payload extension (JtagExtensionSC.cpp, JtagExtensionSC.h), the code for the JTAG logger (JtagLoggerSC.cpp, JtagLoggerSC.h) and the main program for the complete model (jtagSocMain.cpp) may be found in the sysc-models/jtoc-soc directory of the distribution. 11.1. Overall Design of the SoC Model with JTAG Interface The key aspects of the overall decoupled SoC model are captured in a UML class diagram and a UML sequence diagram, showing how a transaction for the JTAG port is processed. 11.1.1. Class Structure The overall class diagram for the SoC with JTAG debug support incorporating a UART, terminal and simple debug logger is shown in Figure 11.3. The design is similar to that for the SoC with interrupts (see Section 10.1.1). The overall diagram is now quite complex, so, for clarity, only those classes new to the JTAG enabled design are shown. The remaining detail was shown earlier in Figure 10.2. The Or1ksim ISS wrapper is subclassed to add the new target port and handler for JTAG. This needs a SystemC mutex in order to ensure that access to the JTAG port does not clash with running of the underlying Or1ksim model. This is discussed in more detail in Section 11.2. The new logger class, JtagLoggerSC provides a simple stream of debug JTAG register transfers through the debug TLM 2.0 interface. That interface makes use of the mandatory extension class JtagExtensionSC to specify details of the JTAG register being shifted. JtagLoggerSC,1 simple_initiator_socket jtag JtagLoggerSC 1 Or1ksimSC,32 debugger simple_initiator_socket Or1ksimSC JtagExtensionSC tlm_extension_base or1ksim JtagExtensionSC tlm_extension bool tlm_generic_payload sc_signal JtagExtensionSC intr 32 Or1ksimIntrSC <<enum>> AccessType UartSC,32 simple_target_socket bus UartSC 1 sc_mutex xterm Or1ksimJtagSC,1 simple_target_socket bool jtag Or1ksimJtagSC UartIntrSC sc_fifo mutex 1 1 intrQueue 1 Figure 11.3. Class diagram for the Or1ksim SoC with JTAG interface. 83 Copyright © 2008, 2010 Embecosm Limited 11.1.2. Behavioral Diagrams A sequence diagram, illustrating how the Or1ksim wrapper handles a debug transaction is shown in Figure 11.4. Only the interaction between the wrapper and the JTAG debug interface is shown, since the other components largely retain their existing functionality. The model is fully decoupled and processes interrupts, but for compactness these details are not repeated here. The key feature is the use of a SystemC mutex to ensure that the JTAG transactions are only processed between calls to the Or1ksim run method. logger:JtagLoggerSC iss:Or1ksimIntrSC or1ksimMutex:sc_mutex :or1ksim { lock() Temporal run() decoupling and interrupts not shown unlock() lock() jtag_shift_dr() unlock() lock() run() Figure 11.4. Sequence diagram for a debug transaction on the Or1ksim SoC with JTAG interface. 11.2. A TLM 2.0 Interface for JTAG Using a Payload Extension The SystemC TLM 2.0 generic payload is intended for use with models of conventional buses. The payload is a multiple of bytes long and transmitted over an interface that is a multiple of bytes wide. This is not a good fit for bit-serial interfaces such as IEEE 1149.1 JTAG. It is possible to build a completely new payload, customized to such an interface, and which would permit use of all the other TLM 2.0 infrastructure. However such a task is complex and time-consuming, and is not good for compatibility between models. As an alternative, SystemC permits extension of the generic payload. There are two flavors of extension, ignorable extensions are used where the generic payload is still meaningful without the extension being present. Mandatory extensions are used where the information in the payload is essential to correct operation of targets and initiators. Ignorable extensions are preferred wherever possible, since they maximize reusability of the interface. The C++ type system is used to enforce mandatory extensions, and their use requires sharing a defining type between all targets and initiators. For the JTAG interface we use an ignorable extension. Where present, this specifies what type of transaction is required (reset, shift through the instruction register, shift through the data register) and the exact bit length of the register being shifted. The actual data is supplied as a byte vector in the generic payload as normal. Where the extension data is not provided, the type of transaction is inferred from the generic payload's address: 0 for shifting through the instruction register, 1 for shifting through the data register and any other value for reset. The bit length is calculated as 8 times the generic payload data length. 84 Copyright © 2008, 2010 Embecosm Limited In practice the extension will always be used, but by being ignorable, we allow the maximum possible reuse of the interface in applications. 11.2.1. JtagExtensionSC Extension Class Definition The extension class is a subclass of the abstract SystemC template class tlm::tlm_extension class JtagExtensionSC: public tlm::tlm_extension<JtagExtensionSC> The extension holds data on the JTAG access type required (reset, shift through the instruction register, shift through the data register) and the exact number of bits to be shifted. For long term compatibility a data field to request debug is added, although it is not used in this application note. An enumeration type is specified to define the access type. This is public, since targets and initiators must be able to reference it. enum AccessType { RESET, SHIFT_IR, SHIFT_DR }; The constructor initializes the data fields to appropriate default values (type RESET, bit size zero, debug disabled). JtagExtensionSC (); It might be thought appropriate to have variants that could simultaneously initialize the arguments, allowing for easy dynamic allocation and destruction of extensions as needed. However allocation of the extension class is expensive in SystemC, and dynamic allocation is discouraged. Instead a single instance is typically allocated and reused. Two virtual methods from the parent class must be implemented to allow instances to cloned and copied. virtual tlm::tlm_extension_base* clone() const; virtual void copy_from (tlm::tlm_extension_base const &ext); The public interface to the extension is through its accessors, a pair for each data field. AccessType getType () const; void setType (AccessType _type); int getBitSize () const; void setBitSize (int _bitSize); bool getDebugEnabled () const; void setDebugEnabled (bool _debugEnabled); 85 Copyright © 2008, 2010 Embecosm Limited The data itself is held privately within the class. AccessType type; int bitSize; bool debugEnabled; The definition of the SystemC generic payload extension class for JTAG, JtagExtensionSC, may be found in sys-models/jtag-soc/JtagExtensionSC.h in the distribution. 11.2.2. JtagExtensionSC Extension Class Implementation The constructor simply initializes the private data fields to default values (type RESET, bit size zero, debugging disabled). The two virtual methods which must be implemented, clone and copy_from use boilerplate code from the TLM 2.0 language reference manual. This is quite sufficient for a simple extension like this. Finally the three pairs of accessor methods allow each field to be read or set. The implementation of the SystemC generic payload extension class for JTAG, JtagExtensionSC, may be found in sys-models/jtag-soc/JtagExtensionSC.cpp in the distribution. 11.3. Extending the Or1ksimIntrSC Module Class The Or1ksim ISS library is extended to provide API calls to handle JTAG registers being shifted in and out. The API call, or1ksim_jtag_reset, causes the JTAG unit to process through a reset sequence. The API calls, or1ksim_jtag_shift_ir and or1ksim_jtag_shift_dr, take a byte vector and bit length as arguments and shift specified number of bits through the instruction register and data register respectively. All three API calls return the time taken by the function in seconds (as a C++ double). A key aspect of this API is that the calls may not be used during the execution of or1ksim_run. This could occur during processing of an upcall, but at such a time the processor is mid-instruction and the state for debug unit processing is inconsistent. This requirement is enforced in the wrapper by use of a SystemC sc_mutex. The Or1ksim wrapper, Or1ksimIntrSC is further extended by a new derived class, Or1ksimJtagSC, which provides a TLM 2.0 target port to for JTAG transactions and a handler method, jtagHandler, for those requests. The JTAG target port makes use of TLM 2.0 generic payload with an ignorable extension, used to specify precisely the JTAG operation required and the size in bits of the JTAG register. The class JtagExtensionSC (see Section 11.2) is defined for this purpose. 11.3.1. Adding JTAG Interface Functions to the Or1ksim library These additional functions allow the external SystemC model to call into the Or1ksim ISS to request debugging activity through use of a JTAG register. The ISS requires that interrupts are not taken mid-instruction (for example while a peripheral memory access upcall is in progress). However it is up to the caller to enforce this restriction. 86 Copyright © 2008, 2010 Embecosm Limited JTAG registers are represented as a byte vector, with the least significant bits in the lowest numbered byte. Where the number of bits is not a multiple of eight, it is the most significant byte which holds the odd number of bits, shifted to the least significant position within the byte. Thus for a 12-bit register, bits 0-7 would be in byte 0 and bits 8-11 would be in the least significant 4 bits of byte 1. • double or1ksim_jtag_reset (); or1ksim_jtag_reset requests the Or1ksim ISS debug unit go through a JTAG reset cycle to put the Test Access Port (TAP) in a consistent state. It returns the time taken in seconds. • double or1ksim_jtag_shift_ir (unsigned char *jreg, int num_bits); or1ksim_jtag_shift_ir shifts the JTAG register specified by its arguments through the JTAG instruction register. It returns the time taken in seconds. • double or1ksim_jtag_shift_dr (unsigned char *jreg, int num_bits); or1ksim_jtag_shift_dr shifts the JTAG register specified by its arguments through the JTAG data register. It returns the time taken in seconds. The behavior of the debug unit in response to JTAG register transfers is fully documented in descriptions of the Test Access Port [3] and the OpenCores Debug Unit [2]. These functions are a standard part of the Or1ksim 0.4.0 library. Caution ! These functions are not a standard part of the Or1ksim 0.3.0 library. 11.3.2. Or1ksimJtagSC Module Class Definition The new module class, Or1ksimIntrSC is derived from the existing Or1ksimIntrSC module class, whose header, Or1ksimIntrSC.h, is included. The key addition to the public interface is a 1-bit wide TLM 2.0 target port for JTAG transactions. tlm_utils::simple_target_socket&Or1ksimJtagSC, 1& jtag; The constructor is identical in form to that of the base class, taking the same arguments. It will have more work to do, setting up the target TLM 2.0 port handler and clearing the mutex. The protected virtual run method is reimplemented in this class. Functionally it is very similar to the base implementation, but a SystemC mutex is used to ensure that it does not run while a JTAG transaction is being processed. 87 Copyright © 2008, 2010 Embecosm Limited As described earlier (see Section 11.2), the JTAG transactional interface uses an ignorable payload extension. If this extension is not present, the address field of the generic payload is used to infer the action required. For convenience the addresses corresponding to the instruction and data registers are specified. static const unsigned int ADDR_SHIFT_IR = 0; static const unsigned int ADDR_SHIFT_DR = 1; JTAG transactions cannot be processed while the underlying Or1ksim ISS is running. This is enforced using a SystemC mutex. sc_core::sc_mutex or1ksimMutex; Finally we need a handler for JTAG transactions that are received. void jtagHandler( tlm::tlm_generic_payload &payload, sc_core::sc_time &delay ); The definition of the Or1ksim ISS wrapper module class with JTAG debug support, Or1ksimJtagSC may be found in sys-models/jtag-soc/Or1ksimJtagSC.h in the distribution. 11.3.3. Or1ksimJtagSC Module Class Implementation The constructor passes its arguments to the base class. It then associates the JTAG target port with its handler and clears the mutex. // Bind the handler to the JTAG target port. jtag.register_b_transport( this, &Or1ksimJtagSC::jtagHandler ); // Unlock the Mutex or1ksimMutex.unlock (); The implementation of the run method is very similar to the base class for temporally decoupled models (see Section 9.4.3). However the call to or1ksim_run is surrounded by lock/unlock of the mutex to ensure it cannot run at the same time as a thread requesting JTAG access. or1ksimMutex.lock (); (void)or1ksim_run (timeLeft.to_seconds ()); or1ksimMutex.unlock (); The handler for JTAG transactions attempts to determine the type and exact bit size of the register from the extension payload. If this is not present (it is an ignorable extension), then it uses the generic payload address and data length instead. 88 Copyright © 2008, 2010 Embecosm Limited // Retrieve the extension. JtagExtensionSC *ext; payload.get_extension (ext); // Check if the extension exists. Set up the access type and bit size as // appropriate. JtagExtensionSC::AccessType type; int bitSize; if (NULL == ext) { unsigned int addr = (unsigned int) payload.get_address (); type = (ADDR_SHIFT_IR == addr) ? JtagExtensionSC::SHIFT_IR : (ADDR_SHIFT_DR == addr) ? JtagExtensionSC::SHIFT_DR : JtagExtensionSC::RESET ; bitSize = 8 * (int) payload.get_data_length (); } else { type = ext->getType (); bitSize = ext->getBitSize (); } The handler then calls the appropriate function in the Or1ksim ISS, surrounding the call by a mutex lock/unlock, to ensure that JTAG transactions are not processed while the ISS is running. This could occur if an upcall caused a wait () allowing processing of a JTAG transaction to occur. The implementation of the Or1ksim ISS wrapper module class with JTAG debug support, Or1ksimJtagSC may be found in sys-models/jtag-soc/Or1ksimJtagSC.cpp in the distribution. 11.4. A JTAG Traffic Generating Class In normal use, a debugger, such as GDB would be connected to the JTAG port. For demonstrating the interface, we use a stripped down JTAG logger class. This uses the debug interface to read the processor's next program counter SPR once per (modeled) second. With the Or1ksim debug unit (see [2]), this requires the following steps. • Reset the JTAG interface • Shift DEBUG (0x8) into the JTAG instruction register. • Construct a JTAG data register to select module CPU0 so we can access its SPRs and shift that into the JTAG data register. • Construct a JTAG data register for the WRITE_COMMAND debug unit command, specifying that we wish to read the next program counter SPR and shift that into the JTAG data register. • Construct a JTAG data register for the GO_COMMAND debug unit command, to collect the value read from the next program counter SPR and shift that into the JTAG data register. 89 Copyright © 2008, 2010 Embecosm Limited These last two steps are repeated with a wait of one second between, to give a regular report on the value of the next program counter. 11.4.1. JtagLoggerSC Module Class Definition The logger will require a simple TLM 2.0 initiator socket, which will use the generic payload with a custom extension, JtagExtensionSC. The relevant headers are included. #include <tlm.h> #include <tlm_utils/simple_initiator_socket.h> #include "JtagExtensionSC.h" The logger declares an initiator TLM 2.0 port to connect to the target port in the Or1ksim wrapper. This is the public interface to this module. tlm_utils::simple_initiator_socket<JtagLoggerSC, 1> jtag; A constructor is needed to connect the extension to the generic payload and to declare the SystemC thread generating JTAG transactions. JtagLoggerSC (sc_core::sc_module_name name); The module uses a single allocation of payload and extension. The temptation is to allocate and free these dynamically locally where they are needed. However, as noted earlier (see Section 11.2 this is an expensive operation in SystemC, so we have a single instance of each. The extension will be associated with the payload in the constructor. tlm::tlm_generic_payload payload; JtagExtensionSC ext; A SystemC thread is used to generate the traffic, and this is implemented in the private method, runJtag. virtual void runJtag(); The JTAG registers for the Or1ksim debug unit have a complex structure. A set of utility methods is provided to construct the registers. 90 Copyright © 2008, 2010 Embecosm Limited void jtagReset (sc_core::sc_time &delay); void jtagInstruction (unsigned char inst, sc_core::sc_time &delay); void jtagSelectModule (unsigned char moduleId, sc_core::sc_time &delay); void jtagWriteCommand (unsigned char accessType, unsigned long int addr, unsigned long int numBytes, sc_core::sc_time &delay); void jtagGoCommandRead (unsigned char data[], unsigned long int dataBytes, sc_core::sc_time &delay); // Utilities unsigned long int crc32 (unsigned long long int value, int num_bits, unsigned long int crc_in); unsigned long long reverseBits (unsigned long long val, int len); The definition of the JTAG logger module class, JtagLoggerSC may be found in sys-models/ jtag-soc/JtagLoggerSC.h in the distribution. 11.4.2. JtagLoggerSC Module Class Implementation The class is declared as having a dynamic process, since the constructor will set up a SystemC thread. SC_HAS_PROCESS (JtagLoggerSC); The constructor passes the module name up to the base class. It associates the payload extension instance with the generic payload instance. Finally it declares a new SystemC thread. We must use a SC_THREAD rather than SC_METHOD since the thread method, runJtag will wait () for one second between each read of the next program counter. payload.set_extension (&ext); SC_THREAD (runJtag); The main thread method, runJtag uses the various support utilities to construct JTAG registers which are then transported to the target wrapped ISS First the JTAG reset, instruction and module selection are shifted, each followed by a message, noting how long the step took. 91 Copyright © 2008, 2010 Embecosm Limited jtagReset (delay); cout << "Reset after " << delay << "." << endl; wait (SC_ZERO_TIME); delay = SC_ZERO_TIME; jtagInstruction (DEBUG_INST, delay); cout << "Instruction shifted after " << delay << "." << endl; wait (SC_ZERO_TIME); delay = SC_ZERO_TIME; jtagSelectModule (CPU0_MOD, delay); cout << "Module selected after " << delay << "." << endl; wait (SC_ZERO_TIME); A wait for zero time between each transaction ensures any other thread has an opportunity to resume if needed. The main loop reads the next program counter, waiting for one second between each loop. The read involves two transactions, one WRITE_COMMAND to specify the transfer required, one GO_COMMAND to accomplish the transfer. while (true) { // Specify the WRITE_COMMAND to read the NPC SPR delay = SC_ZERO_TIME; jtagWriteCommand (READ32, SPR_NPC, 4, delay); cout << "WRITE_COMMAND after " << delay << "." << endl; wait (SC_ZERO_TIME); // Read the data, remembering that OR1200 is big endian unsigned char res[4]; // For the data read back delay = SC_ZERO_TIME; jtagGoCommandRead (res, 4, delay); cout << "GO_COMMAND after " << delay << "." << endl; cout << "- NPC = 0x" << hex << (int) res[3] << (int) res[2] << (int) res[1] << (int) res[0] << dec << "." << endl; wait (sc_time (1000.0, SC_MS)); } The utilities to help in constructing registers and passing them to the target are largely concerned with the minutiae of format. In each the register is constructed, transported to the target and the returned register analyzed. The implementation of the JTAG logger module class, JtagLoggerSC may be found in sys- models/jtag-soc/JtagLoggerSC.cpp in the distribution. 11.5. Main Program for the Model with JTAG Debug Interface The main program for the model with JTAG interface is in jtagSocSC.cpp. It has a very similar structure to the main program used with the interrupt enabled example in Section 10.4, but 92 Copyright © 2008, 2010 Embecosm Limited uses new versions of the Or1ksim wrapper class and adds in the JTAG logger module to generate JTAG debug port traffic. JtagLoggerSC logger ("logger"); logger.jtag (iss.jtag); The code for the SystemC main program for the SoC with JTAG debug interface may be found in sys-models/jtag-soc/jtagSocMainSC.cpp in the distribution. 11.6. Running the Model with JTAG Debug Interface Compilation and linking of the program follows the same procedure as previous examples. As a simple test, the interrupt loop program with interrupts used in Section 10.5 is reused, but this time the value of the next program counter will also be printed on the console. 11.6.1. Simple Test for the Model with JTAG Debug Interface The program is run in the same way as earlier tests. For example from the build directory as follows. $ ./sysc-models/jtag-soc/jtag-soc ../simple.cfg progs-or32/uart-loop-intr As before a xterm screen will appear, and characters typed at the keyboard will be reflected. This time however the console will also log the results of the various JTAG commands. 93 Copyright © 2008, 2010 Embecosm Limited SystemC 2.2.0 --- May 16 2008 10:30:46 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED <Lots of Or1ksim startup messages> Reset after 200 ns. Instruction shifted after 160 ns. Module selected after 2920 ns. WRITE_COMMAND after 5 us. GO_COMMAND after 4200 ns. - NPC = 0x00142c. Read: 'F' Read: 'a' Read: 'r' Read: 'e' Read: 'w' Read: 'e' Read: 'l' Read: 'l' Read: ' ' Read: 'G' Read: 'a' Read: 'l' Read: 'a' Read: 'x' Read: 'y' WRITE_COMMAND after 5 us. GO_COMMAND after 4200 ns. - NPC = 0x0012b0. Read: '!' WRITE_COMMAND after 5 us. GO_COMMAND after 4200 ns. - NPC = 0x001284. The values for the next program counter can be compared against an ordered name table for the UART application. $ or32-elf-nm progs-or32/uart-loop-intr | sort 00000100 T _start 00001000 T _set 00001094 T _clr 00001164 T _is_set 0000121c T _is_clr 000012c8 T _main 00001564 T _simexit 00001584 T _simputc 000015a4 T _simputh 000016f0 T _simputs 94 Copyright © 2008, 2010 Embecosm Limited It can be seen that the first value (0x00142c) falls within the main function, while the second (0x0012b0) and third (0x001284) fall within the flag testing function, is_clr. 95 Copyright © 2008, 2010 Embecosm Limited Appendix A. Downloading the Example Models The example models used in this application note may all be downloaded from the Embecosm website, www.embecosm.com. They are licensed under the GNU General Public License so are freely available to be used. The main directory of the distribution contains: • A directory, sysc-models, containing the example SystemC models; • A directory, progs-or32, containing the OpenRISC 1000 programs to be used with the models • Configuration files for use with Or1ksim when running the simple models and the Linux kernel; and • A copy of the GNU General Public License The OpenRISC 1000 tool chain must be available to allow the target programs to be build. This is documented on the OpenCores website (www.opencores.org) and in a separate Embecosm application note Embecosm Application Note 2. The OpenCores OpenRISC 1000 Simulator and Tool Chain: Installation Guide. . Caution ! This is a change from issue 1 of this application note, when precompiled versions were provided. All the changes described in this application note form part of Or1ksim 0.4.0. At the time writing, this version is not fully released. It's release candidate can be downloaded from the OpenCores website (www.opencores.org). The final, stable release is scheduled for the end of June 2010. The functions for all but the final chapter (Chapter 11) also form part of Or1ksim 0.3.0. Users wishing to build on this form of the library should modify the top level configure.ac and the makefile.am to remove reference to the jtag-soc directory and its files. A.1. Configuring and Building The software is built in its own directory, thus avoiding contaminating the source with the built programs. Assuming that the programs have been downloaded and unpacked in a directory named esp1-tlm2-or1ksim-examples-2.0, then configuration and building is achieved as follows. mkdir build cd build ../esp1-tlm2-or1ksim-examples-2.0/configure options make This will build all the SystemC models and the OpenRISC 1000 examples. A number of options to configure are essential to correct building. --target=or32-elf This specifies the target for the cross compiler used to compile the OpenRISC 1000 programs. Normally this is or32-elf. However an alternative may be required for custom compiler tool chains. --with- dirname is the directory where the Or1ksim libraries have been or1ksim=dirname installed. If this is not specified, then the value of the environment 96 Copyright © 2008, 2010 Embecosm Limited variable OR1KSIM_HOME will be used instead. If that is not defined, then the configuration will fail with an error message. --with- dirname is the directory of the SystemC installation. If this is not systemc=dirname> specified, then the value of the environment variable SYSTEMC will be used instead. If that is not defined, then the configuration will fail with an error message. Since it is normal to have SYSTEMC defined if it is installed, this option is usually not needed. --with- dirname is the directory of the SystemC TLM 2.0 installation. If this tlm=dirname> is not specified, then the value of the environment variable TLM_HOME will be used instead. If that is not defined, then the configuration will fail with an error message. Since it is normal to have TLM_HOME defined if TLM 2.0 is installed, this option is usually not needed. There are a wide range of other generic options available to control configuration. These are seldom used, but can be seen by using the following command. ../configure --help The code is documented throughout with doxygen;. The documentation can be generated by using the following command after configuration. make doxygen A.2. Building the Linux Kernel The Linux kernel is built as described in Embecosm Application Note 2. The OpenCores OpenRISC 1000 Simulator and Tool Chain: Installation Guide. [4]. This does require building the Or1ksim tool chain. This includes patches to the Linux kernel required to get it to work correctly on the Or1ksim ISS 97 Copyright © 2008, 2010 Embecosm Limited Appendix B. Running with Mac OS Robert Günzel of the Department of Integrated Circuit Design at the Technische Universität Braunschweig, Germany has managed to get both the OpenRISC tool chain and the examples in this application note running under Mac OS 10.4. There are three main issues that affect the Mac OS version 1. X11 is not running by default. 2. There is no pseudo-terminal multiplexer 3. Mac OS does not allow use of the F_SETOWN command on the file descriptor of a pseudo terminal slave. Thus SIGIO cannot be received, and there is thus no way of knowing when the user is typing inside the xterm. Robert has written a detailed application note explaining how to resolve these issues. At the time of writing it is available from chschroeder.gamiro.de/rg/or1ksim_macOS10.4.pdf. Check on the OpenCores website (under OpenRISC 1000 tool chain) for more recent updates. Resolving the third of the problems highlighted above required a substantial rewrite of the UART and terminal modules. In making this rewrite, Robert highlights various areas where efficiency of the model can be improved. 98 Copyright © 2008, 2010 Embecosm Limited Glossary 2-state Hardware logic model which is based only on logic high and logic low (binary 0 and binary 1) values. See also: 4-state 4-state Hardware logic model which considers unknown (X) and unproven (Z) values as well as logic high and logic low (binary 0 and binary 1). See also: 2-state Application Binary Interface The low-level interface between an application program and the operating system, thus ensuring binary compatibility between programs. C++ notoriously suffers from lack of agreed standards in this area. approximately timed In TLM 2.0 a modeling style where timing information is provided at the level of transactions representing the phases of data transfer in a specific bus protocol (for example the address and data phases of an AHB read or write). See also: loosely timed, phase backward transport path In TLM 2.0 non-blocking transport, the transport function which returns the response transaction from target to initiator. See also: transport function, forward transport path base class In object oriented programming a class from which other classes (the derived classes) are derived, inheriting variables and functions. Specifically a term favored by C++, also referred to as a parent class or super-class. See also: derived class big endian A description of the relationship between byte and word addressing on a computer architecture. In a big endian architecture, the least significant byte in a data word resides at the highest byte address (of the bytes in the word) in memory. The alternative is little endian addressing. See also: little endian blocking Within the context of TLM, a transaction which blocks the flow of control in the initiator until the target has completed the transaction request and responded. See also: non-blocking convenience socket A TLM 2.0 wrapper, providing for simple TLM communication based on C++ callbacks. 99 Copyright © 2008, 2010 Embecosm Limited derived class In object oriented programming a class which has inheriting variables and functions from another class (known as the base class). Specifically a term favored by C++, also referred to as a child class or subclass. See also: base class direct memory interface In hardware and software design communication between memory and a peripheral without the constant intervention of the processor. In TLM 2.0 communication between two threads (typically representing a processor and a memory block) by direct writing through a pointer to the memory rather than by a transactional exchange. See also: transport function, backward transport path forward transport path In TLM 2.0 non-blocking transport the transport function, which passes the opening transaction from initiator to target. See also: transport function, backward transport path generic payload Within TLM 2.0, a class suitable for use as payload for transactions. Recommended to maximize the interoperability of TLMs. See also: payload, generic payload extension generic payload extension Within TLM 2.0, a mechanism for extending the generic payload, thus allowing initiators and targets to specify additional information. In its simplest form, extensions are ignorable. Initiators and targets will work correctly if the extension is not present. Extensions may also be mandatory. This is for use where the additional information provided is necessary for initiators and targets to work correctly. See also: payload, generic payload extension Hardware Description Language (HDL) A language (Verilog and VHDL are the best known), which describes hardware. Can be used to describe both an actual chip and its test bench. initiator The initiator of a transactional exchange to a target. In TLM 2.0 an initiator module must implement an initiator socket of the appropriate type (blocking or non-blocking). See also: target Instruction Set Simulator (ISS) A software model of a CPU core instruction set. Typically completely models the instruction semantics, but not the full microarchitecture of a particular CPU implementation. Timing information may be just an instruction count, or may (as with the Or1ksim) offer some estimate of timing delays due to memory accesses, caching and virtual memory access. Joint Test Action Group (JTAG) JTAG is the usual name used for the IEEE 1149.1 standard entitled Standard Test Access Port and Boundary-Scan Architecture for test access ports used for testing printed circuit boards and chips using boundary scan. 100 Copyright © 2008, 2010 Embecosm Limited This standard allows external reading of state within the board or chip. It is thus a natural mechanism for debuggers to connect to embedded systems. little endian A description of the relationship between byte and word addressing on a computer architecture. In a little endian architecture, the least significant byte in a data word resides at the lowest byte address (of the bytes in the word) in memory. The alternative is big endian addressing. See also: big endian loosely timed In TLM 2.0 a modeling style, where timing information is provided at the level of transactions representing a complete data transfer across a hardware bus. See also: approximately timed memory management unit (MMU) A hardware component which maps virtual address references to physical memory addresses via a page lookup table. An exception handler may be required to bring non- existent memory pages into physical memory from backing storage when accessed. On a Harvard architecture (i.e. with separate logical instruction and data address spaces), two MMUs are typically needed. mutex An object in a program which provides a lock, used to negotiate mutual exclusion between multiple threads. SystemC provides a sc_mutex class to implement mutual exclusion between SystemC threads. non-blocking Within the context of TLM, a transaction which allows the flow of control in the initiator to continue immediately the transaction is sent. The response will be provided later by a transport call from the target back to the initiator.. See also: blocking OSCI See Open SystemC Initiative. passthrough A term describing a TLM 2.0 convenience socket which does not perform an automatic conversion between blocking and non-blocking transport. Potentially more efficient than the other types of convenience socket. See also: payload payload The data passed between threads by a transaction. See also: generic payload payload extension See generic payload extension. phase In TLM 2.0 approximately timed modeling, a transaction exchange representing a single phase of the specific bus protocol being modeled (for example the address phase of an AHB read or write). 101 Copyright © 2008, 2010 Embecosm Limited See also: approximately timed POSIX An IEEE standard for application programming interfaces and utilities for Unix/Linux operating systems. programmable interrupt controller (PIC) A hardware component which provides a large number of interrupt ports, which are mapped onto one or two interrupt ports on an actual processor. The PIC will provide a lookup table of interrupt service functions for its interrupts, which the interrupt service function on the processor can use to identify the correct handler to use. quantum In TLM 2.0 with temporal decoupling, the maximum time a thread may run ahead of the main system clock. This may be regulated by a quantum keeper. See also: temporal decoupling, quantum keeper quantum keeper In TLM 2.0 with temporal decoupling, an object which enforces the rule that threads may not run more than the quantum ahead of the main system clock See also: temporal decoupling, quantum singleton In object oriented programming, a class which can have at most one instance. Typically implemented by making the constructor private and providing an access function which instantiates the class on its first call and on all other calls returns a pointer to that instance. socket Within the context of TLM 2.0, a SystemC port and export combined with the associated interfaces for blocking and non-blocking transport, direct memory access and debug. See also: SystemC System on Chip (SoC) A silicon chip which includes one or more processor cores. SystemC A set of libraries and macros, which extend the C++ programming language to facilitate modeling of hardware. Standardized by the Open SystemC Initiative, who provide an open source reference implementation. See also: Open SystemC Initiative tagged socket A TLM 2.0 convenience socket, which incorporates a numerical tag to identify the socket in use. This allows a single callback function to handle multiple sockets, with the tag identifying the socket which caused the callback to be invoked. See also: socket target The responder to a transactional exchange initiated by an initiator. In TLM 2.0 a target module must implement a target socket of the appropriate type (blocking or non-blocking). See also: initiator 102 Copyright © 2008, 2010 Embecosm Limited temporal decoupling In TLM 2.0 the concept of allowing individual threads to run ahead of the main simulation time stamp. The maximum permitted time of run ahead is known as the quantum and may be regulated by a quantum keeper. See also: quantum, quantum keeper Test Access Port (TAP) The interface to a JTAG interface defined by IEEE 1149.1. thread In software, a logical parallel flow of control. In the context of SystemC, the main function of such a thread can be specified with the SC_THREAD macro. In SystemC a SC_THREAD is distinguished from a SC_METHOD because it can suspend execution with wait calls. See also: SystemC TLM An abbreviation for (depending on context) Transaction Level Model or Transaction Level Modeling. See also: Transaction Level Model, Transaction Level Modeling TLM 2.0 The OSCI standard interface for writing Transaction Level Models in SystemC. See also: Transaction Level Model, SystemC transaction In TLM modeling the exchange of data between two threads. Transaction An exchange of data (the payload) between two parallel processes. In TLM 2.0 this transaction occurs through SystemC ports implementing the TLM 2.0 interfaces, which are known as sockets. A full description is provided in Section 2.2. See also: payload, socket Transaction Level Model A software model in which the components of the model communicate by transferring information to and from each other (transactions). A full description is provided in Section 2.2. Transaction Level Modeling The process of writing software models using Transaction Level Model See also: Transaction Level Model transport function The C++ function which transfers data from an initiator to a target, and (for a non-blocking interface), the response back from the target to the initiator. Within the context of TLM 2.0 blocking and non-blocking transport interfaces are defined. See also: SystemC 103 Copyright © 2008, 2010 Embecosm Limited References [1] A loosely coupled parallel LISP execution system. John ffitch. International Specialist Seminar on the Design and Application of Parallel Digital Processors, 11-15 Apr 1988. pp 128-133. [2] SoC Debug Interface. Igor Mohor, Issue 3.0 OpenCores (www.opencores.org). 14 April 2004. Available from the OpenCores Subversion tree at http://www.opencores.org/ ocsvn/dbg_interface/dbg_interface/trunk/doc/DbgSupp.pdf. [3] IEEE 1149.1 Test Access Port. Igor Mohor, Issue 2.0. OpenCores (www.opencores.org). 30 January 2004. Available from the OpenCores Subversion tree at http:// www.opencores.org/ocsvn/jtag/jtag/trunk/tap/doc/jtag.pdf. [4] Embecosm Application Note 2. The OpenCores OpenRISC 1000 Simulator and Tool Chain: Installation Guide. Embecosm Limited, June 2008. [5] IEEE Standard SystemC Language Reference Manual. IEEE Computer Society, 1666-2005, 31 March, 2006. [6] OSCI TLM 2.0 User Manual. Open SystemC Initiative, June, 2008. [7] SystemC Version 2.0 User Guide. Open SystemC Initiative, 2002. 104 Copyright © 2008, 2010 Embecosm Limited