Difference between revisions of "Documentation"

From gem5
Jump to: navigation, search
m
 
(153 intermediate revisions by 15 users not shown)
Line 1: Line 1:
Outline for some new documentation. Maybe we should be doing this wit LaTeX and using pandoc (LaTeX->mediawiki converter)?
+
Welcome to the gem5 documentation. We've worked hard to add and organize everything in a more reasonable format, however we still haven't got to everything. All the documentation is a wiki, so we encourage you to add and edit sections as you find omissions and bugs.
  
==Getting Started==
+
For an overview, we have posted slides and most importantly '''video''' of a tutorial at HiPEAC Computer Systems Week. See [[Tutorials]].
  
===What is M5?===
+
'''Old Documentation:''' We have some old documentation and have been trying to move everything to the new format, but we haven't quite succeeded yet. If you don't find the answer you're looking for here, you might want to check [[OldDocumentation | the old documentation]].
  
M5 is a modular discrete event driven computer system simulator platform. That means that:
+
== Getting Started ==
 
+
# [[Introduction]] - A quick introduction to gem5.
# M5's components can be rearranged, parameterized, extended or replaced easily to suite your needs.
+
# [[Source Code]] - Information about the source code itself.
# It simulates the passing of time as a series of discrete events.
+
# [[Dependencies]] - Things you'll need that aren't part of gem5 itself.
# It's intended use is to simulate one or more computer systems in various ways.
+
# [[Build System]] - How to run or modify gem5's build system.
# It's more than just a simulator, it's a simulator platform that lets you use as many of its premade components as you want to build up your own simulation system.
+
# [[Download | Full System and Benchmark Files]] - Disk images for operating system and benchmark applications, and how to install them.
 
+
# [[gem5 101]] - Six part course covering all the basics of gem5 (and some advanced material too).
M5 is written primarily in C++ and python and most components are provided under a BSD style license. It can simulate a complete system with devices and an operating system in full system mode (FS mode), or user space only programs where system services are provided directly by the simulator in syscall emulation mode (SE mode). There are varying levels of support for executing Alpha, ARM, MIPS, Power, SPARC, and 64 bit x86 binaries on CPU models including two simple single CPI models, an out of order model, and an in order pipelined model. A memory system can be flexibly built out of caches and interconnects. Recently the Ruby simulator has been integrated with M5 to provide even better, more flexible memory system modeling.
 
 
 
There are many components and features not mentioned here, but from just this partial list it should be obvious that M5 is a sophisticated and capable simulation platform. Even with all M5 can do today, active development continues through the support of individuals and some companies, and new features are added and existing features improved on a regular basis. For the most up to date information you can check out the project's website at www.m5sim.org.
 
 
 
===Getting a copy===
 
 
 
M5's source code is managed using the mercurial revision control system. There are several repositories you may be interested in:
 
 
 
# m5 – The main repository is where active development takes place.
 
# m5-stable – A repository which lags behind “m5” repository but has basically the same contents. It’s usually better to use “m5” instead of “m5-stable”
 
# encumbered – A repository for extensions to M5 that are under a different, more restrictive license. Currently this only includes support for SimpleScalar's EIO trace format.
 
# linux-patches – A repository for patches to the linux kernel that modify it so it can be simulated more efficiently. These patches are optional, but it's a good idea to use them if possible to cut down on simulation run time.
 
 
 
To check out a copy, first, make sure you have mercurial installed on your system and that you can run the '''hg''' command. Then use '''hg clone''' to create your own local copy using the URL '''http://repo.m5sim.org/XXX''' where XXX is replaced by the name of the repository your interested in. For example, to check out the main repository, you'd use the command:
 
 
 
hg clone http://repo.m5sim.org/m5
 
 
 
You can find out more about mercurial and its commands using its built in help by running:
 
 
 
hg help
 
 
 
===Building===
 
 
 
M5 uses the scons build system which is based on python. To build the simulator binary, run scons from the top of the source directory with a target of the form '''build/<config>/<binary>''' where '''<config>''' is replaced with one of the predefined set of build parameters and '''<binary>''' is replaced with one of the possible m5 binary names. The predefined set of parameters determine build wide configuration settings that affect the behavior, composition, and capabilities of the binary being built. These include whether the simulator will run in FS or SE mode, if Ruby support is included, which ISA will be supported, which CPU models to build, and what coherence protocol Ruby should use. Examples are ARM_FS, X86_SE, and ALPHA_SE_MOESI_CMP_token. All of the available options can be found in the build_opts directory, and it should be fairly easy to see what each is for. We'll talk about the build system in more detail later. Valid binary names are m5.debug, m5.opt, m5.fast, and m5.prof. These binaries all have different properties suggested by their extension. m5.debug has optimization turned off to make debugging easier in tools like gdb, m5.opt has optimizations turned on but debug output and asserts left in, m5.fast removes those debugging tools, and m5.prof is built to use with gprof. Normally you'll want to use m5.opt. To build the simulator in syscall emulation mode with Alpha support, optimizations turned on, and debugging left in, you would run:
 
 
 
scons build/ALPHA_SE/m5.opt
 
 
 
