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.

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.

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:

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.

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.

There are two principal types of TLM 2.0 transport function.

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.

TLM 2.0 considers two levels of timing detail.

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 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 Section 4 Section 6 and Section 7 uses this approach to create an untimed model. This is then refined in Section 8 to add synchronous timing information and in Section 9 to add temporal decoupling.

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

In Section 4 the TLM 2.0 wrapper for the Or1ksim ISS is developed. In Section 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 2.

Figure 2.  Testing the TLM 2.0 wrapper for the OpenRISC 1000 Or1ksim.

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. The model is built up in stages starting with the ISS wrapper module developed in Section 4. In sections Section 6 and Section 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 Section 8 and temporal decoupling to improve performance is added in Section 9. .

Figure 3.  Simple SoC based on the OpenRISC 1000 Or1ksim.

To run Linux (see Section 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 4.

Figure 4.  Simple SoC based on the OpenRISC 1000 Or1ksim with interrupts and MMU enabled.

The code for all the SystemC models is provided in the sysc_models sub-directory of the code distribution. See Appendix A for details of obtaining the code.

Code for example programs which run on the models can be found in in the sysc_models/progs_or32 sub-directory of the code distribution. 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. [2] for more information on building the OpenRISC 1000 tool chain.

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.

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

It is not intended that the reader should have to understand the internal workings of Or1ksim. The changes described in this application note are provided as a patch file, which can be applied to generate a fully working, modified version of the ISS. More information is provided in Appendix A.

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.

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)^[3].

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.

Both the sysc_models and progs_or32 directory contain make files which will build the programs and Doxygen documentation, if the appropriate tools are available.

These files will need editing. In general the main make file, Makefile includes an operating system specific make file (linux.mk for Linux, win32.mk for Microsoft Windows), because of the very substantial differences in behavior between GNU make and Microsoft nmake.

In particular the SystemC model builds need to know the location of the Or1ksim binaries, libraries and include files, which should be set in the environment variable OR1KSIM. If left unset it will default to /opt/or1ksim.

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:

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

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.

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

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.

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

The default destructor is sufficient here. The module has no tidying up to do on termination.

The only public interface is the TLM 2.0 simple initiator convenience socket, dataBus. The TLM 2.0 convenience sockets are templated with

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;

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.

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.

  static unsigned long int  staticReadUpcall( void              *instancePtr,
                                              unsigned long int  addr,
                                              unsigned long int  mask );

  static void               staticWriteUpcall( void              *instancePtr,
                                               unsigned long int  addr,
                                               unsigned long int  mask,
                                               unsigned long int  wdata );

  uint32_t                  readUpcall( sc_dt::uint64  addr,
                                        uint32_t       mask );

  void                      writeUpcall( sc_dt::uint64  addr,
                                         uint32_t       mask,
                                         uint32_t       wdata );

	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.

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, good object oriented design separates class definition from class 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.

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() */

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

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:

unsigned long int
Or1ksimSC::staticReadUpcall( void              *instancePtr,
                             unsigned long int  addr,
                             unsigned long int  mask )
{
  Or1ksimSC *classPtr = (Or1ksimSC *)instancePtr;

  return (unsigned long int)classPtr->readUpcall( (sc_dt::uint64)addr,
                                                  (uint32_t)mask );
}       // staticReadUpcall()

