Difference between revisions of "Documentation"

From gem5
Jump to: navigation, search
(→‎Param types (table?))
Line 155: Line 155:
 
===The python side===
 
===The python side===
  
−
====Param types (table?)====
+
====Param types ====
 +
The information below came from src/python/m5/params.py and src/python/m5/util/convert.py. Reference those files for the most up to date information.
 +
 
 +
{| border="1" cellpadding="10"
 +
! Python Type Name !! C++ Type !! Format !! Notes
 +
|-
 +
| String || std::string || ||
 +
|-
 +
| Int || int || || 32 bits
 +
|-
 +
| Unsigned || unsigned || || 32 bits
 +
|-
 +
| Int8 || int8_t || ||
 +
|-
 +
| UInt8 || uint8_t || ||
 +
|-
 +
| Int16 || int16_t || ||
 +
|-
 +
| UInt16 || uint16_t || ||
 +
|-
 +
| Int32 || int32_t || ||
 +
|-
 +
| UInt32 || uint32_t || ||
 +
|-
 +
| Int64 || int64_t || ||
 +
|-
 +
| UInt64 || uint64_t || ||
 +
|-
 +
| Counter || Counter || ||
 +
|-
 +
| Tick || Tick || ||
 +
|-
 +
| TcpPort || uint16_t || ||
 +
|-
 +
| UdpPort || uint16_t || ||
 +
|-
 +
| Percent || int || || Between 0 and 100.
 +
|-
 +
| Float || double || ||
 +
|-
 +
| MemorySize || uint64_t
 +
| A string formatted as [value][unit] where value is a base 10 number and unit is one of the following:
 +
* PB => pebibytes
 +
* TB => tebibytes
 +
* GB => gibibytes
 +
* MB => mebibytes
 +
* kB => kibibytes
 +
* B => bytes
 +
| kibi, mebi, etc. are true powers of 2.
 +
|-
 +
| MemorySize32 || uint32_t
 +
| See "MemorySize" above. || See "MemorySize" above.
 +
|-
 +
| Addr || Addr || See "MemorySize" above
 +
| See "MemorySize" above. Also, an addr may be specified as a string with units, or a raw integer value.
 +
|-
 +
| Range || Range<[type]>, type is int by default ||
 +
| Defined as a "start" and "end" or "size" value. Exactly one of "end" or "size" is recognized as a keyword argument. A positional argument will be treated as "end", and "size" arguments are convected to "end" internally by adding to "start" and subtracting one.
 +
|-
 +
| AddrRange || Range<Addr> || || See "Range" above.
 +
|-
 +
| TickRange || Range<Tick> || || See "Range" above.
 +
|-
 +
| Bool || bool || ||
 +
|-
 +
| EthernetAddr || Net::EthAddr
 +
| Six pairs of 2 digit hex values seperated by ":"s, for instance "01:23:45:67:89:AB"
 +
| May be set to NextEthernetAddr. All EthernetAddrs set to NextEthernetAddr will be assigned to incremental ethernet addresses starting with 00:90:00:00:00:01.
 +
|-
 +
| IpAddress || Net::IpAddress
 +
| Four decimal values between 0 and 255 separated by "."s, for instance "1.23.45.67", or an integer where the leftmost component is the most significant byte.
 +
|
 +
|-
 +
| IpNetmask || Net::IpNetmask
 +
| A string representation of an IpAddress followed by either "/n" where n is a decimal value from 0 to 32 or "/e.f.g.h" where e-h are integer values between 0 and 255 and where when represented as binary from left to right the number is all 1s and the all 0s. The ip and netmask can also be passed in as positional or keyword arguments where the ip is an integer as described in IpAddress, and the netmask is a decimal value from 0 to 32.
 +
|
 +
|-
 +
| IpWithPort || Net::IpWithPort
 +
| A string representation of an IpAddress followed by ":p" where p is a decimal value from 0 to 65535. The ip and port can also be passed in as positional or keyword arguments where the ip is an integer as described in IpAddress, and the port is a decimal value from 0 to 65535.
 +
|
 +
|-
 +
| Time || tm || May be a Python struct_time, int, long, datetime, or date, the string "Now" or "Today", or a string parseable by Python's strptime with one of the following formats:
 +
* "%a %b %d %H:%M:%S %Z %Y"
 +
* "%a %b %d %H:%M:%S %Z %Y"
 +
* "%Y/%m/%d %H:%M:%S"
 +
* "%Y/%m/%d %H:%M"
 +
* "%Y/%m/%d"
 +
* "%m/%d/%Y %H:%M:%S"
 +
* "%m/%d/%Y %H:%M"
 +
* "%m/%d/%Y"
 +
* "%m/%d/%y %H:%M:%S"
 +
* "%m/%d/%y %H:%M"
 +
* "%m/%d/%y"
 +
|
 +
|-
 +
| subclasses of Enum || enum named after the parameter type || A string defined as part of the enum || This description applies to all enum parameter types which are defined as subclasses of Enum. The possible string values and optionally their mappings are specified in a dict called "map" or a list called "vals" defined as members of the Enum subclass itself.
 +
|-
 +
| Latency || Tick
 +
| Can be assigned an existing Clock or Frequency parameter, or a string with the format [value][unit] where value is a base 10 number and unit is one of the following:
 +
* t => Ticks
 +
* ps => picoseconds
 +
* ns => nanoseconds
 +
* us => microseconds
 +
* ms => milliseconds
 +
* s => seconds
 +
|
 +
|-
 +
| Frequency || Tick
 +
| Can be assigned an existing Latency or Clock parameter, or a string with the format [value][unit] where value is a base 10 number and unit is one of the following:
 +
* THz => terahertz
 +
* GHz => gigahertz
 +
* MHz => megahertz
 +
* kHz => kilohertz
 +
* Hz => hertz
 +
| The frequency value is converted into a period in units of Ticks when transfered to C++.
 +
|-
 +
| Clock || Tick
 +
| Can be assigned an existing Latency or Frequency parameter, or a string with the format [value][unit] where value is a base 10 number and unit is one of the following:
 +
* t => Ticks
 +
* ps => picoseconds
 +
* ns => nanoseconds
 +
* us => microseconds
 +
* ms => milliseconds
 +
* s => seconds
 +
* THz => terahertz
 +
* GHz => gigahertz
 +
* MHz => megahertz
 +
* kHz => kilohertz
 +
* Hz => hertz
 +
| This type is like a combination of the Frequency and Latency types described above.
 +
|-
 +
| NetworkBandwidth || float
 +
| A floating point value specifying bits per second, or a string formatted as [value][unit] where value is a base 10 number and unit is one of the following:
 +
* Tbps => terabits per second
 +
* Gbps => gigabits per second
 +
* Mbps => megabits per second
 +
* kbps => kilobits per second
 +
* bps => bits per second
 +
| The network bandwidth value is converted to Ticks per byte before being transfered to C++.
 +
|-
 +
| MemoryBandwidth || float
 +
| A string formatted as [value][unit] where value is a base 10 number and unit is one of the following:
 +
* PB/s => pebibytes per second
 +
* TB/s => tebibytes per second
 +
* GB/s => gibibytes per second
 +
* MB/s => mebibytes per second
 +
* kB/s => kibibytes per second
 +
* B/s => bytes per second
 +
| The memory bandwidth value is converted to Ticks per byte before being transferred to C++. kibi, mebi, etc. are true powers of 2.
 +
|-
 +
| subclass of SimObject || defined in subclass || || These parameter types are for assigning one simobject to another as a parameter. The may be set to nothing using the special "NULL" python object.
 +
|}
  
 
====Inheritance====
 