In your source tree, you'd then find a new '''build/ALPHA_FS/''' directory with the requested '''m5.opt''' in it. For the rest of this chapter we'll assume this is the binary you're using.
 
 
 
===Running===
 
Now that you've built M5, it's time to try running it. An M5 command line is composed of four parts, the binary itself, options for M5, a configuration script to run, and then finally options for the configuration script. Several example configuration scripts are provided in the “configs/example” directory and are generally pretty powerful. You are encouraged to make your own scripts, but these are a good starting point. The example script we'll use in SE mode is called se.py and sets up a basic SE mode simulation for us. We'll tell it to run the hello world binary provided in the M5 source tree.
 
 
 
build/ALPHA_SE/m5.opt configs/example/se.py -c tests/test-progs/hello/bin/alpha/linux/hello
 
 
 
This builds up a simulated system, tells it to run the binary found at the location specified, and kicks off the simulation. As the binary runs, it's output is sent to the console by default and looks like this:
 
 
 
M5 Simulator System
 
 
   
 
   
Copyright (c) 2001-2008
+
== Running gem5 ==
The Regents of The University of Michigan
+
# [[Running gem5]] - Starting a simulation from the command line.
All Rights Reserved
+
# [[Output Files]] - Output obtained from simulation
+
# [[Checkpoints]], Fast Forwarding - How to create Checkpoints, restore the checkpointed state, fast forward simulation.
M5 compiled Feb 12 2011 20:43:55
+
# [[Regression Tests]] - Running the regression tests.
M5 revision e00ef55a2c49 7933 default tip
+
# [[SimObjects]] - What SimObjects are and how they work.
M5 started Feb 12 2011 20:45:47
+
# [[Configuration / Simulation Scripts]] - Explains how to configure the simulator and run simulations
M5 executing on fajita
+
# [[Visualization]] -- Tools to help visualize what is going on in a system
command line: build/ALPHA_SE/m5.opt configs/example/se.py -c tests/test-progs/hello/bin/alpha/linux/hello
 
Global frequency set at 1000000000000 ticks per second
 
0: system.remote_gdb.listener: listening for remote gdb #0 on port 7000
 
**** REAL SIMULATION ****
 
 
info: Entering event queue @ 0. Starting simulation...
 
info: Increasing stack size by one page.
 
Hello world!
 
hack: be nice to actually delete the event here
 
Exiting @ tick 3240000 because target called exit()
 
 
 
You can see a lot of output from the simulator itself, but the line “Hello world!” came from the simulated program. In this example we didn't provide any options to M5 itself. If we had, they would have gone on the command line between m5.opt and se.py. If you'd like to see what command line options are supported, you can pass the --help option to either M5 or the configuration script. The two groups of options are different, so make sure you keep track of whether they go before or after the configuration script.
 
 
 
===Asking for help===
 
 
 
M5 has two main mailing lists where you can ask for help or advice. m5-dev is for developers who are working on the main version of M5. This is the version that's distributed from the website and most likely what you'll base your own work off of. m5-users is a larger mailing list and is for people working on their own projects which are not, at least initially, going to be distributed as part of the official version of M5. Most of the time m5-users is the right mailing list to use. Most of the people on m5-dev are also on m5-users including all the main developers, and in addition many other members of the M5 community will see your post. That helps you because they might be able to answer your question, and it also helps them because they'll be able to see the answers people send you. To find more information about the mailing lists, to sign up, or to look through archived posts visit:
 
 
 
 
 
 
http://m5sim.org/wiki/index.php/Mailing_Lists
 
 
 
 
 
 
 
==Source Code==
 
 
 
===Tour of the tree===
 
 
 
These are the files and directories at the top of the tree:
 
 
 
 
 
 
AUTHORS  LICENSE  README  RELEASE_NOTES  SConstruct  build_opts  configs  ext  src  system  tests  util
 
 
 
 
 
 
AUTHORS, LICENSE, README are files with general information about the simulator. AUTHORS is a list of people who have historically contributed to M5. LICENSE has the license terms that applies to M5 as a whole, unless overridden by a more specific license. README has some very basic information introducing M5 and explaining how to get started.
 
 
 
 
 
 
The SConstruct file is part of the build system, as is the build_opts directory. build_opts holds files that define default settings for build different build configurations. These include X86_FS and MIPS_SE, for instance.
 
 
 
 
 
 
The configs directory is for simulation configuration scripts which are written in python. These are described in more detail later. The files in this directory help make writing configurations easier by providing some basic prepackaged functionality, and include a few examples which can be used directly or as a starting point for your own scripts.
 
 
 
 
 
 
The ext directory is for things M5 depends on but which aren’t actually part of M5. Specifically these are for dependencies that are harder to find, not likely to be available, or where a particular version is needed.
 
 
 
 
 
 
The src directory is where most of M5 is located. This is where all of the C++ and python source that contributes to the M5 binary is kept, excluding components in the ext directory.
 
 
 
 
 
 
The system directory is for the source for low level software like firmware or bootloaders for use in simulated systems. Currently this includes Alpha’s PAL and console code, and a simple bootloader for ARM.
 
 
 
 
 
 
The tests directory stores files related to M5’s regression tests. These include the scripts that build up the configurations used in the tests and reference outputs. Simple hello world binaries are also stored here, but other binaries need to be downloaded separately.
 
 
 
 
 
 
Finally, in the util directory are utility scripts, programs and useful files which are not part of the M5 binary but are generally useful when working on M5.
 
 
 
 
 
===Style rules===
 
 
 
 
 
===Generated files - where do they end up===
 
 
 
 
 
 
===.m5 config files===
 
 
 
 
===jobfile to run multiple jobs===
 
 
 
 
 
==Build System==
 
 
 
 
 
===Build targets===
 
 
 
===Configuration variables===
 
====What are they====
 
====What do they do====
 
====How do you get at their values====
 
 
 
===Running regressions===
 
===Adding files to the build===
 
 
 
===Using EXTRAS===
 
==SimObjects==
 
 
 
===The python side===
 
 
 
====Param types (table?)====
 
 
 
====Inheritance====
 
 
 
====Special attribute names====
 
 
 
====Rules for importing - how to get what====
 
====Pro tips - avoiding cycles, always descend from root, etc.====
 
===The C++ side===
 
====create functions====
 
 
 
====Stages of initialization====
 
 
 
====Header files to include====
 
==Configuration Scripts==
 
===SimObject hierarchy===
 
===Explanation of infrastructure scripts in configs===
 
 
 
===How to use se.py and fs.py.===
 
===How to use other top level scripts (what are they?)===
 
 
 
===Where M5 looks for files===
 
 
 
==General memory system==
 
===Ports system===
 
====Ports in general====
 
====Various port types====
 
====Packets====
 
====Requests====
 
====Atomic/Timing/Functional accesses====
 
 
 
==Classic memory system==
 
===MemObjects===
 
 
 
===Caches===
 
 
 
====Hooking them up====
 
 
 
====Parameters====
 
===Interconnects===
 
 
 
====Buses====
 
====Bridges====
 
 
 
====Anything else?====
 
 
 
===Coherence===
 
 
 
==Ruby (Tentative and Incomplete)==
 
=== How to use Ruby ? ===
 
    List of example on how to compile and run with common scenario goes here. No detailed discussion here.
 
    Only common cases with common parameter setting.
 
    Examples with FS/SE mode also should be mentioned here.
 
=== High level components of Ruby ===
 
  Need to talk about the overview of Ruby and what are the major components.
 
==== SLICC + Coherence protocols: ====
 
    Need to say what is SLICC and whats its purpose.
 
    Talk about high level strcture of a typical coherence protocol file, that SLICC uses to generate code.
 
    A simple example structure from protocol like MI_example can help here.
 
 
 
==== Protocol independent Memory components ====
 
# Cache Memory
 
# Replacement Policies
 
# Memory Controller
 
# Rubyport
 
# Profiler ?? (Depends upon Derek)
 
     
 
==== Networks ====
 
# SimpleNetwork
 
# Garnet
 
 
 
=== Implementation of Ruby ===
 
  Low level details goes here. Need to explain code directory structure as well.
 
 
 
==== SLICC ====
 
    Explain functionality/ capability of SLICC
 
    Talk about
 
    AST, Symbols, Parser and code generation in some details but NO need to cover every file and/or functions.
 
    Few examples should suffice.
 
 
 
==== Protocols ====
 
    Need to talk about each protocol being shipped. Need to talk about protocol specific configurations.
 
    NO need to explain every action or every state/events, but need to give overall idea and how it works
 
    and assumptions (if any).
 
 
 
=== Protocol Independent Memory components ===
 
    *We stopped here*
 
 
 
=== Networks ===
 
 
 
==Events==
 
 
 
===Event queue===
 
 
 
===EventManager objects (I don’t know a lot about these)===
 
===Event objects===
 
===Time sync===
 
==Devices==
 
 
 
===I/O device base classes===
 
 
 
===IDE===
 
===NICS===
 
===Timers===
 
===PCI devices===
 
 
 
===DMA devices===
 
===UARTs and serial terminals===
 
 
 
===Explanation of platforms and systems, how they’re related, and what they’re each for===
 
==Execution Basics==
 
===Predecoding===
 
===StaticInsts===
 
===Microcode support===
 
===ExecContext===
 
 
 
===ThreadContext===
 
===Faults===
 
 
 
==Architectural State==
 
 
 
===Registers===
 
====Register types - float, int, misc====
 
====Indexing - register spaces stuff====
 
===PCs===
 
 
 
==Address Translation==
 
===TLB management===
 
===Delayed translation===
 
===Page table walkers (defer to ISA discussion?)===
 
===Differences between SE and FS mode===
 
 
 
 
 
==CPUs==
 
===Simple CPU===
 
====Flow of execution====
 
 
 
====Sharing of code between atomic and timing====
 
===O3 CPU===
 
 
 
====Anatomy of the pipeline====
 
 
 
====DynInsts====
 
 
 
====Wires/delay====
 
====Squashing====
 
 
 
====Load/store handling====
 
====Renaming====
 
====etc.====
 
 
 
===InOrder (what to say here?)===
 
 
 
==Interrupts==
 
 
 
===Traditional handling with platform object===
 
 
 
===New, currently X86 only system===
 
====Interrupt sources/sinks/wires/pins====
 
====Interrupt messages====
 
===Interrupt managing objects in the CPU===
 
 
 
==ISA parser==
 
 
 
===Formats===
 
===operands===
 
 
 
===decode tree===
 
===let blocks===
 
 
 
===microcode assembler===
 
 
 
====microops====
 
 
 
====macroops====
 
====directives====
 
====rom object====
 
===Lots more stuff===
 
 
 
==Multiple ISA support==
 
===Switching header files===
 
===Specialized classes and functions===
 
===Matrix of supported ISA/mode/CPU combinations===
 
 
 
==Alpha Implementation==
 
 
 
==ARM Implementation==
 
 
 
===Supported features and modes===
 
===Thumb support===
 
===Special PC management===
 
 
 
==MIPS Implementation==
 
 
 
==Power Implementation==
 
==SPARC Implemenation==
 
 
 
===Supported features and modes===
 
 
 
==X86 Implementation==
 
 
 
===Microcode ISA===
 
==== Register Ops ====
 
 
 
These microops typically take two sources and produce one result. Most have a version that operates on only registers and a version which operates on registers and an immediate value. Some optionally set flags according to their operation. Some of them can be predicated.
 
 
 
===== Add =====
 
Addition.
 
 
 
====== add Dest, Src1, Src2 ======
 
Dest = Dest <- Src1 + Src2
 
 
 
Adds the contents of the Src1 and Src2 registers and puts the result in the Dest register.
 
 
 
====== addi Dest, Src1, Imm ======
 
Dest = Dest <- Src1 + Imm
 
 
 
Adds the contents of the Src1 register and the immediate Imm and puts the result in the Dest register.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, ZF, EZF, PF, AF, SF, and OF flags.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td>The carry out of the most significant bit.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>ZF and EZF</b> </td><td>Whether the result was zero.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>PF</b> </td><td> The parity of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>AF</b> </td><td> The carry from the 4th to 5th bit positions. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>SF</b> </td><td> The sign of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> Whether there was an overflow. </td>
 
  </tr>
 
</table>
 
 
 
===== Adc =====
 
 
 
Add with carry.
 
 
 
====== adc Dest, Src1, Src2 ======
 
Dest = Dest <- Src1 + Src2 + CF
 
 
 
Adds the contents of the Src1 and Src2 registers and the carry flag and puts the result in the Dest register.
 
 
 
====== adci Dest, Src1, Imm ======
 
Dest = Dest <- Src1 + Imm + CF
 
 
 
Adds the contents of the Src1 register, the immediate Imm, and the carry flag and puts the result in the Dest register.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, ZF, EZF, PF, AF, SF, and OF flags.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td>The carry out of the most significant bit.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>ZF and EZF</b> </td><td>Whether the result was zero.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>PF</b> </td><td> The parity of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>AF</b> </td><td> The carry from the 4th to 5th bit positions. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>SF</b> </td><td> The sign of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> Whether there was an overflow. </td>
 
  </tr>
 
</table>
 
 
 
===== Sub =====
 
 
 
Subtraction.
 
 
 
====== sub Dest, Src1, Src2 ======
 
Dest = Dest <- Src1 - Src2
 
 
 
Subtracts the contents of the Src2 register from the Src1 register and puts the result in the Dest register.
 
 
 
====== subi Dest, Src1, Imm ======
 
Dest = Dest <- Src1 - Imm
 
 
 
Subtracts the contents of the immediate Imm from the Src1 register and puts the result in the Dest register.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, ZF, EZF, PF, AF, SF, and OF flags.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td>The barrow into of the most significant bit.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>ZF and EZF</b> </td><td>Whether the result was zero.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>PF</b> </td><td> The parity of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>AF</b> </td><td> The barrow from the 5th to 4th bit positions. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>SF</b> </td><td> The sign of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> Whether there was an overflow. </td>
 
  </tr>
 
</table>
 
 
 
===== Sbb =====
 
 
 
Subtract with barrow.
 
 
 
====== sbb Dest, Src1, Src2 ======
 
Dest = Dest <- Src1 - Src2 - CF
 
 
 
Subtracts the contents of the Src2 register and the carry flag from the Src1 register and puts the result in the Dest register.
 
 
 
====== sbbi Dest, Src1, Imm ======
 
Dest = Dest <- Src1 - Imm - CF
 
 
 
Subtracts the immediate Imm and the carry flag from the Src1 register and puts the result in the Dest register.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, ZF, EZF, PF, AF, SF, and OF flags.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td>The barrow into of the most significant bit.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>ZF and EZF</b> </td><td>Whether the result was zero.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>PF</b> </td><td> The parity of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>AF</b> </td><td> The barrow from the 5th to 4th bit positions. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>SF</b> </td><td> The sign of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> Whether there was an overflow. </td>
 
  </tr>
 
</table>
 
 
 
===== Mul1s =====
 
 
 
Signed multiply.
 
 
 
====== mul1s Src1, Src2 ======
 
ProdHi:ProdLo = Src1 * Src2
 
 
 
Multiplies the unsigned contents of the Src1 and Src2 registers and puts the high and low portions of the product into the internal registers ProdHi and ProdLo, respectively.
 
 
 
====== mul1si Src1, Imm ======
 
ProdHi:ProdLo = Src1 * Imm
 
 
 
Multiplies the unsigned contents of the Src1 register and the immediate Imm and puts the high and low portions of the product into the internal registers ProdHi and ProdLo, respectively.
 
 
 
====== Flags ======
 
This microop does not set any flags.
 
 
 
===== Mul1u =====
 
 
 
Unsigned multiply.
 
 
 
====== mul1u Src1, Src2 ======
 
ProdHi:ProdLo = Src1 * Src2
 
 
 
Multiplies the unsigned contents of the Src1 and Src2 registers and puts the high and low portions of the product into the internal registers ProdHi and ProdLo, respectively.
 
 
 
====== mul1ui Src1, Imm ======
 
ProdHi:ProdLo = Src1 * Imm
 
 
 
Multiplies the unsigned contents of the Src1 register and the immediate Imm and puts the high and low portions of the product into the internal registers ProdHi and ProdLo, respectively.
 
 
 
====== Flags ======
 
This microop does not set any flags.
 
 
 
===== Mulel =====
 
 
 
Unload multiply result low.
 
 
 
====== mulel Dest ======
 
Dest = Dest <- ProdLo
 
 
 
Moves the value of the internal ProdLo register into the Dest register.
 
 
 
====== Flags ======
 
This microop does not set any flags.
 
 
 
===== Muleh =====
 
 
 
Unload multiply result high.
 
 
 
====== muleh Dest ======
 
Dest = Dest <- ProdHi
 
 
 
Moves the value of the internal ProdHi register into the Dest register.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, and OF flags.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td> Whether ProdHi is non-zero</td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> Whether ProdHi is non-zero. </td>
 
  </tr>
 
</table>
 
 
 
===== Div1 =====
 
 
 
First stage of division.
 
 
 
====== div1 Src1, Src2 ======
 
Quotient * Src2 + Remainder = Src1
 
Divisor = Src2
 
 
 
Begins a division operation where the contents of SrcReg1 is the high part of the dividend and the contents of SrcReg2 is the divisor. The remainder from this partial division is put in the internal register Remainder. The quotient is put in the internal register Quotient. The divisor is put in the internal register Divisor.
 
 
 
====== div1i Src1, Imm: ======
 
Quotient * Imm + Remainder = Src1
 
Divisor = Imm
 
 
 
Begins a division operation where the contents of SrcReg1 is the high part of the dividend and the immediate Imm is the divisor. The remainder from this partial division is put in the internal register Remainder. The quotient is put in the internal register Quotient. The divisor is put in the internal register Divisor.
 
 
 
====== Flags ======
 
This microop does not set any flags.
 
 
 
===== Div2 =====
 
 
 
Second and later stages of division.
 
 
 
====== div2 Dest, Src1, Src2 ======
 
Quotient * Divisor + Remainder = original Remainder with bits shifted in from Src1
 
 
 
Dest = Dest <- Src2 - number of bits shifted in above
 
 
 
Performs subsequent steps of division following a div1 instruction. The contents of the register Src1 is the low portion of the dividend. The contents of the register Src2 denote the number of bits in Src1 that have not yet been used before this step in the division. Dest is set to the number of bits in Src1 that have not been used after this step. The internal registers Quotient, Divisor, and Remainder are updated by this instruction.
 
 
 
If there are no remaining bits in Src1, this instruction does nothing except optionally compute flags.
 
 
 
====== div2i Dest, Src1, Imm ======
 
Quotient * Divisor + Remainder = original Remainder with bits shifted in from Src1
 
 
 
Dest = Dest <- Imm - number of bits shifted in above
 
 
 
Performs subsequent steps of division following a div1 instruction. The contents of the register Src1 is the low portion of the dividend. The immediate Imm denotes the number of bits in Src1 that have not yet been used before this step in the division. Dest is set to the number of bits in Src1 that have not been used after this step. The internal registers Quotient, Divisor, and Remainder are updated by this instruction.
 
 
 
If there are no remaining bits in Src1, this instruction does nothing except optionally compute flags.
 
 
 
====== Flags ======
 
This microop optionally sets the EZF flag.
 
 
 
<table>
 
  <tr>
 
    <td> <b>EZF</b> </td><td> Whether there are any remaining bits in Src1 after this step. </td>
 
  </tr>
 
</table>
 
 
 
===== Divq =====
 
 
 
Unload division quotient.
 
 
 
====== divq Dest ======
 
Dest = Dest <- Quotient
 
 
 
Moves the value of the internal Quotient register into the Dest register.
 
 
 
====== Flags ======
 
This microop does not set any flags.
 
 
 
===== Divr =====
 
 
 
Unload division remainder.
 
 
 
====== divr Dest ======
 
Dest = Dest <- Remainder
 
 
 
Moves the value of the internal Remainder register into the Dest register.
 
 
 
====== Flags ======
 
This microop does not set any flags.
 
 
 
===== Or =====
 
 
 
Logical or.
 
 
 
====== or Dest, Src1, Src2 ======
 
Dest = Dest <- Src1 | Src2
 
 
 
Computes the bitwise or of the contents of the Src1 and Src2 registers and puts the result in the Dest register.
 
 
 
====== ori Dest, Src1, Imm ======
 
Dest = Dest <- Src1 | Imm
 
 
 
Computes the bitwise or of the contents of the Src1 register and the immediate Imm and puts the result in the Dest register.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, ZF, EZF, PF, AF, SF, and OF flags.
 
There is nothing that prevents computing a value for the AF flag, but it's value will be meaningless.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td>Cleared</td>
 
  </tr>
 
  <tr>
 
    <td> <b>ZF and EZF</b> </td><td>Whether the result was zero.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>PF</b> </td><td> The parity of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>AF</b> </td><td> Undefined </td>
 
  </tr>
 
  <tr>
 
    <td> <b>SF</b> </td><td> The sign of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> Cleared </td>
 
  </tr>
 
</table>
 
 
 
===== And =====
 
 
 
Logical And
 
 
 
====== and Dest, Src1, Src2 ======
 
Dest = Dest <- Src1 & Src2
 
 
 
Computes the bitwise and of the contents of the Src1 and Src2 registers and puts the result in the Dest register.
 
 
 
====== andi Dest, Src1, Imm ======
 
Dest = Dest <- Src1 & Imm
 
 
 
Computes the bitwise and of the contents of the Src1 register and the immediate Imm and puts the result in the Dest register.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, ZF, EZF, PF, AF, SF, and OF flags.
 
There is nothing that prevents computing a value for the AF flag, but it's value will be meaningless.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td>Cleared</td>
 
  </tr>
 
  <tr>
 
    <td> <b>ZF and EZF</b> </td><td>Whether the result was zero.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>PF</b> </td><td> The parity of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>AF</b> </td><td> Undefined </td>
 
  </tr>
 
  <tr>
 
    <td> <b>SF</b> </td><td> The sign of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> Cleared </td>
 
  </tr>
 
</table>
 
 
 
===== Xor =====
 
 
 
Logical exclusive or.
 
 
 
====== xor Dest, Src1, Src2 ======
 
Dest = Dest <- Src1 | Src2
 
 
 
Computes the bitwise xor of the contents of the Src1 and Src2 registers and puts the result in the Dest register.
 
 
 
====== xori Dest, Src1, Imm ======
 
Dest = Dest <- Src1 | Imm
 
 
 
Computes the bitwise xor of the contents of the Src1 register and the immediate Imm and puts the result in the Dest register.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, ZF, EZF, PF, AF, SF, and OF flags.
 
There is nothing that prevents computing a value for the AF flag, but it's value will be meaningless.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td>Cleared</td>
 
  </tr>
 
  <tr>
 
    <td> <b>ZF and EZF</b> </td><td>Whether the result was zero.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>PF</b> </td><td> The parity of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>AF</b> </td><td> Undefined </td>
 
  </tr>
 
  <tr>
 
    <td> <b>SF</b> </td><td> The sign of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> Cleared </td>
 
  </tr>
 
</table>
 
 
 
===== Sll =====
 
 
 
Logical left shift.
 
 
 
====== sll Dest, Src1, Src2 ======
 
Dest = Dest <- Src1 << Src2
 
 
 
Shifts the contents of the Src1 register to the left by the value in the Src2 register and writes the result into the Dest register. The shift amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== slli Dest, Src1, Imm ======
 
Dest = Dest <- Src1 << Imm
 
 
 
Shifts the contents of the Src1 register to the left by the value in the immediate Imm and writes the result into the Dest register. The shift amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, and OF flags. If the shift amount is zero, no flags are modified.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td>The last bit shifted out of the result.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> The exclusive or of the what this instruction would set the CF flag to (if requested) and the most significant bit of the result </td>
 
  </tr>
 
</table>
 
 
 
===== Srl =====
 
 
 
Logical right shift.
 
 
 
====== srl Dest, Src1, Src2 ======
 
Dest = Dest <- Src1 >>(logical) Src2
 
 
 
Shifts the contents of the Src1 register to the right by the value in the Src2 register and writes the result into the Dest register. Bits which are shifted in sign extend the result. The shift amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== srli Dest, Src1, Imm ======
 
Dest = Dest <- Src1 >>(logical) Imm
 
 
 
Shifts the contents of the Src1 register to the right by the value in the immediate Imm and writes the result into the Dest register. Bits which are shifted in sign extend the result. The shift amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, and OF flags. If the shift amount is zero, no flags are modified.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td>The last bit shifted out of the result.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> The most significant bit of the original value to shift </td>
 
  </tr>
 
</table>
 
 
 
===== Sra =====
 
 
 
Arithmetic right shift.
 
 
 
====== sra Dest, Src1, Src2 ======
 
Dest = Dest <- Src1 >>(arithmetic) Src2
 
 
 
Shifts the contents of the Src1 register to the right by the value in the Src2 register and writes the result into the Dest register. Bits which are shifted in zero extend the result. The shift amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== srai Dest, Src1, Imm ======
 
Dest = Dest <- Src1 >>(arithmetic) Imm
 
 
 
Shifts the contents of the Src1 register to the right by the value in the immediate Imm and writes the result into the Dest register. Bits which are shifted in zero extend the result. The shift amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, and OF flags. If the shift amount is zero, no flags are modified.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td>The last bit shifted out of the result.</td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> Cleared </td>
 
  </tr>
 
</table>
 
 
 
===== Ror =====
 
 
 
Rotate right.
 
 
 
====== ror Dest, Src1, Src2 ======
 
Rotates the contents of the Src1 register to the right by the value in the Src2 register and writes the result into the Dest register. The rotate amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== rori Dest, Src1, Imm ======
 
Rotates the contents of the Src1 register to the right by the value in the immediate Imm and writes the result into the Dest register. The rotate amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, and OF flags. If the rotate amount is zero, no flags are modified.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td> The most significant bit of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> The exclusive or of the two most significant bits of the original value. </td>
 
  </tr>
 
</table>
 
 
 
===== Rcr =====
 
 
 
Rotate right through carry.
 
 
 
====== rcr Dest, Src1, Src2 ======
 
Rotates the contents of the Src1 register through the carry flag and to the right by the value in the Src2 register and writes the result into the Dest register. The rotate amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== rcri Dest, Src1, Imm ======
 
Rotates the contents of the Src1 register through the carry flag and to the right by the value in the immediate Imm and writes the result into the Dest register. The rotate amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, and OF flags. If the rotate amount is zero, no flags are modified.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td> The last bit shifted out of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> The exclusive or of the CF flag before the rotate and the most significant bit of the original value. </td>
 
  </tr>
 
</table>
 
 
 
===== Rol =====
 
 
 
Rotate left.
 
 
 
====== rol Dest, Src1, Src2 ======
 
Rotates the contents of the Src1 register to the left by the value in the Src2 register and writes the result into the Dest register. The rotate amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== roli Dest, Src1, Imm ======
 
Rotates the contents of the Src1 register to the left by the value in the immediate Imm and writes the result into the Dest register. The rotate amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, and OF flags. If the rotate amount is zero, no flags are modified.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td> The least significant bit of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> The exclusive or of the most and least significant bits of the result. </td>
 
  </tr>
 
</table>
 
 
 
===== Rcl =====
 
 
 
Rotate left through carry.
 
 
 
====== rcl Dest, Src1, Src2 ======
 
Rotates the contents of the Src1 register through the carry flag and to the left by the value in the Src2 register and writes the result into the Dest register. The rotate amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== rcli Dest, Src1, Imm ======
 
Rotates the contents of the Src1 register through the carry flag and to the left by the value in the immediate Imm and writes the result into the Dest register. The rotate amount is truncated to either 5 or 6 bits, depending on the operand size.
 
 
 
====== Flags ======
 
This microop optionally sets the CF, ECF, and OF flags. If the rotate amount is zero, no flags are modified.
 
 
 
<table>
 
  <tr>
 
    <td> <b>CF and ECF</b> </td><td> The last bit rotated out of the result. </td>
 
  </tr>
 
  <tr>
 
    <td> <b>OF</b> </td><td> The exclusive or of CF before the rotate and most significant bit of the result. </td>
 
  </tr>
 
</table>
 
 
 
===== Mov =====
 
 
 
Move.
 
 
 
====== mov Dest, Src1, Src2 ======
 
Dest = Src1 <- Src2
 
 
 
Merge the contents of the Src2 register into the contents of Src1 and put the result into the Dest register.
 
 
 
====== movi Dest, Src1, Imm ======
 
Dest = Src1 <- Imm
 
 
 
Merge the contents of the immediate Imm into the contents of Src1 and put the results into the Dest register.
 
 
 
====== Flags ======
 
This microop does not set any flags. It is optionally predicated.
 
 
 
===== Sext =====
 
 
 
Sign extend.
 
 
 
====== sext Dest, Src1, Imm ======
 
Dest = Dest <- sign_extend(Src1, Imm)
 
 
 
Sign extend the value in the Src1 register starting at the bit position in the immediate Imm, and put the result in the Dest register.
 
 
 
====== Flags ======
 
This microop does not set any flags.
 
 
 
===== Zext =====
 
 
 
Zero extend.
 
 
 
====== zext Dest, Src1, Imm ======
 
Dest = Dest <- zero_extend(Src1, Imm)
 
 
 
Zero extend the value in the Src1 register starting at the bit position in the immediate Imm, and put the result in the Dest register.
 
 
 
====== Flags ======
 
This microop does not set any flags.
 
 
 
===== Ruflag =====
 
 
 
Read user flag.
 
 
 
====== ruflag Dest, Imm ======
 
Reads the user level flag stored in the bit position specified by the immediate Imm and stores it in the register Dest.
 
 
 
The mapping between values of Imm and user level flags is show in the following table.
 
<table>
 
  <tr>
 
    <td> 0 </td><td> CF (carry flag) </td>
 
  </tr>
 
  <tr>
 
    <td> 2 </td><td> PF (parity flag) </td>
 
  </tr>
 
  <tr>
 
    <td> 3 </td><td> ECF (emulation carry flag) </td>
 
  </tr>
 
  <tr>
 
    <td> 4 </td><td> AF (auxiliary carry flag) </td>
 
  </tr>
 
  <tr>
 
    <td> 5 </td><td> EZF (emulation zero flag) </td>
 
  </tr>
 
  <tr>
 
    <td> 6 </td><td> ZF (zero flag) </td>
 
  </tr>
 
  <tr>
 
    <td> 7 </td><td> SF (sign flag) </td>
 
  </tr>
 
  <tr>
 
    <td> 10 </td><td> DF (direction flag) </td>
 
  </tr>
 
  <tr>
 
    <td> 11 </td><td> OF (overflow flag) </td>
 
  </tr>
 
</table>
 
 
 
====== Flags ======
 
The EZF flag is always set. In the future this may become optional.
 
 
 
<table>
 
  <tr>
 
    <td> <b>EZF</b> </td><td> Set if the value of the flag read was zero. </td>
 
  </tr>
 
</table>
 
 
 
===== Ruflags =====
 
 
 
Read all user flags.
 
 
 
====== ruflags Dest ======
 
Dest = user flags
 
 
 
Store the user level flags into the Dest register.
 
 
 
====== Flags ======
 
This microop does not set any flags.
 
 
 
===== Wruflags =====
 
 
 
Write all user flags.
 
 
 
====== wruflags Src1, Src2 ======
 
user flags = Src1 ^ Src2
 
 
 
Set the user level flags to the exclusive or of the Src1 and Src2 registers.
 
 
 
====== wruflagsi Src1, Imm ======
 
user flags = Src1 ^ Imm
 
 
 
Set the user level flags to the exclusive or of the Src1 register and the immediate Imm.
 
 
 
====== Flags ======
 
See above.
 
 
 
===== Rdip =====
 
 
 
Read the instruction pointer.
 
 
 
====== rdip Dest ======
 
Dest = rIP
 
 
 
Set the Dest register to the current value of rIP.
 
 
 
====== Flags ======
 
This microop does not set any flags.
 
 
 
===== Wrip =====
 
 
 
Write the instruction pointer.
 
 
 
====== wrip Src1, Src2 ======
 
rIP = Src1 + Src2
 
 
 
Set the rIP to the sum of the Src1 and Src2 registers. This causes a macroop branch at the end of the current macroop.
 
 
 
====== wripi Src1, Imm ======
 
micropc = Src1 + Imm
 
 
 
Set the rIP to the sum of the Src1 register and immediate Imm. This causes a macroop branch at the end of the current macroop.
 
 
 
====== Flags ======
 
This microop does not set any flags. It is optionally predicated.
 
 
 
===== Chks =====
 
Check selector.
 
 
 
Not yet implemented.
 
 
 
==== Load/Store Ops ====
 
 
 
===== Ld =====
 
Load.
 
====== ld Data, Seg, Sib, Disp ======
 
Loads the integer register Data from memory.
 
 
 
===== Ldf =====
 
Load floating point.
 
====== ldf Data, Seg, Sib, Disp ======
 
Loads the floating point register Data from memory.
 
 
 
===== Ldm =====
 
Load multimedia.
 
====== ldm Data, Seg, Sib, Disp ======
 
Load the multimedia register Data from memory.
 
This is not implemented and may never be.
 
 
 
===== Ldst =====
 
Load with store check.
 
====== Ldst Data, Seg, Sib, Disp ======
 
Load the integer register Data from memory while also checking if a store to that location would succeed.
 
This is not implemented currently.
 
 
 
===== Ldstl =====
 
Load with store check, locked.
 
====== Ldst Data, Seg, Sib, Disp ======
 
Load the integer register Data from memory while also checking if a store to that location would succeed, and also provide the semantics of the "LOCK" instruction prefix.
 
This is not implemented currently.
 
 
 
===== St =====
 
Store.
 
====== st Data, Seg, Sib, Disp ======
 
Stores the integer register Data to memory.
 
 
 
===== Stf =====
 
Store floating point.
 
====== stf Data, Seg, Sib, Disp ======
 
Stores the floating point register Data to memory.
 
 
 
===== Stm =====
 
Store multimedia.
 
====== stm Data, Seg, Sib, Disp ======
 
Store the multimedia register Data to memory.
 
This is not implemented and may never be.
 
 
 
===== Stupd =====
 
Deprecated
 
 
 
===== Lea =====
 
Load effective address.
 
====== lea Data, Seg, Sib, Disp ======
 
Calculates the address for this combination of parameters and stores it in Data.
 
 
 
===== Cda =====
 
Check data address.
 
====== cda Seg, Sib, Disp ======
 
Check whether the data address is valid.
 
This is not implemented currently.
 
 
 
===== Cdaf =====
 
CDA with cache line flush.
 
====== cdaf Seg, Sib, Disp ======
 
Check whether the data address is valid, and flush cache lines
 
This is not implemented currently.
 
 
 
===== Cia =====
 
Check instruction address.
 
====== cia Seg, Sib, Disp ======
 
Check whether the instruction address is valid.
 
This is not implemented currently.
 
 
 
===== Tia =====
 
TLB invalidate address
 
====== tia Seg, Sib, Disp ======
 
Invalidate the tlb entry which corresponds to this address.
 
This is not implemented currently.
 
 
 
==== Load immediate Op ====
 
 
 
===== Limm =====
 
====== limm Dest, Imm ======
 
Stores the 64 bit immediate Imm into the integer register Dest.
 
 
 
==== Floating Point Ops ====
 
 
 
===== Movfp =====
 
====== movfp Dest, Src ======
 
Dest = Src
 
 
 
Move the contents of the floating point register Src into the floating point register Dest.
 
 
 
This instruction is predicated.
 
 
 
===== Xorfp =====
 
====== xorfp Dest, Src1, Src2 ======
 
Dest = Src1 ^ Src2
 
 
 
Compute the bitwise exclusive or of the floating point registers Src1 and Src2 and put the result in the floating point register Dest.
 
 
 
===== Sqrtfp =====
 
====== sqrtfp Dest, Src ======
 
Dest = sqrt(Src)
 
 
 
Compute the square root of the floating point register Src and put the result in floating point register Dest.
 
 
 
===== Addfp =====
 
====== addfp Dest, Src1, Src2 ======
 
Dest = Src1 + Src2
 
 
 
Compute the sum of the floating point registers Src1 and Src2 and put the result in the floating point register Dest.
 
 
 
===== Subfp =====
 
====== subfp Dest, Src1, Src2 ======
 
Dest = Src1 - Src2
 
 
 
Compute the difference of the floating point registers Src1 and Src2 and put the result in the floating point register Dest.
 
 
 
===== Mulfp =====
 
====== mulfp Dest, Src1, Src2 ======
 
Dest = Src1 * Src2
 
 
 
Compute the product of the floating point registers Src1 and Src2 and put the result in the floating point register Dest.
 
 
 
===== Divfp =====
 
====== divfp Dest, Src1, Src2 ======
 
Dest = Src1 / Src2
 
 
 
Divide Src1 by Src2 and put the result in the floating point register Dest.
 
 
 
===== Compfp =====
 
====== compfp Src1, Src2 ======
 
Compare floating point registers Src1 and Src2.
 
 
 
===== Cvtf_i2d =====
 
====== cvtf_i2d Dest, Src ======
 
Convert integer register Src into a double floating point value and store the result in the lower part of Dest.
 
 
 
===== Cvtf_i2d_hi =====
 
====== cvtf_i2d_hi Dest, Src ======
 
Convert integer register Src into a double floating point value and store the result in the upper part of Dest.
 
 
 
===== Cvtf_d2i =====
 
====== cvtf_d2i Dest, Src ======
 
Convert floating point register Src into an integer value and store the result in the integer register Dest.
 
 
 
==== Special Ops ====
 
 
 
===== Fault =====
 
Generate a fault.
 
====== fault fault_code ======
 
Uses the C++ code fault_code to allocate a Fault object to return.
 
 
 
===== Lddha =====
 
Set the default handler for a fault.
 
This is not implemented currently.
 
 
 
===== Ldaha =====
 
Set the alternate handler for a fault
 
This is not implemented currently.
 
 
 
==== Sequencing Ops ====
 
These microops are used for control flow withing microcode
 
 
 
===== Br =====
 
 
 
Microcode branch. This is never considered the last microop of a sequence. If it appears at the end of a macroop, it is assumed that it branches to microcode in the ROM.
 
 
 
====== br target ======
 
micropc = target
 
 
 
Set the micropc to the 16 bit immediate target.
 
 
 
====== Flags ======
 
This microop does not set any flags. It is optionally predicated.
 
 
 
===== Eret =====
 
 
 
Return from emulation. This instruction is always considered the last microop in a sequence. When executing from the ROM, it is the only way to return to normal instruction decoding.
 
 
 
====== eret ======
 
 
 
Return from emulation.
 
 
 
====== Flags ======
 
This microop does not set any flags. It is optionally predicated.
 
 
 
===Macroop specialization===
 
===Platform objects===
 
===Physical memory space allocation===
 
===Microcode registers and other hidden implementation details===
 
===Supported features and modes===
 
 
 
==Pseudo Instructions==
 
 
 
===List of pseudo instructions and what they do===
 
===How to get at and use them from a binary, script, etc.===
 
 
 
==SE mode==
 
 
 
===Loading binaries===
 
===System call instruction handling===
 
 
 
===Implementation of various system calls===
 
 
 
===Limitations===
 
  
==Statistics (don’t know what to say here)==
+
== Workloads ==
 +
# [[Compiling workloads | Compiling]] - How to compile workloads to run within gem5.
 +
# [[Multiprogrammed workloads | Multi-programmed]] - Multiprogrammed workloads in SE mode.
 +
# [[Multithreaded workloads | Multi-threaded]] - Multithreaded workloads in SE mode.
 +
# Benchmark suites
 +
## [[SPEC benchmarks | SPEC]] - SPEC benchmarks in SE mode.
 +
## [[Splash benchmarks | SPLASH]] - SPLASH benchmarks (SE or FS mode?)
 +
## [[PARSEC benchmarks | PARSEC]] - PARSEC benchmarks in FS mode.
 +
# [[Disk images]] - Setting up a disk image.
 +
# [[Linux kernel]] - Preparing a Linux kernel for use in gem5.
 +
# [[m5ops]] - How to talk to the simulator from within a simulated workload.
  
==Utility Code==
+
== Development ==
 +
# [[Functional Testers]]
 +
#* [[Directed Test]]
 +
#* [[memtest]]
 +
#* [[Garnet Synthetic Traffic]]
 +
#* [[Ruby Random Tester]]
 +
# Debugging - features designed specifically to help you figure out what's going on.
 +
#* [[Trace Based Debugging | Trace-Based Debugging]]: figuring out what gem5 is doing using debug traces
 +
#* [[Debugger Based Debugging | Debugger-Based Debugging]]: using gdb to debug gem5
 +
#* [[Debugging Simulated Code]]: debugging the system/program running on top of gem5
 +
# [[Coding Style]]
 +
# [[Adding Functionality]]
 +
#* [[Managing Local Changes with Mercurial Queues]]
 +
#* [[Extras | Compiling Additional Code with EXTRAS]]
 +
# [[Source Code Documentation]]
 +
# [[Submitting Contributions]]
  
===Bitfield functions===
+
== Infrastructure ==
 +
# [[Events]]
 +
# [[Statistics]]
 +
# [[Utility Code]]
 +
# [[Serialization]]
  
===BitUnion classes===
+
== Memory System ==
===FastAlloc===
+
# [[General Memory System]] - Shared infrastructure between the Classic and Ruby models
===IntMath===
+
# [[Classic Memory System]] - Description of our easily configurable, crossbar-based memory system
===panic, warn, etc., when to use what===
+
# [[Ruby]] - Description of our detailed and flexible memory system.  Lots of information here.
===random number generation===
+
#* [[SLICC|SLICC Overview]]
===reference counting pointers===
+
#* [[GEMS-gem5_SLICC_Transition_Guide|SLICC Transistion Guide]]
 +
#* [[Interconnection_Network]]
  
==Debugging==
+
== Full System ==
===Trace flags===
+
# [[Devices]]
===State trace/Tracer objects===
+
## [[IDE Devices]]
===Remote GDB support===
+
## [[NIC Devices]]
===tracediff===
+
## [[Timers]]
===Regressions===
+
## [[UARTs and serial terminals]]
===Unit tests===
+
# [[Disks and Disk Images]]
 +
# [[Interrupts]]
  
==Development Tools/Contributing==
+
== Syscall Emulation ==
 +
# [[SE Mode]]
  
===Mercurial queues===
+
== Instruction Execution ==
===Review board===
+
# [[Execution Basics]]
===Mercurial repo browser===
+
# [[Architectural State]]
 +
# [[Address Translation]]
 +
== CPU Models ==
 +
# [[SimpleCPU | Simple CPU Model]]
 +
# [[O3CPU | Out-of-Order CPU Model]]
 +
# [[InOrder | In Order CPU Model]]
 +
# [[TraceCPU | Trace CPU Model ]]
 +
# [[Adding a New CPU Model]]
  
==External Dependencies==
+
== ISA Implementations ==
===Required versions===
+
# [[Architecture Support]] -- What architectures are supported by gem5 and what features of them are implemented
===Things in ext===
+
# [[Status Matrix]]
 +
# [[ISA Parser]]
 +
# [[Alpha Implementation]]
 +
# [[ARM Implementation]]
 +
# [[MIPS Implementation]]
 +
# [[Power Implementation]]
 +
# [[SPARC Implementation]]
 +
# [[X86 Implementation]]
 +
# [[Defining ISAs]]

Latest revision as of 06:22, 28 November 2016

Welcome to the gem5 documentation. We've worked hard to add and organize everything in a more reasonable format, however we still haven't got to everything. All the documentation is a wiki, so we encourage you to add and edit sections as you find omissions and bugs.

For an overview, we have posted slides and most importantly video of a tutorial at HiPEAC Computer Systems Week. See Tutorials.

Old Documentation: We have some old documentation and have been trying to move everything to the new format, but we haven't quite succeeded yet. If you don't find the answer you're looking for here, you might want to check the old documentation.

Getting Started

  1. Introduction - A quick introduction to gem5.
  2. Source Code - Information about the source code itself.
  3. Dependencies - Things you'll need that aren't part of gem5 itself.
  4. Build System - How to run or modify gem5's build system.
  5. Full System and Benchmark Files - Disk images for operating system and benchmark applications, and how to install them.
  6. gem5 101 - Six part course covering all the basics of gem5 (and some advanced material too).

Running gem5

  1. Running gem5 - Starting a simulation from the command line.
  2. Output Files - Output obtained from simulation
  3. Checkpoints, Fast Forwarding - How to create Checkpoints, restore the checkpointed state, fast forward simulation.
  4. Regression Tests - Running the regression tests.
  5. SimObjects - What SimObjects are and how they work.
  6. Configuration / Simulation Scripts - Explains how to configure the simulator and run simulations
  7. Visualization -- Tools to help visualize what is going on in a system

Workloads

  1. Compiling - How to compile workloads to run within gem5.
  2. Multi-programmed - Multiprogrammed workloads in SE mode.
  3. Multi-threaded - Multithreaded workloads in SE mode.
  4. Benchmark suites
    1. SPEC - SPEC benchmarks in SE mode.
    2. SPLASH - SPLASH benchmarks (SE or FS mode?)
    3. PARSEC - PARSEC benchmarks in FS mode.
  5. Disk images - Setting up a disk image.
  6. Linux kernel - Preparing a Linux kernel for use in gem5.
  7. m5ops - How to talk to the simulator from within a simulated workload.

Development

  1. Functional Testers
  2. Debugging - features designed specifically to help you figure out what's going on.
  3. Coding Style
  4. Adding Functionality
  5. Source Code Documentation
  6. Submitting Contributions

Infrastructure

  1. Events
  2. Statistics
  3. Utility Code
  4. Serialization

Memory System

  1. General Memory System - Shared infrastructure between the Classic and Ruby models
  2. Classic Memory System - Description of our easily configurable, crossbar-based memory system
  3. Ruby - Description of our detailed and flexible memory system. Lots of information here.

Full System

  1. Devices
    1. IDE Devices
    2. NIC Devices
    3. Timers
    4. UARTs and serial terminals
  2. Disks and Disk Images
  3. Interrupts

Syscall Emulation

  1. SE Mode

Instruction Execution

  1. Execution Basics
  2. Architectural State
  3. Address Translation

CPU Models

  1. Simple CPU Model
  2. Out-of-Order CPU Model
  3. In Order CPU Model
  4. Trace CPU Model
  5. Adding a New CPU Model

ISA Implementations

  1. Architecture Support -- What architectures are supported by gem5 and what features of them are implemented
  2. Status Matrix
  3. ISA Parser
  4. Alpha Implementation
  5. ARM Implementation
  6. MIPS Implementation
  7. Power Implementation
  8. SPARC Implementation
  9. X86 Implementation
  10. Defining ISAs