Outline for some new documentation. Maybe we should be doing this wit LaTeX and using pandoc (LaTeX->mediawiki converter)?
- 1 Getting Started
- 2 Source Code
- 3 Build System
- 4 SimObjects
- 5 Configuration Scripts
- 6 General memory system
- 7 Classic memory system
- 8 Ruby (Tentative and Incomplete)
- 9 Events
- 10 Devices
- 11 Execution Basics
- 12 Architectural State
- 13 Address Translation
- 14 CPUs
- 15 Interrupts
- 16 ISA parser
- 17 Multiple ISA support
- 18 Alpha Implementation
- 19 ARM Implementation
- 20 MIPS Implementation
- 21 Power Implementation
- 22 SPARC Implemenation
- 23 X86 Implementation
- 24 Pseudo Instructions
- 25 SE mode
- 26 Statistics (don’t know what to say here)
- 27 Utility Code
- 28 Debugging
- 29 Development Tools/Contributing
- 30 External Dependencies
What is M5?
M5 is a modular discrete event driven computer system simulator platform. That means that:
- M5's components can be rearranged, parameterized, extended or replaced easily to suite your needs.
- It simulates the passing of time as a series of discrete events.
- It's intended use is to simulate one or more computer systems in various ways.
- 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:
- 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:
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:
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.
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:
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.
Generated files - where do they end up
.m5 config files
jobfile to run multiple jobs
What are they
What do they do
How do you get at their values
Adding files to the build
The python side
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|
|Percent||int||Between 0 and 100.|
|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.|
|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 "220.127.116.11", 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.|
Special attribute names
Rules for importing - how to get what
Pro tips - avoiding cycles, always descend from root, etc.
The C++ side
Stages of initialization
Header files to include
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 in general
Various port types
Classic memory system
Hooking them up
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
- Profiler ?? (Depends upon Derek)
Implementation of Ruby
Low level details goes here. Need to explain code directory structure as well.
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.
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*