====Inheritance====

Revision as of 01:51, 28 February 2011

Outline for some new documentation. Maybe we should be doing this wit LaTeX and using pandoc (LaTeX->mediawiki converter)?

Contents

Getting Started

What is M5?

M5 is a modular discrete event driven computer system simulator platform. That means that:

  1. M5's components can be rearranged, parameterized, extended or replaced easily to suite your needs.
  2. It simulates the passing of time as a series of discrete events.
  3. It's intended use is to simulate one or more computer systems in various ways.
  4. 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.

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:

  1. m5 – The main repository is where active development takes place.
  2. 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”
  3. 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.
  4. 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
The Regents of The University of Michigan
All Rights Reserved

M5 compiled Feb 12 2011 20:43:55
M5 revision e00ef55a2c49 7933 default tip
M5 started Feb 12 2011 20:45:47
M5 executing on fajita
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

The information below came from src/python/m5/params.py and src/python/m5/util/convert.py. Reference those files for the most up to date information.

Python Type Name C++ Type Format Notes
String std::string
Int int 32 bits
Unsigned unsigned 32 bits
Int8 int8_t
UInt8 uint8_t
Int16 int16_t
UInt16 uint16_t
Int32 int32_t
UInt32 uint32_t
Int64 int64_t
UInt64 uint64_t
Counter Counter
Tick Tick
TcpPort uint16_t
UdpPort uint16_t
Percent int Between 0 and 100.
Float double
MemorySize uint64_t A string formatted as [value][unit] where value is a base 10 number and unit is one of the following: 
* PB => pebibytes
* TB => tebibytes
* GB => gibibytes
* MB => mebibytes
* kB => kibibytes
* B => bytes
kibi, mebi, etc. are true powers of 2.
MemorySize32 uint32_t See "MemorySize" above. See "MemorySize" above.
Addr Addr See "MemorySize" above See "MemorySize" above. Also, an addr may be specified as a string with units, or a raw integer value.
Range Range<[type]>, type is int by default Defined as a "start" and "end" or "size" value. Exactly one of "end" or "size" is recognized as a keyword argument. A positional argument will be treated as "end", and "size" arguments are convected to "end" internally by adding to "start" and subtracting one.
AddrRange Range<Addr> See "Range" above.
TickRange Range<Tick> See "Range" above.
Bool bool
EthernetAddr Net::EthAddr Six pairs of 2 digit hex values seperated by ":"s, for instance "01:23:45:67:89:AB" May be set to NextEthernetAddr. All EthernetAddrs set to NextEthernetAddr will be assigned to incremental ethernet addresses starting with 00:90:00:00:00:01.
IpAddress Net::IpAddress Four decimal values between 0 and 255 separated by "."s, for instance "1.23.45.67", or an integer where the leftmost component is the most significant byte.
IpNetmask Net::IpNetmask A string representation of an IpAddress followed by either "/n" where n is a decimal value from 0 to 32 or "/e.f.g.h" where e-h are integer values between 0 and 255 and where when represented as binary from left to right the number is all 1s and the all 0s. The ip and netmask can also be passed in as positional or keyword arguments where the ip is an integer as described in IpAddress, and the netmask is a decimal value from 0 to 32.
IpWithPort Net::IpWithPort A string representation of an IpAddress followed by ":p" where p is a decimal value from 0 to 65535. The ip and port can also be passed in as positional or keyword arguments where the ip is an integer as described in IpAddress, and the port is a decimal value from 0 to 65535.
Time tm May be a Python struct_time, int, long, datetime, or date, the string "Now" or "Today", or a string parseable by Python's strptime with one of the following formats: 
* "%a %b %d %H:%M:%S %Z %Y"
* "%a %b %d %H:%M:%S %Z %Y"
* "%Y/%m/%d %H:%M:%S"
* "%Y/%m/%d %H:%M"
* "%Y/%m/%d"
* "%m/%d/%Y %H:%M:%S"
* "%m/%d/%Y %H:%M"
* "%m/%d/%Y"
* "%m/%d/%y %H:%M:%S"
* "%m/%d/%y %H:%M"
* "%m/%d/%y"
subclasses of Enum enum named after the parameter type A string defined as part of the enum This description applies to all enum parameter types which are defined as subclasses of Enum. The possible string values and optionally their mappings are specified in a dict called "map" or a list called "vals" defined as members of the Enum subclass itself.
Latency Tick Can be assigned an existing Clock or Frequency parameter, or a string with the format [value][unit] where value is a base 10 number and unit is one of the following: 
* t => Ticks
* ps => picoseconds
* ns => nanoseconds
* us => microseconds
* ms => milliseconds
* s => seconds
Frequency Tick Can be assigned an existing Latency or Clock parameter, or a string with the format [value][unit] where value is a base 10 number and unit is one of the following: 
* THz => terahertz
* GHz => gigahertz
* MHz => megahertz
* kHz => kilohertz
* Hz => hertz
The frequency value is converted into a period in units of Ticks when transfered to C++.
Clock Tick Can be assigned an existing Latency or Frequency parameter, or a string with the format [value][unit] where value is a base 10 number and unit is one of the following: 
* t => Ticks
* ps => picoseconds
* ns => nanoseconds
* us => microseconds
* ms => milliseconds
* s => seconds
* THz => terahertz
* GHz => gigahertz
* MHz => megahertz
* kHz => kilohertz
* Hz => hertz
This type is like a combination of the Frequency and Latency types described above.
NetworkBandwidth float A floating point value specifying bits per second, or a string formatted as [value][unit] where value is a base 10 number and unit is one of the following: 
* Tbps => terabits per second
* Gbps => gigabits per second
* Mbps => megabits per second
* kbps => kilobits per second
* bps => bits per second
The network bandwidth value is converted to Ticks per byte before being transfered to C++.
MemoryBandwidth float A string formatted as [value][unit] where value is a base 10 number and unit is one of the following: 
* PB/s => pebibytes per second
* TB/s => tebibytes per second
* GB/s => gibibytes per second
* MB/s => mebibytes per second
* kB/s => kibibytes per second
* B/s => bytes per second
The memory bandwidth value is converted to Ticks per byte before being transferred to C++. kibi, mebi, etc. are true powers of 2.
subclass of SimObject defined in subclass These parameter types are for assigning one simobject to another as a parameter. The may be set to nothing using the special "NULL" python object.

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

  1. Cache Memory
  2. Replacement Policies
  3. Memory Controller
  4. Rubyport
  5. Profiler ?? (Depends upon Derek)

