|
OpenRISC 1000: Architectural Simulator
Introduction
The aim of this project is to develop and maintain an OpenRISC 1000 architectural simulator. Or1ksim is a generic OpenRISC 1000 architecture simulator capable of emulating OpenRISC based computer systems. This project was static for 2.5 years until mid-2008, but is now active again. The latest candidate release (0.3.0rc2) was released in November 2008. This brings Or1ksim in line with the current OpenRISC 1000 architecture and adds
- support for the GDB Remote Serial Protocol
- support for GDB 6.8
- an OSCI TLM 2.0 SystemC interface
Or1ksim provides several unique features:
- Free, open source code
- High level, fast, architecture simulation that allows early code analysis and system performance evaluation
- All major models of OpenCores peripheral and system controller cores supported
- Easy addition of new peripheral models
- Remote debugging through a network socket with the GNU Debugger (GDB)
- Support for different environments (memory configurations and sizes, OR1K processor model, configuration of peripheral devices)
Development Release
The development release of Or1ksim is version 0.3.0rc2. It may be downloaded here This is now open for beta testing. Further release candidates may be made in the light of testing. The objective is to have a stable release 0.3.0 by the end of 2009. Release 0.3.0rc2 includes a User Guide (download here), which also has some information on the internals, and fixes a number of bugs. The code is now consistently structured to GNU standards and has been commented to take advantage of Doxygen. A PDF version of the Doxygen analysis may be downloaded here. Feeback to the OpenRISC mailing list on this release candidate is welcome. Issues of particular concern are:
- is the Remote Serial Protocol working as expected
- should the "stall" and "unstall" commands remain?
- should the Custom Unit Compiler be discontinued?
- should dynamic execution remain an option?
Stable Release
The current stable release of Or1ksim is version 0.2.0. It may be downloaded here. It features:
- Or1ksim simulates 32-bit part of the OpenRISC 1000 architecture
- Or1ksim support for 64-bit part of the OpenRISC is not yet available
- Supported OpenCores peripherals: vga/lcd, uart, dma, ethernet, general purpose io, memory controller, ps2 interface (keyboard only), OCIDEC (partially)
The stable release must be patched to support GDB 6.8. This patch also fixes a number of outstanding bugs, and brings the behavior into line with the current OpenRISC 1000 Verilog. The patch may be downloaded here.Since the simulator is no longer only a processor simulator, but also supports peripherals, it is now used also as the ORPsoc simulator. For example the VGA peripheral can output images like the following figure, showing uClinux booting on a VGA console: 
Downloading Or1ksim
You may also checkout the latetest version from CVS using:
cvs -d :pserver:cvs@cvs.opencores.org:/home/oc/cvs -z9 co or1k/or1ksim
(Note that the checkout process may take a while). The current top of CVS tree is not considered stable. Build it using the process described below, but remember that some patching may be needed to get a working binary. Binaries of Or1ksim are not available. Building the stable version is straightforward.
Installation
Building or1ksim was historically tested under RedHat 7.0 GNU/Linux. The development version, 0.3.0rc2 has been tested under Fedora 9 Linux, Centos 4.7 Linux and Cygwin 1.5.25. The stable version 0.2.0 with patches for GDB 6.8 have been tested under Fedora 9 Linux. Development Version. The procedure to build and install the development version of or1ksim is the following: First get the sources for Or1ksim 0.3.0rc2 using the instructions above and unpack. Assuming the unpacked source is in directory or1ksim-0.3.0rc2, and the code is to be installed in /opt/or1ksim, build and install the simulator as follows.
mkdir builddir_or1ksim
cd builddir_or1ksim
../or1ksim-0.c.0rc2/configure --target=or32-uclinux --prefix=/opt/or1ksim
make all
make install
export PATH=/opt/or1ksim/bin:$PATH
Stable version. The procedure to build and install the stable version of Or1ksim is the following: First get the sources for Or1ksim 0.2.0 using the instructions above and apply the patch for GDB 6.8. This patch also fixes a number of outstanding bugs Warning. There is a known bug on older versions of Linux when using an Xterm as the UART output (triggered at least on RHEL4 and Centos 4.6). To fix this, edit the file peripheral/channels/xterm.c and comment out all the lines between #if defined(I_PUSH) and #endif . This should be done after the patch described above has been applied. This bug will be fixed in a future release.Assuming the patched source is in directory or1ksim-0.2.0, and the code is to be installed in /opt/or1ksim, build and install the simulator as follows.
mkdir builddir_or1ksim
cd builddir_or1ksim
../or1ksim-0.2.0/configure --target=or32-uclinux --prefix=/opt/or1ksim
make all
make install
export PATH=/opt/or1ksim/bin:$PATH
More detailed information on installing Or1ksim (and the rest of the OpenRISC 1000 tool chain) with examples of the simulator in use may be found in the Embecosm Application Note EAN2: The OpenCores OpenRISC 1000 Simulator and Tool Chain: Installation Guide
Documentation
Or1ksim 0.3.0rc2 includes a new User Guide. This provides information on using and configurating Or1ksim, both as a standalone tool and as a library. It also gives some guidance on the internal structure of Or1ksim. It may be downloaded (PDF) here. The documentation can also be generated from the source to give HTML, info, DVI and PostScript. A summary of the command options can be seen with or32-uclinux-sim --help For booting Linux, use the sim.cfg file in the root directory of the Linux distribution with the command or32-uclinux-sim -f sim.cfg vmlinux More details on Linux for OpenRISC 1000 may be found on the tool chain page.The Embecosm Application Note EAN2 described in the Installation section above includes examples of using Or1ksim. The User Guide for the OpenRISC 1000 port of GDB 6.8 includes details of running Or1ksim with GDB. The code is documented to take advantage of the Doxygen documentation system, which provides automatically generated, structured documentation on the files, functions and data-structures of the entire program, together with their interrelationships. This may be generated in PDF form or as HTML. The PDF version derived from the Or1ksim 0.3.0rc2 release may be found here. Documentation would benefit from extending, particularly with tutorial material and with more detail on the internals of the program (see Contributing, below).
Contributing
We are constantly looking for developers to help in the development of the simulator, though you don't need to be a highly skilled developer to do so. Many (very usefull) projects may be performed without any C programming knowledge or without an intricate knowledge of the openrisc architecture. A few items to get you started:
We are constantly short of manpower to maintain the website. If you feel you're up to doing some webdesign, don't hold back any longer! Some general ideas to get you started (by no means exhausive): Add a more indepth discussion of the simulator for the introduction, provide some more screen shots showing off some interesting features of the sim, or any other good idea you have in mind.
- Extend the documentation:
Or1ksim now has a User Guide. However this would benefit from some good tutorial material. This is an excellent task for anyone new to or1ksim. This would involve documenting, in the form of a well narated passage (not point form!), how to get started using or1ksim, the general pitfalls that someone new to or1ksim may take and how to avoid those, some neat examples of how to use some of the more "cool" peripherals of the sim (esp. how to make use of the Ethernet peripheral), documenting the interface that is used to implement the peripherals, documenting the more arcane features of the simulator, the various execution models, branch prediction, super scaler emulation and in general what they are usefull for. If you have any questions about the above, don't hesitate to contact us on the mailing list.
- Develop a proper testsuite:
The current testsuite (in directory testsuite) is "rudimentary". It is just a collection of programs giving basic exercise to each peripheral in turn. It has been known to report failure, when there is no problem and often reports success when there are serious problems.The system would benefit from a complete rewrite, probably using DejaGNU, to properly exercise all the features of the architecture.
- Test or1ksim on non-Linux platforms (various UNIX and Cygwin platforms) :
The developers do not have acess to every operating system out there. We would like the simulator to run on as many platforms as possible. If you are running on anything other than linux you would help us a great deal if you could periodically check if the simulator builds (and works) on your prefered platform, reporting any failures to the mailing list.
- Add additional models of OpenCores peripherals and system controllers:
- Support for running the sim on 64-bit architectures:
There are numerous places in the sim where the length of the basic C types are assumed to be a certain length (esp. the "long" type), which breaks running the simulator on 64-bit architectures.
The development version of the simulator has numerous speed otimisations already, though this is a never ending task. The uart for example needs lots of work so that uart_clock16 does not need to be called so often. The ethernet could use similar optimisations. This task generally streches quite deep into the simulator and is not concentrated into any single area.
- Support for 64-bit part of OpenRISC 1000:
This is a very big (and fun) piece of work. This does not only involve writting emulation of the 64-bit architecture. It also requires modifying the exsisting processor units such that they support 64-bit types (mmu/caches/debug unit/etc.).
If you have a suggestion that you'd like to see developed, feel free to send it to the mailing list so that may be added to the list and somebody may start working on it.
SystemC TLM 2.0 Interface for Or1ksim
An experimental wrapper has been developed by Embecosm to provide an OSCI SystemC TLM 2.0 interface to Or1ksim. The application note describing this may be downloaded here and the software downloaded here.
Past Contributors
These are the people who are currently not working on the or1ksim, but have contributed in significant ways in the past:
Developers
The team currently working on or1ksim:
Mailing List / Discussion Forum
To participate in the development or simply to discuss or1ksim issues and to report bugs, go to the openrisc mailing list. To subscribe to the list, follow the mailing list subscribe instructions.
Page Maintainer(s)
This web page is maintained by Jeremy Bennett and Marcus Erlandsson.
|
Browse
