|
|
| (168 intermediate revisions by 15 users not shown) |
| Line 1: |
Line 1: |
| − | ==Getting Started==
| + | 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. |
| | | | |
| − | ===What is M5?===
| + | For an overview, we have posted slides and most importantly '''video''' of a tutorial at HiPEAC Computer Systems Week. See [[Tutorials]]. |
| | | | |
| − | M5 is a modular discrete event driven computer system simulator platform. That means that:
| + | '''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]]. |
| | | | |
| − | 1. M5's components can be rearranged, parameterized, extended or replaced easily to suite your needs.
| + | == Getting Started == |
| − | | + | # [[Introduction]] - A quick introduction to gem5. |
| − | 2. It simulates the passing of time as a series of discrete events.
| + | # [[Source Code]] - Information about the source code itself. |
| − | | + | # [[Dependencies]] - Things you'll need that aren't part of gem5 itself. |
| − | 3. 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. |
| − | | + | # [[Download | Full System and Benchmark Files]] - Disk images for operating system and benchmark applications, and how to install them. |
| − | 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.
| + | # [[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:
| |
| − | | |
| − | 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. alpha-system – A repository for Alpha system software specialized for M5, specifically PAL and Console code.
| |
| − | | |
| − | 5. 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===
| |
| | | | |
| | + | == Running gem5 == |
| | + | # [[Running gem5]] - Starting a simulation from the command line. |
| | + | # [[Output Files]] - Output obtained from simulation |
| | + | # [[Checkpoints]], Fast Forwarding - How to create Checkpoints, restore the checkpointed state, fast forward simulation. |
| | + | # [[Regression Tests]] - Running the regression tests. |
| | + | # [[SimObjects]] - What SimObjects are and how they work. |
| | + | # [[Configuration / Simulation Scripts]] - Explains how to configure the simulator and run simulations |
| | + | # [[Visualization]] -- Tools to help visualize what is going on in a system |
| | | | |
| − | ===jobfile to run multiple jobs=== | + | == Workloads == |
| − | | + | # [[Compiling workloads | Compiling]] - How to compile workloads to run within gem5. |
| − | | + | # [[Multiprogrammed workloads | Multi-programmed]] - Multiprogrammed workloads in SE mode. |
| − | ==Build System==
| + | # [[Multithreaded workloads | Multi-threaded]] - Multithreaded workloads in SE mode. |
| − | | + | # Benchmark suites |
| − | | + | ## [[SPEC benchmarks | SPEC]] - SPEC benchmarks in SE mode. |
| − | ===Build targets===
| + | ## [[Splash benchmarks | SPLASH]] - SPLASH benchmarks (SE or FS mode?) |
| − | | + | ## [[PARSEC benchmarks | PARSEC]] - PARSEC benchmarks in FS mode. |
| − | ===Configuration variables===
| + | # [[Disk images]] - Setting up a disk image. |
| − | ====What are they====
| + | # [[Linux kernel]] - Preparing a Linux kernel for use in gem5. |
| − | ====What do they do===
| + | # [[m5ops]] - How to talk to the simulator from within a simulated workload. |
| − | ====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?)===
| |
| − | | |
| − | ==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 (no idea what to say here)==
| |
| − | | |
| − | ==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==
| |
| − | | |
| − | ==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 | + | == Development == |
| − | == | + | # [[Functional Testers]] |
| − | ==tracediff==
| + | #* [[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]] |
| | | | |
| − | ==Regressions== | + | == Infrastructure == |
| | + | # [[Events]] |
| | + | # [[Statistics]] |
| | + | # [[Utility Code]] |
| | + | # [[Serialization]] |
| | | | |
| − | =Development Tools/Contributing= | + | == Memory System == |
| | + | # [[General Memory System]] - Shared infrastructure between the Classic and Ruby models |
| | + | # [[Classic Memory System]] - Description of our easily configurable, crossbar-based memory system |
| | + | # [[Ruby]] - Description of our detailed and flexible memory system. Lots of information here. |
| | + | #* [[SLICC|SLICC Overview]] |
| | + | #* [[GEMS-gem5_SLICC_Transition_Guide|SLICC Transistion Guide]] |
| | + | #* [[Interconnection_Network]] |
| | | | |
| − | ==Mercurial queues | + | == Full System == |
| − | == | + | # [[Devices]] |
| − | ==Review board==
| + | ## [[IDE Devices]] |
| | + | ## [[NIC Devices]] |
| | + | ## [[Timers]] |
| | + | ## [[UARTs and serial terminals]] |
| | + | # [[Disks and Disk Images]] |
| | + | # [[Interrupts]] |
| | | | |
| − | ==Mercurial repo browser | + | == Syscall Emulation == |
| − | == | + | # [[SE Mode]] |
| − | =External Dependencies=
| |
| | | | |
| − | ==Required versions== | + | == Instruction Execution == |
| | + | # [[Execution Basics]] |
| | + | # [[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]] |
| | | | |
| − | ==Things in ext== | + | == ISA Implementations == |
| | + | # [[Architecture Support]] -- What architectures are supported by gem5 and what features of them are implemented |
| | + | # [[Status Matrix]] |
| | + | # [[ISA Parser]] |
| | + | # [[Alpha Implementation]] |
| | + | # [[ARM Implementation]] |
| | + | # [[MIPS Implementation]] |
| | + | # [[Power Implementation]] |
| | + | # [[SPARC Implementation]] |
| | + | # [[X86 Implementation]] |
| | + | # [[Defining ISAs]] |
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.