Networks

  1. SimpleNetwork
  2. 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.

CF and ECF The carry out of the most significant bit.
ZF and EZF Whether the result was zero.
PF The parity of the result.
AF The carry from the 4th to 5th bit positions.
SF The sign of the result.
OF Whether there was an overflow.
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.

CF and ECF The carry out of the most significant bit.
ZF and EZF Whether the result was zero.
PF The parity of the result.
AF The carry from the 4th to 5th bit positions.
SF The sign of the result.
OF Whether there was an overflow.
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.

CF and ECF The barrow into of the most significant bit.
ZF and EZF Whether the result was zero.
PF The parity of the result.
AF The barrow from the 5th to 4th bit positions.
SF The sign of the result.
OF Whether there was an overflow.
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.

CF and ECF The barrow into of the most significant bit.
ZF and EZF Whether the result was zero.
PF The parity of the result.
AF The barrow from the 5th to 4th bit positions.
SF The sign of the result.
OF Whether there was an overflow.
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.

CF and ECF Whether ProdHi is non-zero
OF Whether ProdHi is non-zero.
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.

EZF Whether there are any remaining bits in Src1 after this step.
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.

CF and ECF Cleared
ZF and EZF Whether the result was zero.
PF The parity of the result.
AF Undefined
SF The sign of the result.
OF Cleared
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.