The address is cast to the SystemC native 64-bit type, which is always used in TLM 2.0 for addresses. The mask and result (and write data for staticWriteUpcall are cast to the POSIX uint32_t fixed length type to avoid any ambiguity over size^[4].

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.

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.

Both payload and data are declared as local (automatic) variables, i.e. on the stack. This is fine with a blocking transport function, since they will remain valid for the duration of the transaction. The data and mask are both encoded in the four bytes of a POSIX uint32_t.

Caution

Using local variables is this way would not be appropriate with a non-blocking socket, since the initiator function could return before the result of the transaction is received back from the target. TLM 2.0 requires that the payload, data and mask fields all remain valid for the duration of the complete transaction, so in this case the variables would need to be allocated and deleted from the heap.

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 Section 6 when other threads are added to model peripherals.

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"

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

The public interface is the single simple target convenience socket.

  tlm_utils::simple_target_socket<LoggerSC>  loggerPort;

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.

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"

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

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. Endianism issues due 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()

The program includes the main TLM 2.0 header and the header of the two modules which will be used:

#include "tlm.h"
#include "Or1ksimSC.h"
#include "LoggerSC.h"

The program takes two arguments, an Or1ksim configuration file (described further in Section 5.5) and a binary image to execute on the Or1ksim ISS (see Section 5.4).

int  sc_main( int   argc,
              char *argv[] )
{
  if( argc != 3 ) {
    fprintf( stderr, "Usage: TestSC <config_file> <image_file>\n" );
    exit( 1 );
  }

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" );

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

Once the model is instantiated, simulation is invoked to run forever.

  sc_core::sc_start();

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.

The memory mapped address is defined in the configuration of Or1ksim (see Section 5.5) 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;

The details of each write are logged and the value then written. (In the absence of a printf, the logging is necessarily cumbersome).

  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;

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.

The program is compiled with the utility functions (in utils.c) and a small boot loader (in start.s) which defines a _start function which invokes main. The linker arguments are chosen to make the program load from start of memory, with the _start function sitting at the OpenRISC 1000 reset vector (0x100).

The SystemC modules are each compiled with access to the Or1ksim, SystemC and TLM 2.0 header directories. It is also essential that SC_INCLUDE_DYNAMIC_PROCESSES is defined when using TLM 2.0:

g++ -ggdb -DSC_INCLUDE_DYNAMIC_PROCESSES -I$OR1KSIM_HOME/include \
    -I$SYSTEMC_HOME/include -I$TLM_HOME/include/tlm -c TestSC.cpp
g++ -ggdb -DSC_INCLUDE_DYNAMIC_PROCESSES -I$OR1KSIM_HOME/include \
    -I$SYSTEMC_HOME/include -I$TLM_HOME/include/tlm -c Or1ksimSC.cpp
g++ -ggdb -DSC_INCLUDE_DYNAMIC_PROCESSES -I$OR1KSIM_HOME/include \
    -I$SYSTEMC_HOME/include -I$TLM_HOME/include/tlm -c LoggerSC.cpp

The final linking must include the SystemC library, and since the Or1ksim library includes some shared objects, linker directions to find those shared objects (-Wl,--rpath,$OR1KSIM_HOME).

g++ -ggdb -DSC_INCLUDE_DYNAMIC_PROCESSES TestSC.o Or1ksimSC.o LoggerSC.o \
    -Wl,--rpath,$OR1KSIM_HOME/lib -L$OR1KSIM_HOME/lib \
    -L$SYSTEMC_HOME/lib-linux -lsim -lsystemc -o TestSC

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. [2]. 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

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.

$ ./TestSC ../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
Reading script file from '../simple.cfg'...

   ... <Or1ksim initialization messages>

Writing byte 0xa5 to address 0x090000000
Logging
  Command:      Write
  Address:      0x90000000
  Byte enables: 0x000000ff
  Data:         0x000000a5
  Delay:        0.000000000s

Writing half word 0xbeef to address 0x090000002
Logging
  Command:      Write
  Address:      0x90000000
  Byte enables: 0xffff0000
  Data:         0xbeef0000
  Delay:        0.000000000s

   ... <More test program output>

Logging
  Command:      Read
  Address:      0x90000004
  Byte enables: 0xffffffff
  Delay:        0.000000000s

Read full word 0x0 from address 0x090000004
exit(0)
@reset : cycles 0, insn #0
@exit  : cycles 26921, insn #13854
 diff  : cycles 26921, insn #13854
$ 

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.

	Note
	The Or1ksim ISS can be configured to model big-endian architectures. The TLM 2.0 payloads are always packed with data using the endianism of the model. If the exercise were repeated with a big-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.

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 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 Section 7) will offer the complementary arrangement.

	Note
	A SystemC buffer (sc_buffer) is used rather than a (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 Section 10.

The divisor latch affects the baud rate, which will affect timing of transfers. This will be covered in a later section (see Section 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 Section 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.

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.

The additional function is straightforward, since endianism is a compile time constant in the Or1ksim ISS.

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 endianism of the underlying CPU model is defined

bool  isLittleEndian();

The doTrans 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 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 function^[5].

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 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 Section 5 worked without this call to wait, because it had no thread—all its functionality was in the blocking transaction callback function.

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

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

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 endianism of the model.

  UartSC( sc_core::sc_module_name  name,
          unsigned long int        _clockRate,
          bool                     _isLittleEndian );

The interfaces to the UART model are:

No external port is provided for the interrupt at this stage. That will be added in Section 10

A SystemC thread is provided busThread 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.

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.

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.

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

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 the interrupt enable register bits) indicating which interrupts are currently pending. A flag initialized at construction records the model endianism, isLittleEndian.

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:

  sc_core::sc_event  txReceived;

The callback function notifies on this event, to trigger behavior in the busThread.

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

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

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.

The second thread, rxThread sits in a perpetual loop, waiting for characters to be received on 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.

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

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:

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:

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 Section 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 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 readable^[6].

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.

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.

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.

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.

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.3.2). The thread can safely make an operating system read to get the character, knowing that data is definitely available.

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.

The structure of the main program (SimpleSoC.cpp) is similar to that for the logger test program (see Section 5.3). 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"

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

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

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:

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

Compilation uses the same command lines as the standalone test of the Or1ksim wrapper with the logger (see Section 5.5), but this time links in the UART and terminal; rather than the logger.

	Important
	Since Or1ksimExt is a derived class of Or1ksim, linking should include the compiled base class, Or1ksimSC.o as well as the derived class, Or1ksimExtSC.o.

The Or1ksim configuration is also unchanged. Like the logger, the UART registers start at address 0x90000000 and are 8 bytes long.

Running the model requires specifying the configuration file (unchanged) and the binary executable (this time the UART loop back program).

./SimpleSocSC ../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 8.

$ ./SimpleSocSC ../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
Reading script file from '../simple.cfg'...

   ... <Or1ksim initialization messages>

Read: 'F'
Read: 'a'
Read: 'r'

   ... <more Or1ksim output>

Read: '!'
Read: '!'
Read: '!'

At the same time the characters will be echoed on the xterm, as shown in figure Figure 9.

Figure 9.  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.

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 rxThread in UartSC, to print out the time when a character is received from the terminal^[8].

void
UartSC::rxThread()
{
  // Loop woken up when a character is written into the buffer from the terminal.

  while( true ) {
    regs.rbr  = rx.read();                      // Blocking read of the data

    sc_core::sc_time  now = sc_core::sc_time_stamp();
    printf( "Char read at    %12.9f sec\n", now.to_seconds());

    set( regs.lsr, UART_LSR_DR );               // Mark data ready

    if( isSet( regs.ier, UART_IER_ERBFI ) ) {   // Send interrupt if enabled
      genIntr( UART_IIR_RDI );
    }
  }
}       // rxThread()

Similarly edit the rxThread in TermSC, to print out the time when a character is received from the UART.

void
TermSC::rxThread()
{
  while( true ) {
    unsigned char  ch = rx.read();      // Blocking read from the buffer

    xtermWrite( ch );                   // Write it to the screen

    sc_core::sc_time  now = sc_core::sc_time_stamp();
    printf( "Char written at %12.9f sec\n", now.to_seconds());
  }
}       // rxThread()

In both cases the C standard IO header will be needed at the top of the file (UartSC.cpp and TermSC.cpp):

#include <stdio.h>

The model can now be rerun as before, and will print out precise timing (use of 9 decimal places ensures that granularity at least as fine as the 100MHz CPU clock will be seen). The output is shown in Figure 10.

$ ./SimpleSocSC ../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
Reading script file from '../simple.cfg'...

   ... <Or1ksim initialization messages>

Char read at    0.000000000 sec
Read: 'F'
Char written at 0.000000000 sec
Char read at    0.000000000 sec
Read: 'a'
Char written at 0.000000000 sec
Char read at    0.000000000 sec
Read: 'r'

   ... <Lots more output>

As can be seen all the reads and writes occur at time zero.

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 point^[9].

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.

The new Or1ksim library call to give the clock rate is wrapped by a public function^[10].

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

However, since this is a synchronized model, the target will have called wait to model the time taken to read or write, so 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

  or1ksim_set_time_point();

The utility getClockRate is a simple wrapper for the underlying Or1ksim library function (see Section 8.2.1). It will be used in the main program (see Section 8.5).

unsigned long int
Or1ksimSyncSC::getClockRate()
{
  return or1ksim_clock_rate();

}       // getClockRate()

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.

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

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 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 custom constructor calls the base class constructor to set the module name. The body of the constructor is 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

TLM 2.0 defines four different timing entities to describe temporal decoupling. These are illustrated in Figure 12.

Figure 12.  Diagram illustrating temporal decoupling

TLM 2.0 defines a singleton class^[12] which can be used to hold the system global quantum. A set of functions to manipulate the global quantum are provided.

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.

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 is 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 calculates 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 offset^[13]. 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.

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.

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.

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 quantum keeper for the ISS thread, issQk is defined.

  tlm_utils::tlm_quantumkeeper  issQk;

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.

  tlm::tlm_global_quantum &refTgq = 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. Ensure that it is assigned to a reference variable (declared as &refTgq here) of type tlm::tlm_global_quantum. Use of a plain variable would be valid code, but make a copy of the quantum keeper, so subsequent calls to set would not actually set the singleton instance. An example of the dangers of reference variables in C++ and why singleton accessors should return pointers, not references.

The main thread function, run is reimplemented to ensure that 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.

Since the local quantum is only available through the singleton tlm::tlm_global_quantum a reference to that instance is obtained for use throughout this function:

  tlm::tlm_global_quantum &refTgq = tlm::tlm_global_quantum::instance();

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 =
      refTgq.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.

    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.

  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.

  tlm::tlm_global_quantum &refTgq = tlm::tlm_global_quantum::instance();
  sc_core::sc_time  timeLeft      =
    refTgq.compute_local_quantum() - issQk.get_local_time();

  or1ksim_reset_duration ( timeLeft.to_seconds() );

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

  switch( payload.get_command() ) {

  case tlm::TLM_READ_COMMAND:
    delay += sc_core::sc_time( UART_READ_NS, sc_core::SC_NS );
    break;

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

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

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

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.

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: Installation Guide. [2]. 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. 

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 ^[14]).

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.