This manual describes the device model used by PSIM. In addition it describes the interfaces available to the programmer when implementing the model of a specific device.
A key feature of the standard IEEE1275-1994 - IEEE Standard for Boot (Initialization Configuration) Firmware (aka OpenBoot) is its use of a device tree to provide an abstract representation of a machines bus architecture.
In PSIM, this approach has been extended so that the tree structure also provides the framework upon which a target machines underying implementation can be modeled. For instance, an OpenBoot serial device would include a method for outputting a sequence of characters. A PSIM serial device would, in addition, include methods that model more concreate operations such as PIO accesses to the modeled devices registers, asynchronous DMA transfers of data to/from memory and the signalling events through the hardware interrupt network.
In the figure below appears what can best be described as a typical computer architecture. It is characterized by:
The bus topology of such an architecture can be represented abstractly as a tree. In such a representation, primary, secondary and tertary busses correspond to inner nodes and physical devices correspond to the leaves. A tree representation of the above architecture is illustrated below.
As with OpenBoot not all nodes in the device tree correspond to real devices. CPU devices seen in the above are an example of this. PSIM contains a processor engine that is separate from the device tree and interracts with it as described below.
During initialization, the device tree which defines the relationship between all devices and hence the system bus architecture created. The exact structure of the tree being defined through the use of command line options or a specification file.
Mentioned above was the fact that the execution engine modeling the behavour of a processor is an object separate from the device tree. The engine interracts with the device tree and hence the devices via the root (CORE) node.
During initialization, each device notifies its parent of any addressable regions (registers, memory) owned by the device that lie within the parents address space.
When the core device receives an access (read, write or execute) from a processor engine, it determines, using the specified address, the child device that access is destined for. It then passes the access on to the child device which is able to either resolve the access internally or propogate on down the device tree.
Clearly, while such a mechanism is simple, it incures significant overhead. To reduce this overhead, the most common case of a processor engine needing to access physical memory has been optomized.
As part of notifying the parent of an addressable region, a device also specifies if it can be treated as passive memory (RAM). Since the device has no need to be notified of access to such memory regions the parent is able to manage accesses to it. Consequently, the core will be directly managing memory sections that are typically accessed by a processor engine.
A device needing to perform a data transfer is handled in a similar fashion. It notifies its parent of the DMA request. That parent can then in turn either propogate the request further up the tree, handle it internally or reflect the access back down the tree to the destination device.
While a tree structure is sufficient for providing a frame work that models a system's bus architecture, the structure is not sufficient for modeling the more general relationships found in that systems interrupt netowrk.
PSIM, represents the system interrupt net using a directed graph. Each edge connecting a potential interrupt source and destination ports.
Illustrated in the figure below is a typical systems interrupt network - a programmable interrupt controler (MPIC) has a number of interrupt ports (int0 .. int3). Of these, only number zero (shared between a UART and MACIO pin A) and three (exclusivly connected to the MACIO's B pin) are used. The MPIC is in turn connected to each processor's interrupt (INT) port.
Within the network, the processor (CPU) nodes are especially important. They provide the link between the interrupt net and the instruction execution engine. For instance, the cpu node used in the PowerPC simulator has ports corresponding to each possible external asynchronous stimulus (i.e. hreset, sreset, int, smi, mci). When the cpu node is notified of an event on an interrupt ports it in turn notifies its corresponding processor's execution engine.
As with the device tree, the interrupt network is created during initialization. The exact network being specified through either command line options or a system description file. Devices are also permitted to add and remove additional edges to the interrupt network during the course of a simulation run.
OpenBoot firmware includes an abstrat interface to devices in the device tree. Firmware code first opens a device, creating a device instance, and is then able to apply abstract operations to the instance including reading and writing blocks of data and (for disk devices) seeking to a block address.
An important part of such a model is being able to safely pass identifiers (or handles) of devices and device instances between the simulated program and the simulator proper. OpenBoot refers to these handles as ihandles (device instances) and phandles (devices) and they are implemented as integer sized identifiers.
PSIM both includes methods to create an manipulate instances of devices and also operators that will safely map between a device instance (or device) and its corresponding ihandle (phandle).
In PSIM, the device tree is created and then initialized in stages. When using devices it is important to be clear what initialization the simulator assumes is being performed during each of these stages.
Firstly, each device is created in isolation (using the create from template method). Only after it has been created will a device be inserted into the tree ready for initialization.
Once the tree is created, it is initialized as follows:
The core device, positioned at the top of the device tree that models the architecure being simulated, acts as an interface between the processor engines and the modeled devices.
On the one side the processor engines issue read and write requests to the core (each request further catagorised as being for an instruction or data subunit) while on the other side, the core is receiving address configuration and DMA requests from child devices.
In the below a synopsis of the core object and device in PSIM is
given, details of the object can be found in the files
corefile.h and corefile.c.
At the heart of the interface between devices and processor engines is a single core object. This object, in turn, has two children:
The core ojbect manages two different types of address maps:
For callback maps it is possible to further order them by specifiying specifying a callback level (eg callback + 1).
When the core is resolving an access it searches each of the maps in order. First raw-memory and then callback maps (in assending order of level). This search order makes it possible for latter maps to overlap earlier ones. For instance, a device that wants to be notified of all accesses that are not covered by raw-memory maps could attach its self with an address range of the entire address space.
In addition, each attached address map as an associated set of access attributes (readable, writeable, executable) which are verified as part of resolving each access.
At present there is no method for removing address maps. That will be implemented in a future release.
The operation of mapping between an address and its destination device or memory array is currently implemented using a simple linked list. The posibility of replacing this list with a more powerfull data structure exists.
The device that corresponds to the core object is described separatly in the devices section.
Providing an interface between the processor engines and the core object are the access maps (core_map). Three access maps are provided, one for each of the possible access requests that can be generated by a processor.
A processor being able to request a read (or write) or write operation to any of the maps. Those operations can either be highly efficient (by specifying a specific transfer size) or generic (specifying a parameterized number of bytes).
Internally the core object takes the request, determines the approperiate attached address space that it should handle it passes it on.
As explained in earlier sections, the device, device instance, property and interrupts lie at the heart of PSIM's device model.
In the below a synopsis of the device object and the operations it
supports are given. Details of this object can be found in the
files device.h and device.c.
A device is able to determine its relationship to other devices within the tree. Operations include querying for a devices parent, sibling, child, name, and path (from the root).
Attached to a device are a number of properties. Each property has a size and type (both of which can be queried). A device is able to iterate over or query and set a properties value.
As with IEEE1275, a device can be opened, creating an instance. Instances provide more abstract interfaces to the underlying hardware. For example, the instance methods for a disk may include code that is able to interpret file systems found on disks. Such methods would there for allow the manipulation of files on the disks file system. The operations would be implemented using the basic block I/O model provided by the disk.
This model includes methods that faciliate the creation of device instance and (should a given device support it) standard operations on those instances.
Often devices require `out of band' operations to be performed.
For instance a pal device may need to notify a PCI bridge device
that an interrupt ack cycle needs to be performed on the PCI bus.
Within PSIM such operations are performed by using the generic
ioctl call device_ioctl().
So that errors originating from devices appear in a consistent
format, the device_error() function can be used. Formats and
outputs the error message before aborting the simulation
Devices should use this function to abort the simulation except when the abort reason leaves the simulation in a hazardous condition (for instance a failed malloc).
Both device nodes and device instances, in OpenBoot firmware have an external representation (phandles and ihandles) and these values are both stored in the device tree in property nodes and passed between the client program and the simulator during emulation calls.
To limit the potential risk associated with trusing `data' from the client program, the following mapping operators `safely' convert between the two representations
The device inherets certain event queue operations from the main