CF and ECF Cleared
ZF and EZF Whether the result was zero.
PF The parity of the result.
AF Undefined
SF The sign of the result.
OF Cleared
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.

CF and ECF Cleared
ZF and EZF Whether the result was zero.
PF The parity of the result.
AF Undefined
SF The sign of the result.
OF Cleared
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.

CF and ECF The last bit shifted out of the result.
OF The exclusive or of the what this instruction would set the CF flag to (if requested) and the most significant bit of the result
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.

CF and ECF The last bit shifted out of the result.
OF The most significant bit of the original value to shift
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.

CF and ECF The last bit shifted out of the result.
OF Cleared
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.

CF and ECF The most significant bit of the result.
OF The exclusive or of the two most significant bits of the original value.
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.

CF and ECF The last bit shifted out of the result.
OF The exclusive or of the CF flag before the rotate and the most significant bit of the original value.
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.

CF and ECF The least significant bit of the result.
OF The exclusive or of the most and least significant bits of the result.
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.

CF and ECF The last bit rotated out of the result.
OF The exclusive or of CF before the rotate and most significant bit of the result.
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.

0 CF (carry flag)
2 PF (parity flag)
3 ECF (emulation carry flag)
4 AF (auxiliary carry flag)
5 EZF (emulation zero flag)
6 ZF (zero flag)
7 SF (sign flag)
10 DF (direction flag)
11 OF (overflow flag)
Flags

The EZF flag is always set. In the future this may become optional.

EZF Set if the value of the flag read was zero.
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)

Utility Code

Bitfield functions

BitUnion classes

FastAlloc

IntMath

panic, warn, etc., when to use what

random number generation

reference counting pointers

Debugging

Trace flags

State trace/Tracer objects

Remote GDB support

tracediff

Regressions

Unit tests

Development Tools/Contributing

Mercurial queues

Review board

Mercurial repo browser

External Dependencies

Required versions

Things in ext

Retrieved from "http://daystrom.m5sim.org/wiki/index.php?title=Documentation&oldid=2944"