diff --git a/_pages/about.md b/_pages/about.md index e05105d72d..82c28df401 100755 --- a/_pages/about.md +++ b/_pages/about.md @@ -32,8 +32,12 @@ e.g., to model complex multi-level non-uniform cache hierarchies with heterogeneous memories. #### Multiple ISA support -gem5 decouples ISA semantics from its CPU models, enabling effective [support of multiple ISAs](/documentation/general_docs/architecture_support). Currently gem5 supports the Alpha, ARM, SPARC, MIPS, POWER, RISC-V and x86 ISAs. -However, all guest platforms aren't supported on all host platforms (most notably Alpha requires little-endian hardware). + + + +gem5 decouples ISA semantics from its CPU models, enabling effective [support of multiple ISAs](/documentation/general_docs/architecture_support). Currently gem5 supports the ARM, SPARC, MIPS, POWER, RISC-V and x86 ISAs. +However, all guest platforms aren't supported on all host platforms . #### Homogeneous and heterogeneous multi-core The CPU models and caches can be combined in arbitrary topologies, creating @@ -44,7 +48,7 @@ coherence protocol keeps the caches coherent. - **ARM**: gem5 can model up to 64 (heterogeneous) cores of a Realview ARM platform, and boot [unmodified Linux](/documentation/general_docs/fullsystem/building_arm_kernel) and - [Android](/documentation/general_docs/fullsystem/building_android_m) with a combination of + [Android](/documentation/general_docs/fullsystem/building_android_m) with a combination of in-order and out-of-order CPUs. The ARM implementation supports 32 or 64-bit kernels and applications. - **x86**: The gem5 simulator supports a standard PC platform and boots unmodified Linux @@ -54,10 +58,11 @@ coherence protocol keeps the caches coherent. in a similar manner as the Sun T1 Architecture simulator tools (building the hypervisor with specific defines and using the HSMID virtual disk driver). - - **Alpha**: gem5 models a DEC Tsunami system in sufficient detail + + #### Application-only support In application-only (non-full-system) mode, gem5 can execute a variety of @@ -76,6 +81,10 @@ provides a complete platform for research in future energy-efficient systems. However, the existing DVFS documentation is out of date. You can find this page at the [old wiki](http://old.gem5.org/Running_gem5.html#Experimenting_with_DVFS). + #### A trace-based CPU CPU model that plays back elastic traces, which are dependency and timing annotated traces generated by a probe attached to the out-of-order CPU model. The focus of the [Trace CPU model](/documentation/general_docs/cpu_models/TraceCPU) is to achieve memory-system (cache-hierarchy, interconnects and main memory) performance exploration in a fast and reasonably accurate way instead of using the detailed CPU model. @@ -86,6 +95,9 @@ thread inside the SystemC event kernel, and keeping the events and timelines syn This functionality enables the gem5 components to interoperate with a wide range of System on Chip (SoC) component models, such as interconnects, devices and accelerators. A wrapper for SystemC Transaction Level Modelling (TLM) is provided. + #### A NoMali GPU model. gem5 comes with an integrated [NoMali GPU model](http://old.gem5.org/wiki/images/5/53/2015_ws_04_ISCA_2015_NoMali.pdf) that is compatible with the Linux and Android GPU driver stack, and thus removes the need for software rendering. diff --git a/_pages/contributing.md b/_pages/contributing.md index d0aefa6f6e..794c572437 100644 --- a/_pages/contributing.md +++ b/_pages/contributing.md @@ -221,7 +221,7 @@ be run on multiple threads with the `-j` flag. E.g.: `python main.py run The unit tests should also pass. To run the unit tests: ```sh -scons build/NULL/unittests.opt +scons build/ALL/unittests.opt ``` To compile an individual gem5 binary: diff --git a/_pages/documentation/gem5-stdlib/0-overview.md b/_pages/documentation/gem5-stdlib/0-overview.md index 1f895c629c..f3253a8e2a 100644 --- a/_pages/documentation/gem5-stdlib/0-overview.md +++ b/_pages/documentation/gem5-stdlib/0-overview.md @@ -18,13 +18,15 @@ The [`configs/examples/gem5_library`](https://github.com/gem5/gem5/tree/stable/c The following subsections give a broad overview of the gem5 stdlib packages and what there intended purposes are. -**Note: The documentation/tutorial/etc. related to the standard library are for the v22.0 release. +**Note: The documentation/tutorials/etc. related to the standard library have been updated for the v24.1 release. Please ensure you have the correct version of gem5 before proceeding.** As part of [gem5's 2022 Bootcamp](/events/boot-camp-2022), the stdlib was taught as a tutorial. Slides for this tutorial can be found [here](https://raw.githubusercontent.com/gem5bootcamp/gem5-bootcamp-env/main/assets/slides/using-gem5-02-gem5-stdlib-tutorial.pdf). A video recording of this tutorial can be found [here](https://www.youtube.com/watch?v=vbruiMyIFsA). +The stdlib was also covered during the [2024 gem5 Bootcamp](https://bootcamp.gem5.org/#02-Using-gem5/01-stdlib). + ## The gem5 stdlib components package and its design philosophy @@ -85,7 +87,7 @@ A resource, in the context of gem5, is something used in a simulation, or by a s Typically these are applications, kernels, disk images, benchmarks, or tests. As these resources can be hard to find, or hard to create, we provide pre-built resources as part of [gem5-resources](/documentation/general_docs/gem5_resources). -For example, via gem5-resources, a user may download an Ubuntu 18.04 disk image with known compatibility with gem5. +For example, via gem5-resources, a user may download an Ubuntu 24.04 disk image with known compatibility with gem5. They need not setup this themselves. A core feature of the gem5 stdlib resource package is that it allows users to _automatically obtain_ prebuilt gem5 resources for their simulation. @@ -94,28 +96,30 @@ A user may specify in their Python config file that a specific gem5 resource is The tutorials will demonstrate how to use the resource package in greater detail, but for now, a typical pattern is as follows: ```python -from gem5.resources.resource import Resource +from gem5.resources.resource import obtain_resource -resource = Resource("riscv-disk-img") +resource = obtain_resource("riscv-ubuntu-24.04-boot") print(f"The resources is available at {resource.get_local_path()}") ``` -This will obtain the `riscv-disk-img` resource and store it locally for use in a gem5 simulation. +This will obtain the `riscv-ubuntu-24.04-boot` workload resource and store it locally for use in a gem5 simulation. The resources package references the resources that are available to view at the [gem5 Resources website](https://resources.gem5.org) and the [gem5 Resources repository](https://github.com/gem5/gem5-resources). The website is strongly recommended to get info on what resources are available and where they may be downloaded from. ## The Simulate package -**WARNING: The Simulate package is still in a BETA state. APIs in this package may change in future releases of gem5**. - The simulate package is used to run gem5 simulations. While there is some boilerplate code this module handles on the users behalf, its primary purpose is to provde default behavior and APIs for what we refer to as _Exit Events_. Exit events are when a simulation exits for a particular reason. + + A typical example of an exit event would be a `Workbegin` exit event. This is used to specify that a Region-of-Interest (ROI) has been reached. Usually this exit would be used to allow a user to begin logging statistics or to switch to a more detailed CPU model. Prior to the stdlib, the user would need to specify precisely what the expected behavior was at exit events such as this. The simulation would exit and the configuration script would contain Python code specifying what to do next. Now, with the simulate package, there is a default behavior for this kind of event (the stats are reset), and an easy interface to override this behavior with something the user requires. + +More information about exit events can be found in the [M5ops documentation](https://www.gem5.org/documentation/general_docs/m5ops/). \ No newline at end of file diff --git a/_pages/documentation/gem5-stdlib/1-tutorial-hello-world.md b/_pages/documentation/gem5-stdlib/1-tutorial-hello-world.md index 7856fe061f..a1b9b15731 100644 --- a/_pages/documentation/gem5-stdlib/1-tutorial-hello-world.md +++ b/_pages/documentation/gem5-stdlib/1-tutorial-hello-world.md @@ -7,6 +7,10 @@ permalink: /documentation/gem5-stdlib/hello-world-tutorial author: Bobby R. Bruce --- + + ## Building a "Hello World" example with the gem5 standard library In this tutorial we will cover how to create a very basic simulation using gem5 components. @@ -14,13 +18,15 @@ This simulation will setup a system consisting of a single-core processor, runni The system will run an X86 binary in syscall emulation (SE) mode. The binary will be obtained from gem5-resources and which will print a "Hello World!" string to stdout upon execution. -To start we must compile gem5 to simulate the X86 ISA: +To start we must compile the ALL build for gem5: ```sh # In the root of the gem5 directory -scons build/X86/gem5.opt -j +scons build/ALL/gem5.opt -j ``` +As of gem5 v24.1, the ALL build includes all Ruby protocols and all ISAs. If you are using a prebuilt gem5 binary, this step is not necessary. + Then a new Python file should be created (we will refer to this as `hello-world.py` going forward). The first lines in this file should be the needed imports: @@ -28,9 +34,10 @@ The first lines in this file should be the needed imports: from gem5.components.boards.simple_board import SimpleBoard from gem5.components.cachehierarchies.classic.no_cache import NoCache from gem5.components.memory.single_channel import SingleChannelDDR3_1600 -from gem5.components.processors.simple_processor import SimpleProcessor from gem5.components.processors.cpu_types import CPUTypes -from gem5.resources.resource import Resource +from gem5.components.processors.simple_processor import SimpleProcessor +from gem5.isas import ISA +from gem5.resources.resource import obtain_resource from gem5.simulate.simulator import Simulator ``` @@ -68,7 +75,7 @@ If not set, the `SingleChannelDDR3_1600` will default to 8 GiB. Then we consider the _processor_: ```python -processor = SimpleProcessor(cpu_type=CPUTypes.ATOMIC, num_cores=1) +processor = SimpleProcessor(cpu_type=CPUTypes.ATOMIC, num_cores=1, isa=ISA.X86) ``` A processor in `gem5.components` is an object which contains a number of gem5 CPU cores, of a particular or varying type (`ATOMIC`, `TIMING`, `KVM`, `O3`, etc.). @@ -95,11 +102,11 @@ Of course, in order to run a meaningful simulation, we must specify a workload f To do so we add the following lines: ```python -binary = Resource("x86-hello64-static") +binary = obtain_resource("x86-hello64-static") board.set_se_binary_workload(binary) ``` -The `Resource` class takes a string which specifies which resource, from [gem5-resources](/documentation/general_docs/gem5_resources), is to be obtained for the simulation. +The `obtain_resource` function takes a string which specifies which resource, from [gem5-resources](/documentation/general_docs/gem5_resources), is to be obtained for the simulation. All the gem5 resources can be found on the [gem5 Resources website](https://resources.gem5.org). If the resource is not present on the host system it'll be automatically downloaded. @@ -108,7 +115,7 @@ an x86, 64-bit, statically compiled binary which will print "Hello World!" to st After specifying the resource we set the workload via the board's `set_se_binary_workload` function. As the name suggests `set_se_binary_workload` is a function used to set a binary to be executed in Syscall Execution mode. - +You can see and search for available resources on the [gem5 resources website](https://resources.gem5.org/). This is all that is required to setup your simulation. From this you simply need to construct and run the `Simulator`: @@ -118,26 +125,24 @@ simulator = Simulator(board=board) simulator.run() ``` -It should also be noted that **the `Simulator` module is still in a beta state, so its APIs may change upon the next release**. - As a recap, your script should look like the following: ```python from gem5.components.boards.simple_board import SimpleBoard from gem5.components.cachehierarchies.classic.no_cache import NoCache from gem5.components.memory.single_channel import SingleChannelDDR3_1600 -from gem5.components.processors.simple_processor import SimpleProcessor from gem5.components.processors.cpu_types import CPUTypes -from gem5.resources.resource import Resource +from gem5.components.processors.simple_processor import SimpleProcessor +from gem5.isas import ISA +from gem5.resources.resource import obtain_resource from gem5.simulate.simulator import Simulator - # Obtain the components. cache_hierarchy = NoCache() memory = SingleChannelDDR3_1600("1GiB") -processor = SimpleProcessor(cpu_type=CPUTypes.ATOMIC, num_cores=1) +processor = SimpleProcessor(cpu_type=CPUTypes.ATOMIC, num_cores=1, isa=ISA.X86) -#Add them to the board. +# Add them to the board. board = SimpleBoard( clk_freq="3GHz", processor=processor, @@ -146,7 +151,7 @@ board = SimpleBoard( ) # Set the workload. -binary = Resource("x86-hello64-static") +binary = obtain_resource("x86-hello64-static") board.set_se_binary_workload(binary) # Setup the Simulator and run the simulation. @@ -157,22 +162,26 @@ simulator.run() It can then be executed with: ```sh -./build/X86/gem5.opt hello-world.py +./build/ALL/gem5.opt hello-world.py ``` -If setup correctly, the output will look something like: +If you are using a pre-built binary, you can execute the simulation with: +```sh +gem5 hello-world.py ``` -... -warn: The simulate package is still in a beta state. The gem5 project does not guarantee the APIs within this package will remain consistent across upcoming releases. +If setup correctly, the output will look something like: + +```text +info: Using default config Global frequency set at 1000000000000 ticks per second -build/X86/mem/mem_interface.cc:791: warn: DRAM device capacity (8192 Mbytes) does not match the address range assigned (1024 Mbytes) -0: board.remote_gdb: listening for remote gdb on port 7000 -build/X86/sim/simulate.cc:194: info: Entering event queue @ 0. Starting simulation... -build/X86/sim/syscall_emul.hh:1014: warn: readlink() called on '/proc/self/exe' may yield unexpected results in various settings. - Returning '/scr/bbruce/.cache/gem5/x86-hello64-static' -build/X86/sim/mem_state.cc:443: info: Increasing stack size by one page. +src/mem/dram_interface.cc:690: warn: DRAM device capacity (8192 Mbytes) does not match the address range assigned (1024 Mbytes) +src/base/statistics.hh:279: warn: One of the stats is a legacy stat. Legacy stat is a stat that does not belong to any statistics::Group. Legacy stat is deprecated. +board.remote_gdb: Listening for connections on port 7005 +src/sim/simulate.cc:199: info: Entering event queue @ 0. Starting simulation... +src/sim/syscall_emul.hh:1117: warn: readlink() called on '/proc/self/exe' may yield unexpected results in various settings. +src/sim/mem_state.cc:448: info: Increasing stack size by one page. Hello world! ``` @@ -180,7 +189,7 @@ It should be obvious from this point that a _board's_ parameters may be altered For example, if we want to test a `TIMING` CPU setup we'd change our _processor_ to: ```python -processor = SimpleProcessor(cpu_type=CPUTypes.TIMING, num_cores=1) +processor = SimpleProcessor(cpu_type=CPUTypes.TIMING, num_cores=1, isa=ISA.X86) ``` This is all that is required. @@ -190,14 +199,14 @@ As another example, consider swapping out a component for another. In this design we decided on `NoCache` but we could use another classic cache hierarchy, such as `PrivateL1CacheHierarchy`. To do so we'd change our `cache_hierarchy` parameter: -``` +```python # We import the cache hierarchy we want. from gem5.components.cachehierarchies.classic.private_l1_cache_hierarchy import PrivateL1CacheHierarchy ... # Then set it. -cache_hierarchy = PrivateL1CacheHierarchy(l1d_size="32kB", l1i_size="32kB") +cache_hierarchy = PrivateL1CacheHierarchy(l1d_size="32KiB", l1i_size="32KiB") ``` Note here that `PrivateL1CacheHierarchy` requires the user to specify the L1 data and instruction cache sizes to be constructed. diff --git a/_pages/documentation/gem5-stdlib/2-tutorial-x86-fs.md b/_pages/documentation/gem5-stdlib/2-tutorial-x86-fs.md index 38844af296..b15b8e0689 100644 --- a/_pages/documentation/gem5-stdlib/2-tutorial-x86-fs.md +++ b/_pages/documentation/gem5-stdlib/2-tutorial-x86-fs.md @@ -7,6 +7,10 @@ permalink: /documentation/gem5-stdlib/x86-full-system-tutorial author: Bobby R. Bruce --- + + ## Building an x86 full-system simulation with the gem5 standard library One of the key ideas behind the gem5 standard library is to allow users to simulate, big, complex systems, with minimal effort. @@ -19,29 +23,35 @@ This system will utilize gem5's ability to switch cores, allowing booting of the Without using the gem5 library this would take several hundred lines of Python, forcing the user to specify details such as every IO component and exactly how the cache hierarchy is setup. Here, we will demonstrate how simple this task can be with using the gem5 standard library. -As we focus on X86, we must must build the gem5 X86 binary: +First, we build the ALL binary. This will allow us to run simulations for any ISA, including X86: ```sh -scons build/X86/gem5.opt -j +scons build/ALL/gem5.opt -j ``` +If you are using a prebuilt gem5 binary, this step is not necessary. + To start, create a new Python file. We will refer to this as `x86-ubuntu-run.py`. To begin we add our import statements: ```python -from gem5.utils.requires import requires +from gem5.coherence_protocol import CoherenceProtocol from gem5.components.boards.x86_board import X86Board +from gem5.components.cachehierarchies.ruby.mesi_two_level_cache_hierarchy import ( + MESITwoLevelCacheHierarchy, +) from gem5.components.memory.single_channel import SingleChannelDDR3_1600 -from gem5.components.cachehierarchies.ruby.mesi_two_level_cache_hierarchy import MESITwoLevelCacheHierarchy -from gem5.components.processors.simple_switchable_processor import SimpleSwitchableProcessor -from gem5.coherence_protocol import CoherenceProtocol -from gem5.isas import ISA from gem5.components.processors.cpu_types import CPUTypes -from gem5.resources.resource import Resource -from gem5.simulate.simulator import Simulator +from gem5.components.processors.simple_switchable_processor import ( + SimpleSwitchableProcessor, +) +from gem5.isas import ISA +from gem5.resources.resource import obtain_resource from gem5.simulate.exit_event import ExitEvent +from gem5.simulate.simulator import Simulator +from gem5.utils.requires import requires ``` As in other Python scripts, these are simply classes/functions needed in our script. @@ -60,9 +70,7 @@ requires( Here we state that we need gem5 compiled to run the X86 ISA and support the MESI Two Level protocol. We also require the host system to have KVM. **NOTE: Please ensure your host system supports KVM. If your system does not please remove the `kvm_required` check here**. -KVM will only work if the host platform and the simulated ISA are the same (e.g., X86 host and X86 simulation). - - +KVM will only work if the host platform and the simulated ISA are the same (e.g., X86 host and X86 simulation). You can learn more about using KVM with gem5 [here](https://www.gem5.org/documentation/general_docs/using_kvm/). This `requires` call is not required but provides a good safety net to those running the script. Errors that occur due to incompatible gem5 binaries may not make much sense otherwise. @@ -102,6 +110,7 @@ Next we setup the _processor_: processor = SimpleSwitchableProcessor( starting_core_type=CPUTypes.KVM, switch_core_type=CPUTypes.TIMING, + isa=ISA.X86, num_cores=2, ) ``` @@ -136,122 +145,124 @@ This finalizes our system design. Now we set the workload to run on the system: ```python -command = "m5 exit;" \ - + "echo 'This is running on Timing CPU cores.';" \ - + "sleep 1;" \ - + "m5 exit;" - -board.set_kernel_disk_workload( - kernel=Resource("x86-linux-kernel-5.4.49",), - disk_image=Resource("x86-ubuntu-18.04-img"), - readfile_contents=command, -) +workload = obtain_resource("x86-ubuntu-24.04-boot-with-systemd") +board.set_workload(workload) ``` -The `X86Board`'s `set_kernel_disk_workload` function requires a `kernel` and `disk_image` to be set. -Both these are obtainable from the gem5 resources repository. -Therefore, via the `Resource` class, we specify `x86-linux-kernel-5.4.49` for the Kernel (a Linux kernel, version 5.4.49, compiled to X86) and `x86-ubuntu-18.04-img` for the disk image (a disk image containing Ubuntu 18.04, for X86). -The `Resource` class will automatically retrieve these resources if they are not already present on the host system. -**Note: If a user wishes to use their own resource (that is, a resource not prebuilt as part of gem5-resources), they may follow the tutorial [here](../general_docs/gem5_resources)** +The `obtain_resource` function acquires an X86 Ubuntu 24.04 boot workload, which encompasses a kernel and disk image resource, as well as additional parameters to the kernel and a string indicating the underlying `set_workload` function that the workload uses. You can see these details under the [Raw](https://resources.gem5.org/resources/x86-ubuntu-24.04-boot-with-systemd/raw?database=gem5-resources&version=3.0.0) tab of of the gem5 Resources website page for this workload. -The `x86-ubuntu-18.04-img` has been designed to boot the OS, automatically login, and run `m5 readfile`. -The `m5 readfile` will read a file and execute it. -The contents of this file are specified via the `readfile_contents` parameter. -Therefore the value of` readfile_contents` will be executed on system startup. -**Note: `readfile_contents` is an optional argument. If it is not specified in `set_kernel_disk_workload` the simulation will exit after boot**. -This behavior is specific to the `x86-ubuntu-18.04-img` disk image and is not true for all disk images. +It is also possible to use the `set_kernel_disk_workload` function instead of `set_workload` and obtain the disk image and kernel resources separately. This can be used when you want to use a combination of resources that is not provided at [the gem5 resources website](resources.gem5.org). -In this tutorial the script first runs `m5 exit`. -This temporarily exits the simulation allowing us to switch the CPUs from `KVM` to `TIMING`. -Then, when the simulation is resumed, the echo and sleep statements are executed (on the `TIMING` CPUs) and `m5 exit` is called again, thus exiting and completing the simulation. -Users may inspect `m5out/system.pc.com_1.device` to see the echo output. +**Note: If a user wishes to use their own resource (that is, a resource not prebuilt as part of gem5-resources), they may follow the tutorial [here](../general_docs/gem5_resources). A tutorial is also available at the [2024 gem5 bootcamp website](https://bootcamp.gem5.org/#02-Using-gem5/02-gem5-resources)** + +When using the `set_kernel_disk_workload` function, you can also pass an optional `readfile_contents` argument. This will be run as a bash script after the system boots up, and can be used to launch a benchmark after the system boots if you are using a disk image with benchmarks. An example can be found [here](https://resources.gem5.org/resources/x86-ubuntu-24.04-npb-ua-b/raw?database=gem5-resources&version=2.0.0) Finally, we specify how the simulation is to be run with the following: + + ```python + +# This exit handler generator is only needed in gem5 v24.1 and lower. +# gem5 v25.0 adds hypercalls and sets default handlers, meaning that users +# no longer have to set handlers in each configuration script to prevent +# simulations from exiting on kernel boot or Ubuntu boot +def exit_event_handler(): + print("First exit: kernel booted") + yield False # gem5 is now executing systemd startup + print("Second exit: Started `after_boot.sh` script") + # The after_boot.sh script is executed after the kernel and systemd have + # booted. + # Here we switch the CPU type to Timing. + print("Switching to Timing CPU") + processor.switch() + yield False # gem5 is now executing the `after_boot.sh` script + print("Third exit: Finished `after_boot.sh` script") + # The after_boot.sh script will run a script if it is passed via + # m5 readfile. This is the last exit event before the simulation exits. + yield True + + simulator = Simulator( board=board, - on_exit_event={ - ExitEvent.EXIT : (func() for func in [processor.switch]), - }, + # This line is only needed for gem5 v24.1 and below + # on_exit_event={ + # ExitEvent.EXIT: exit_event_handler(), + # }, ) simulator.run() ``` -The important thing to note here is the `on_exit_event` argument. -Here we can override default behavior. -The `m5 exit` command triggers an `EXIT` exit event in the `Simulator` module. -By default this exits the simulation run completely. -In our case we want the first `m5 exit` call to switch processors from KVM to TIMING cores. +The `on_exit_event` argument is used to override default behavior in gem5 v24.1 +and below. The `on_exit_event` parameter is a Python dictionary of exit events and [Python generators](https://wiki.python.org/moin/Generators). -In this tutorial we are setting `ExitEvent.Exit` to the generator `(func() for func in [processor.switch])`. -This means the `processor.switch` function is called on the first yield of the generator (that is, on the first instance of `m5 exit`). -After this the generator is exhausted and the `Simulator` module will return to the default `Exit` exit event behavior. - +In this tutorial we are setting `ExitEvent.Exit` to the `exit_event_handler` generator. +There are three `EXIT` exit events in the Ubuntu 24.04 disk image resource used by the workload. +If an exit event handler is not defined, the simulation will end after the first exit event, which takes place after the kernel finishes booting. +Yielding `False` allows the simulation to continue, while yielding `True` ends the simulation. +After the second exit event, we switch the cores from KVM to TIMING, then yield `False` to continue the simulation. +After the third exit event, we yield `True`, ending the simulation. -This completes the setup of our script, to execute the script we run: +This completes the setup of our script. To execute the script we run: +```bash +./build/ALL/gem5.opt x86-ubuntu-run.py ``` -./build/X86/gem5.opt x86-ubuntu-run.py + +If you are using a pre-built binary, you can execute the simulation with: + +```sh +gem5 x86-ubuntu-run.py ``` You can see the output of the simulator in `m5out/system.pc.com_1.device`. Below is the configuration script in full. -It mirrors closely the example script at `configs/example/gem5_library/x86-ubuntu-run.py` in the gem5 repository. +It mirrors closely the example script at `configs/example/gem5_library/x86-ubuntu-run-with-kvm.py` in the gem5 repository. ```python -from gem5.utils.requires import requires +from gem5.coherence_protocol import CoherenceProtocol from gem5.components.boards.x86_board import X86Board +from gem5.components.cachehierarchies.ruby.mesi_two_level_cache_hierarchy import ( + MESITwoLevelCacheHierarchy, +) from gem5.components.memory.single_channel import SingleChannelDDR3_1600 -from gem5.components.cachehierarchies.ruby.mesi_two_level_cache_hierarchy import (MESITwoLevelCacheHierarchy,) -from gem5.components.processors.simple_switchable_processor import SimpleSwitchableProcessor -from gem5.coherence_protocol import CoherenceProtocol -from gem5.isas import ISA from gem5.components.processors.cpu_types import CPUTypes -from gem5.resources.resource import Resource -from gem5.simulate.simulator import Simulator +from gem5.components.processors.simple_switchable_processor import ( + SimpleSwitchableProcessor, +) +from gem5.isas import ISA +from gem5.resources.resource import obtain_resource from gem5.simulate.exit_event import ExitEvent +from gem5.simulate.simulator import Simulator +from gem5.utils.requires import requires -# This runs a check to ensure the gem5 binary is compiled to X86 and supports -# the MESI Two Level coherence protocol. requires( isa_required=ISA.X86, coherence_protocol_required=CoherenceProtocol.MESI_TWO_LEVEL, kvm_required=True, ) -# Here we setup a MESI Two Level Cache Hierarchy. cache_hierarchy = MESITwoLevelCacheHierarchy( l1d_size="32KiB", l1d_assoc=8, l1i_size="32KiB", l1i_assoc=8, - l2_size="256kB", + l2_size="256KiB", l2_assoc=16, num_l2_banks=1, ) -# Setup the system memory. -# Note, by default DDR3_1600 defaults to a size of 8GiB. However, a current -# limitation with the X86 board is it can only accept memory systems up to 3GB. -# As such, we must fix the size. -memory = SingleChannelDDR3_1600("2GiB") - -# Here we setup the processor. This is a special switchable processor in which -# a starting core type and a switch core type must be specified. Once a -# configuration is instantiated a user may call `processor.switch()` to switch -# from the starting core types to the switch core types. In this simulation -# we start with KVM cores to simulate the OS boot, then switch to the Timing -# cores for the command we wish to run after boot. +memory = SingleChannelDDR3_1600(size="2GiB") + processor = SimpleSwitchableProcessor( starting_core_type=CPUTypes.KVM, switch_core_type=CPUTypes.TIMING, + isa=ISA.X86, num_cores=2, ) -# Here we setup the board. The X86Board allows for Full-System X86 simulations. board = X86Board( clk_freq="3GHz", processor=processor, @@ -259,48 +270,43 @@ board = X86Board( cache_hierarchy=cache_hierarchy, ) -# This is the command to run after the system has booted. The first `m5 exit` -# will stop the simulation so we can switch the CPU cores from KVM to timing -# and continue the simulation to run the echo command, sleep for a second, -# then, again, call `m5 exit` to terminate the simulation. After simulation -# has ended you may inspect `m5out/system.pc.com_1.device` to see the echo -# output. -command = "m5 exit;" \ - + "echo 'This is running on Timing CPU cores.';" \ - + "sleep 1;" \ - + "m5 exit;" - -# Here we set the Full System workload. -# The `set_workload` function for the X86Board takes a kernel, a disk image, -# and, optionally, a the contents of the "readfile". In the case of the -# "x86-ubuntu-18.04-img", a file to be executed as a script after booting the -# system. -board.set_kernel_disk_workload( - kernel=Resource("x86-linux-kernel-5.4.49",), - disk_image=Resource("x86-ubuntu-18.04-img"), - readfile_contents=command, -) +workload = obtain_resource("x86-ubuntu-24.04-boot-with-systemd") +board.set_workload(workload) + + +def exit_event_handler(): + print("First exit: kernel booted") + yield False # gem5 is now executing systemd startup + print("Second exit: Started `after_boot.sh` script") + # The after_boot.sh script is executed after the kernel and systemd have + # booted. + # Here we switch the CPU type to Timing. + print("Switching to Timing CPU") + processor.switch() + yield False # gem5 is now executing the `after_boot.sh` script + print("Third exit: Finished `after_boot.sh` script") + # The after_boot.sh script will run a script if it is passed via + # m5 readfile. This is the last exit event before the simulation exits. + yield True + simulator = Simulator( board=board, on_exit_event={ - # Here we want override the default behavior for the first m5 exit - # exit event. Instead of exiting the simulator, we just want to - # switch the processor. The 2nd 'm5 exit' after will revert to using - # default behavior where the simulator run will exit. - ExitEvent.EXIT : (func() for func in [processor.switch]), + ExitEvent.EXIT: exit_event_handler(), }, ) simulator.run() + ``` To recap what we learned in this tutorial: * The `requires` function can be used to specify the gem5 and host requirements for a script. * The `SimpleSwitchableProcessor` can be used to create a setup in which cores can be switched out for others. -* The `X86Board` can be used to setup full-system simulations. -Its `set_kernel_disk_workload` is used specify the kernel and disk image to use. +* The `X86Board` can be used to set up full-system simulations. +Its `set_kernel_disk_workload` is used to specify the kernel and disk image to use. * The `set_kernel_disk_work` accepts a `readfile_contents` argument. This is used to set the contents of the file to be read via gem5's `m5 readfile` function. -With the `x86-ubuntu-18.04-img` this is processed as a script to be executed after the system boot is complete. +This is processed as a script to be executed after the system boot is complete. * The `Simulator` module allows for the overriding of exit events using Python generators. diff --git a/_pages/documentation/gem5-stdlib/3-tutorial-developing-own-components.md b/_pages/documentation/gem5-stdlib/3-tutorial-developing-own-components.md index d493e63551..6828af2cae 100644 --- a/_pages/documentation/gem5-stdlib/3-tutorial-developing-own-components.md +++ b/_pages/documentation/gem5-stdlib/3-tutorial-developing-own-components.md @@ -7,6 +7,10 @@ permalink: /documentation/gem5-stdlib/develop-own-components-tutorial author: Bobby R. Bruce --- + + ## Developing your own gem5 standard library components ![gem5 component library design](/assets/img/stdlib/gem5-components-design.png) @@ -28,10 +32,15 @@ To begin, we should create a new Python class which inherits from the `AbstractC In this example we will call this `UniqueCacheHierarchy`, contained within a file `unique_cache_hierarchy.py`: ```python -from gem5.components.cachehierarchies.classic.abstract_classic_cache_hierarchy import AbstractClassicCacheHierarchy +from m5.objects import ( + Port, +) + from gem5.components.boards.abstract_board import AbstractBoard +from gem5.components.cachehierarchies.classic.abstract_classic_cache_hierarchy import ( + AbstractClassicCacheHierarchy, +) -from m5.objects import Port class UniqueCacheHierarchy(AbstractClassicCacheHierarchy): @@ -66,16 +75,23 @@ This has actually already been implemented in the gem5 stdlib as the [PrivateL1C First we start by implementing the `get_mem_side_port` and `get_cpu_side_port` functions: ```python -from gem5.components.cachehierarchies.classic.abstract_classic_cache_hierarchy import AbstractClassicCacheHierarchy +from m5.objects import ( + BadAddr, + Port, + SystemXBar, +) + from gem5.components.boards.abstract_board import AbstractBoard +from gem5.components.cachehierarchies.classic.abstract_classic_cache_hierarchy import ( + AbstractClassicCacheHierarchy, +) -from m5.objects import Port, SystemXBar, BadAddr class UniqueCacheHierarchy(AbstractClassicCacheHierarchy): def __init__(self) -> None: AbstractClassicCacheHierarchy.__init__(self=self) - self.membus = SystemXBar(width=64) + self.membus = SystemXBar(width=64) self.membus.badaddr_responder = BadAddr() self.membus.default = self.membus.badaddr_responder.pio @@ -94,19 +110,27 @@ Here we have used a simple memory bus. Next, we implement the `incorporate_cache` function: ```python -from gem5.components.cachehierarchies.classic.abstract_classic_cache_hierarchy import AbstractClassicCacheHierarchy +from m5.objects import ( + BadAddr, + Cache, + Port, + SystemXBar, +) + +from gem5.components.boards.abstract_board import AbstractBoard +from gem5.components.cachehierarchies.classic.abstract_classic_cache_hierarchy import ( + AbstractClassicCacheHierarchy, +) from gem5.components.cachehierarchies.classic.caches.l1dcache import L1DCache from gem5.components.cachehierarchies.classic.caches.l1icache import L1ICache from gem5.components.cachehierarchies.classic.caches.mmu_cache import MMUCache -from gem5.components.boards.abstract_board import AbstractBoard -from m5.objects import Port, SystemXBar, BadAddr, Cache class UniqueCacheHierarchy(AbstractClassicCacheHierarchy): def __init__(self) -> None: AbstractClassicCacheHierarchy.__init__(self=self) - self.membus = SystemXBar(width=64) + self.membus = SystemXBar(width=64) self.membus.badaddr_responder = BadAddr() self.membus.default = self.membus.badaddr_responder.pio @@ -134,11 +158,13 @@ class UniqueCacheHierarchy(AbstractClassicCacheHierarchy): ] # ITLB Page walk caches self.iptw_caches = [ - MMUCache(size="8KiB") for _ in range(board.get_processor().get_num_cores()) + MMUCache(size="8KiB") + for _ in range(board.get_processor().get_num_cores()) ] # DTLB Page walk caches self.dptw_caches = [ - MMUCache(size="8KiB") for _ in range(board.get_processor().get_num_cores()) + MMUCache(size="8KiB") + for _ in range(board.get_processor().get_num_cores()) ] if board.has_coherent_io(): @@ -194,7 +220,7 @@ Before contributing your component, you will need to move it into the `src/` dir The gem5 standard library code resides in `src/python/gem5`. The basic directory structure is as follows: -``` +```txt gem5/ components/ # All the components to build the system to simulate. boards/ # The boards, typically broken down by ISA target. @@ -216,7 +242,7 @@ We recommend putting the `unique_cache_hierarchy.py` in `src/python/gem5/compone From then you need to add the following line to `src/python/SConscript`: -``` +```scons PySource('gem5.components.cachehierarchies.classic', 'gem5/components/cachehierarchies/classic/unique_cache_hierarchy.py') ``` @@ -251,7 +277,7 @@ Please look over other source code in the stdlib to see how this is typically do For example, it will not reduce string lengths. You may have to manually reduce the length of some lines. -Code will be reviewed via our [Gerrit code review system](https://gem5-review.googlesource.com/) like all other contributions. +Code will be reviewed via [GitHub](https://github.com/gem5/gem5) like all other contributions. We would, however, emphasize that we will not accept patches to the library for simply being functional and tested; we require some persuasion that the contribution improves the library and benefits the community. For example, niche components may not be incorporated if they are seen to be low utility while increasing the library's maintenance overhead. diff --git a/_pages/documentation/gem5-stdlib/4-tutorial-creating-stdlib-board.md b/_pages/documentation/gem5-stdlib/4-tutorial-creating-stdlib-board.md index 05c510ef91..94f93fda8a 100644 --- a/_pages/documentation/gem5-stdlib/4-tutorial-creating-stdlib-board.md +++ b/_pages/documentation/gem5-stdlib/4-tutorial-creating-stdlib-board.md @@ -7,10 +7,16 @@ permalink: /documentation/gem5-stdlib/develop-stdlib-board author: Jasjeet Rangi, Kunal Pai --- -## How to Create Your Own Board Using the gem5 Standard Library + -In this tutorial we will cover how to create a custom board using the gem5 Standard Library. +## How to Create Your Own Board Using the gem5 Standard Library +In this tutorial we will cover how to create a custom board using the gem5 Standard Library. This tutorial is based on the process used to make the _RiscvMatched_, a RISC-V prebuilt board that inherits from `MinorCPU`. This board can be found at `src/python/gem5/prebuilt/riscvmatched`. @@ -21,18 +27,28 @@ Likewise, this tutorial will utilize the UniqueCacheHierarchy made in the [Devel First, we start by importing the components and stdlib features we require. ``` python -from gem5.components.cachehierarchies.classic.unique_cache_hierarchy import UniqueCacheHierarchy +from typing import List + +from m5.objects import ( + AddrRange, + BaseCPU, + BaseMMU, + IOXBar, + Port, + Process, +) +from m5.objects.RiscvCPU import RiscvMinorCPU + from gem5.components.boards.abstract_system_board import AbstractSystemBoard -from gem5.components.processors.base_cpu_processor import BaseCPUProcessor -from gem5.components.processors.base_cpu_core import BaseCPUCore from gem5.components.boards.se_binary_workload import SEBinaryWorkload +from gem5.components.cachehierarchies.classic.unique_cache_hierarchy import ( + UniqueCacheHierarchy, +) from gem5.components.memory import SingleChannelDDR4_2400 -from gem5.utils.override import overrides +from gem5.components.processors.base_cpu_core import BaseCPUCore +from gem5.components.processors.base_cpu_processor import BaseCPUProcessor from gem5.isas import ISA -from typing import List -from m5.objects import AddrRange, IOXBar, Port -from m5.objects import BaseMMU, Port, BaseCPU, Process -from m5.objects.RiscvCPU import RiscvMinorCPU +from gem5.utils.override import overrides ``` We will begin development by creating a specialized CPU core for our board which inherits from an ISA-specific version of the chosen CPU. @@ -41,7 +57,6 @@ This is done so that we can set our own parameters to tailor the CPU it to our r In our example will override a single parameter: `decodeToExecuteForwardDelay` (the default is 1). We have called this new CPU core type `UniqueCPU`. - ``` python class UniqueCPU(RiscvMinorCPU): decodeToExecuteForwardDelay = 2 @@ -52,10 +67,10 @@ The `BaseCPUCore` takes the `BaseCPU` as an argument during construction. Ergo, we can do the following: ```python -core = BaseCPUCore(core = UniqueCPU(core_id=0)) +core = BaseCPUCore(core=UniqueCPU(), isa=ISA.RISCV) ``` -**Note**: `BaseCPU` objects require a unique `core_id` to be specified upon construction. + Next we must define our processor. In the gem5 Standard Library a processor is a collection of cores. @@ -64,7 +79,7 @@ The `BaseCPUProcessor` requires a list of `BaseCPUCore`s. Therefore: ```python -processor = BaseCPUProcessor(cores = [core]) +processor = BaseCPUProcessor(cores=[core]) ``` Next we focus on the construction of the board to host our components. @@ -84,8 +99,8 @@ class UniqueBoard(AbstractSystemBoard, SEBinaryWorkload): self, clk_freq: str, ) -> None: - core = BaseCPUCore(core = UniqueCPU(core_id=0)) - processor = BaseCPUProcessor(cores = [core]) + core = BaseCPUCore(core=UniqueCPU(), isa=ISA.RISCV) + processor = BaseCPUProcessor(cores=[core]) memory = SingleChannelDDR4_2400("2GiB") cache_hierarchy = UniqueCacheHierarchy() super().__init__( @@ -113,8 +128,8 @@ class UniqueBoard(AbstractSystemBoard, SEBinaryWorkload): self, clk_freq: str, ) -> None: - core = BaseCPUCore(core = UniqueCPU(core_id=0)) - processor = BaseCPUProcessor(cores = [core]) + core = BaseCPUCore(core=UniqueCPU(), isa=ISA.RISCV) + processor = BaseCPUProcessor(cores=[core]) memory = SingleChannelDDR4_2400("2GiB") cache_hierarchy = UniqueCacheHierarchy() super().__init__( @@ -168,19 +183,111 @@ class UniqueBoard(AbstractSystemBoard, SEBinaryWorkload): memory.set_memory_range(self.mem_ranges) ``` - This concludes the creation of your custom board for the gem5 standard library. +The completed board is as follows: + +```python +from typing import List + +from m5.objects import ( + AddrRange, + BaseCPU, + BaseMMU, + IOXBar, + Port, + Process, +) +from m5.objects.RiscvCPU import RiscvMinorCPU + +from gem5.components.boards.abstract_system_board import AbstractSystemBoard +from gem5.components.boards.se_binary_workload import SEBinaryWorkload +from gem5.components.cachehierarchies.classic.unique_cache_hierarchy import ( + UniqueCacheHierarchy, +) +from gem5.components.memory import SingleChannelDDR4_2400 +from gem5.components.processors.base_cpu_core import BaseCPUCore +from gem5.components.processors.base_cpu_processor import BaseCPUProcessor +from gem5.isas import ISA +from gem5.utils.override import overrides + + +class UniqueCPU(RiscvMinorCPU): + decodeToExecuteForwardDelay = 2 + + +class UniqueBoard(AbstractSystemBoard, SEBinaryWorkload): + def __init__( + self, + clk_freq: str, + ) -> None: + core = BaseCPUCore(core=UniqueCPU(), isa=ISA.RISCV) + processor = BaseCPUProcessor(cores=[core]) + memory = SingleChannelDDR4_2400("2GiB") + cache_hierarchy = UniqueCacheHierarchy() + super().__init__( + clk_freq=clk_freq, + processor=processor, + memory=memory, + cache_hierarchy=cache_hierarchy, + ) + + @overrides(AbstractSystemBoard) + def _setup_board(self) -> None: + pass + + @overrides(AbstractSystemBoard) + def has_io_bus(self) -> bool: + return False + + @overrides(AbstractSystemBoard) + def get_io_bus(self) -> IOXBar: + raise NotImplementedError( + "UniqueBoard does not have an IO Bus. " + "Use `has_io_bus()` to check this." + ) + + @overrides(AbstractSystemBoard) + def has_dma_ports(self) -> bool: + return False + + @overrides(AbstractSystemBoard) + def get_dma_ports(self) -> List[Port]: + raise NotImplementedError( + "UniqueBoard does not have DMA Ports. " + "Use `has_dma_ports()` to check this." + ) + + @overrides(AbstractSystemBoard) + def has_coherent_io(self) -> bool: + return False + + @overrides(AbstractSystemBoard) + def get_mem_side_coherent_io_port(self) -> Port: + raise NotImplementedError( + "UniqueBoard does not have any I/O ports. Use has_coherent_io to " + "check this." + ) + + @overrides(AbstractSystemBoard) + def _setup_memory_ranges(self) -> None: + memory = self.get_memory() + self.mem_ranges = [AddrRange(memory.get_size())] + memory.set_memory_range(self.mem_ranges) + +``` + From this you can create a runscript and test your board: ``` python -from .unqiue_board import UniqueBoard -from gem5.resources.resource import Resource +from unique_board import UniqueBoard + +from gem5.resources.resource import obtain_resource from gem5.simulate.simulator import Simulator board = UniqueBoard(clk_freq="1.2GHz") -#As we are using the RISCV ISA, "riscv-hello" should work. -board.set_se_binary_workload(Resource("riscv-hello")) +# As we are using the RISCV ISA, "riscv-hello" should work. +board.set_se_binary_workload(obtain_resource("riscv-hello")) simulator = Simulator(board=board) simulator.run() diff --git a/_pages/documentation/gem5-stdlib/5-local-resources-support.md b/_pages/documentation/gem5-stdlib/5-local-resources-support.md index 4bd87b31c4..2a34407537 100644 --- a/_pages/documentation/gem5-stdlib/5-local-resources-support.md +++ b/_pages/documentation/gem5-stdlib/5-local-resources-support.md @@ -7,7 +7,7 @@ permalink: /documentation/gem5-stdlib/local-resources-support author: Kunal Pai, Harshil Patel --- -This tutorial will walk you through the process of creating a WorkloadResource in gem5 and testing it, through the new gem5 Resources infrastructure introduced in gem5 v23.0. +This tutorial will walk you through the process of creating a WorkloadResource in gem5 and testing it, through the gem5 Resources infrastructure introduced in gem5 v23.0. A workload is set to a board in gem5 through the following line: @@ -24,6 +24,7 @@ The function call specified in the `"function"` field of the Workload JSON is th ## Introduction + The gem5 Resources infrastructure allows adding a local JSON data source that can be added to the main gem5 Resources MongoDB database. We will use the local JSON data source to add a new WorkloadResource to gem5. @@ -41,6 +42,8 @@ In case the Resource already exists in gem5, you may skip this step. Let's assume that the Resource we want to wrap in a WorkloadResource is compiled for `RISC-V`, categorized as a `binary`, and has the name `my-benchmark`. We can define this Resource in a JSON object as follows: + + ``` json { @@ -67,6 +70,10 @@ Let's assume that the WorkloadResource we are building wraps `my-benchmark`, and We can define this WorkloadResource in a local JSON file as follows: + + + ``` json { "id": "binary-workload", @@ -79,9 +86,12 @@ We can define this WorkloadResource in a local JSON file as follows: "23.0" ], "resources": { - "binary": "my-benchmark" + "binary": { + "id": "my-benchmark", + "resource_version": "1.0.0" + } }, - "additional_parameters": { + "additional_params": { "arguments": ["arg1", "arg2"] } } @@ -101,6 +111,9 @@ To see more about the fields required and not required by the workloads, see the ## Testing the Workload To test the WorkloadResource, we first have to add the local JSON file as a data source for gem5. + This can be done by creating a new JSON file with the following format: @@ -114,6 +127,7 @@ This can be done by creating a new JSON file with the following format: } } ``` + On running gem5, if the new JSON config file you have created is present in the current working directory, it will be used as the data source for gem5. If the JSON file is not present in the current working directory, you can specify the path to the JSON file using the `GEM5_CONFIG` flag while building gem5. @@ -126,7 +140,7 @@ Its implementation can be found in [`src/python/gem5/resources/resource.py`](htt From gem5 v23.1, there are a couple additional ways to define your local `resources.json` file. Both these ways are through environment variables and are defined through the command line while running a gem5 simulation. -1. `GEM5_RESOURCE_JSON` variable: This variable substitutes all the current data sources used by gem5 with the JSON file present at the path passed in through this variable. +1. `GEM5_RESOURCE_JSON` variable: This variable substitutes all the current data sources used by gem5 with the JSON file present at the path passed in through this variable. This is equivalent to a gem5 data source configuration file as follows: ``` json @@ -150,7 +164,7 @@ This is equivalent to a gem5 data source configuration file as follows: "url": '/local/local.json', "isMongo": false, }, - "my-resources-2": { + "my-resources-2": { "url": $GEM5_RESOURCE_JSON_APPEND, "isMongo": false, }, @@ -159,6 +173,11 @@ This is equivalent to a gem5 data source configuration file as follows: ``` ## Support for Local Path to Resources + From gem5 v23.1, support has been added to make a workload of local resources through the method mentioned above. @@ -169,12 +188,14 @@ You can specify a path on your localhost and gem5 would be able to run it. With these changes, a JSON object for a local instance of `my-benchmark` would look like: + + ``` json { "category": "binary", "id": "my-benchmark", "description": "A RISCV binary used to test a specific RISCV instruction.", - "url": "file:/", + "url": "file:/", "architecture": "RISCV", "is_zipped": false, "resource_version": "1.1.0", diff --git a/_pages/documentation/gem5-stdlib/6-tutorial-suites.md b/_pages/documentation/gem5-stdlib/6-tutorial-suites.md index 2a0451d141..6dbc136629 100644 --- a/_pages/documentation/gem5-stdlib/6-tutorial-suites.md +++ b/_pages/documentation/gem5-stdlib/6-tutorial-suites.md @@ -9,7 +9,7 @@ author: Kunal Pai, Harshil Patel ## Introduction -Suite is a new category of resource introduced in gem5 version 23.1, which allows users to group workloads. +A suite is a resource category introduced in gem5 version 23.1 which allows users to group workloads. SuiteResource class is added to the resource specialization. Pre-made suites on the gem5 resources can be obtained using `obtain_resource()` like all other resources. @@ -23,7 +23,7 @@ To get a suite already in gem5 resources, we can use the `obtain_resource` funct To get a suite with ID “riscv-vertical-microbenchmarks” and version “1.0.0” ```python -suite_obj = obtain_resource(id = "riscv-vertical-microbenchmarks", resource_version="1.0.0") +suite_obj = obtain_resource("riscv-vertical-microbenchmarks", resource_version="1.0.0") ``` Not specifying the resource_version will return the latest compatible version of the resource. @@ -38,22 +38,22 @@ The workload field would look like the following: ```python [ - { - 'id': 'riscv-cca-run', - 'resource_version': '1.0.0', - 'input_group': ['cca'] - }, - { - 'id': 'riscv-cce-run', - 'resource_version': '1.0.0', - 'input_group': ['cce'] - }, - { - 'id': 'riscv-ccm-run', - 'resource_version': '1.0.0', - 'input_group': ['ccm'] - }, - ... + { + 'id': 'riscv-cca-run', + 'resource_version': '1.0.0', + 'input_group': ['cca'] + }, + { + 'id': 'riscv-cce-run', + 'resource_version': '1.0.0', + 'input_group': ['cce'] + }, + { + 'id': 'riscv-ccm-run', + 'resource_version': '1.0.0', + 'input_group': ['ccm'] + }, + ... ] ``` @@ -75,45 +75,49 @@ filtered_suite = suite_obj.with_input_group('cca') This will return a `SuiteResource` with all the workloads that fulfill the case of having input group “cca”, which in this case is the `WorkloadResource` with ID “riscv-cca-run”. -We can also use the `with_input_group()` function along with a for loop and a generator. + +We can also use the `with_input_group()` function along with a for loop and multisim: ```python -for workload in suite_obj.with_input_group('cca') - board.set_workload(workload) - simulator = Simulator(board=board) - simulator.run() -``` +import multisim -### Make a Custom Suite +# other imports -Custom suites can also be made by directly using the `SuiteResource` class from `[resource.py](http://resource.py)`. -To create a custom suite we will also need `WorkloadResource` objects. +multisim.set_num_processes(5) -```python -workload1= obtain_resource('workload-1', resource_version='1.0.0') -workload2= obtain_resource('workload-2', resource_version='1.0.0') +# set up the rest of the simulation -suite_obj = SuiteResource(workloads=[workload1, workload2]) +for workload in suite_obj.with_input_group('cca'): + board.set_workload(workload) + simulator = Simulator(board=board) + multisim.add_simulator(simulator=simulator) ``` -The above code snippet will create a suite object with two workloads. -We have not defined the `workloads` field in the above suite so the `get_input_group()` and `with_input_group()` functions will throw a warning and return an empty set and a suite object with no workloads respectively. +### Make a Custom Suite + + +Custom suites can also be made by directly using the `SuiteResource` class from `[resource.py](http://resource.py)`. +To create a custom suite we will also need `WorkloadResource` objects. -If the `workloads` field is added then the custom suite will function the same as a suite created by using `obtain_resource`. +The code snippet below shows how we can create a custom suite with two workloads. +The constructor of SuiteResource takes in a `Dict` with WorkloadResources as keys +and a `Set` of the input groups as values. ```python -workload1= obtain_resource('workload-1', resource_version='1.0.0') -workload2= obtain_resource('workload-2', resource_version='1.0.0') -workloads = [ - { - 'id': 'workload-1', - 'resource_version': '1.0.0', - 'input_group': ['input_group_1', 'input_group_2'] - }, - { - 'id': 'workload-2', - 'resource_version': '1.0.0', - 'input_group': ['input_group_1', 'input_group_3'] - }] -suite_obj = SuiteResource(workloads=[workload1, workload2], worklaods= workloads) +workload1 = obtain_resource('workload-1', resource_version='1.0.0') +workload2 = obtain_resource('workload-2', resource_version='1.0.0') +workloads = { + workload1: { + 'input_group_1', 'input_group_2' + }, + workload2: { + 'input_group_1', 'input_group_3' + } +} +suite_obj = SuiteResource(workloads=workloads) ``` diff --git a/_pages/documentation/gem5-stdlib/7-using-local-data-sources.md b/_pages/documentation/gem5-stdlib/7-using-local-data-sources.md index 7abff2bf2d..acaaa38084 100644 --- a/_pages/documentation/gem5-stdlib/7-using-local-data-sources.md +++ b/_pages/documentation/gem5-stdlib/7-using-local-data-sources.md @@ -7,6 +7,15 @@ permalink: /documentation/gem5-stdlib/using-local-resources author: Harshil Patel --- + + + + gem5 supports using local data sources in the form of a MongoDB Atlas and JSON datasource. gem5 has a default resources config in `src/python/gem5_default_config.py`. This resources config points to the MongoDB Atlas collection of gem5 resources. To utilize data sources other than the main gem5 resources database, you will need to override the gem5-resources-config. There are several ways to update the gem5 resources configuration: @@ -25,7 +34,6 @@ Additionally, if you wish to utilize or add a local resource JSON file to the cu It's essential to note that overriding or appending doesn't modify the actual configuration files themselves. These methods allow you to temporarily specify or add resource configurations during runtime without altering the original configuration files. - MongoDB Atlas Config Format: ```json @@ -56,6 +64,8 @@ JSON Config Format: } } ``` + + ### Setting up a MongoDB Atlas Database You would need to set up an Atlas cluster, steps on setting up an Atlas cluster can be found here: @@ -101,17 +111,19 @@ resource = obtain_resource("id", clients=["data-source-json-1"]) ### Understanding Local Resources -Local resources, in the context of gem5, pertain to resources that users possess and wish to integrate into gem5 but aren't pre-existing in the gem5 resources database. +Local resources in gem5 are resources that exist on a user's local machine, but +have not been uploaded to the gem5 resources database. -For users, This offers the flexibility to employ their own resources seamlessly within gem5, bypassing the need to create dedicated resource objects using `BinaryResource(local_path=/path/to/binary)`. Instead, they can directly utilize these local resources through `obtain_resource()`, streamlining the integration process. +For users, the option to add a JSON data source pointing to local resources allows them to use `obtain_resource()` for their own resources. +This bypasses the need to create dedicated resource objects using `BinaryResource(local_path=/path/to/binary)`, and streamlines the process of launching simulations. ### Using Custom Resource Configuration and Local Resources -In this example, we will walk through how to set up your custom configuration and utilize your own local resources. For this illustration, we'll employ a JSON file as our resource data source. +In this example, we will walk through how to set up your custom configuration and utilize your own local resources. For this example, we'll use a JSON file as our resource data source. #### Creating a Custom Resource Data Source -Let's begin by creating a local resource. This is a bare bones resource that will serve as an example. To use local resources with `obtain_resource()`, our bare bones resource need to have a binary file. Here we use an empty binary called `fake-binary`. +Let's begin by creating a local resource. This is a bare bones resource that will serve as an example. To use local resources with `obtain_resource()`, our bare bones resource need to have a binary file. Here we use an empty binary called `fake-binary`. **Note**: Make sure that Gem5 binary and `fake-binary` have same ISA target (RISCV here). @@ -162,25 +174,29 @@ Create a file named `gem5-config.json` with the following content: } } ``` + **Note**: It is implied that isMongo = false means that the data source is a JSON data source as gem5 currently only supports 2 types of data sources. #### Running gem5 with a Local Data Source -First, build gem5 with RISCV: +First, build gem5 with the ALL build, which contains RISCV: ```bash -scons build/RISCV/gem5.opt -j`nproc` +scons build/ALL/gem5.opt -j`nproc` ``` Next, run the `local-resource-example.py` file using our local `test-binary` resource: Using environment variable + ```bash -GEM5_RESOURCE_JSON_APPEND=path/to/my-resources.json ./build/RISCV/gem5.opt configs/example/gem5_library/local-resource-example.py --resource test-binary +GEM5_RESOURCE_JSON_APPEND=path/to/my-resources.json ./build/ALL/gem5.opt configs/example/gem5_library/local-resource-example.py --resource test-binary ``` + or you can overwrite the `gem5_default_config` with our own custom config: ```bash -GEM5_CONFIG=path/to/gem5-config.json ./build/RISCV/gem5.opt configs/example/gem5_library/local-resource-example.py --resource test-binary +GEM5_CONFIG=path/to/gem5-config.json ./build/ALL/gem5.opt configs/example/gem5_library/local-resource-example.py --resource test-binary ``` + This command will execute the `local-resource-example.py` script using our locally downloaded resource. This script just calls the obtain_resource function and prints the local path of the resource. This script indicates that local resources function similarly as resources on the gem5 resources database. diff --git a/_pages/documentation/gem5art/introduction.md b/_pages/documentation/gem5art/introduction.md index 30b6eadd53..b07e637c38 100644 --- a/_pages/documentation/gem5art/introduction.md +++ b/_pages/documentation/gem5art/introduction.md @@ -6,6 +6,9 @@ parent: gem5art permalink: /documentation/gem5art/introduction --- + + # Zen and the art of gem5 experiments gem5art-logo diff --git a/_pages/documentation/general_docs/apis.md b/_pages/documentation/general_docs/apis.md index 355a6b6cee..67614e72a9 100644 --- a/_pages/documentation/general_docs/apis.md +++ b/_pages/documentation/general_docs/apis.md @@ -7,6 +7,10 @@ permalink: /documentation/general_docs/gem5-apis/ authors: Bobby R. Bruce --- + + For complete documentation of all methods and variables tagged as APIs, please see our [Doxygen Module page]( http://doxygen.gem5.org/release/v20-1-0-0/modules.html). @@ -22,6 +26,7 @@ manner between gem5 releases. ## How is the gem5 API documented? + We document the gem5 APIs using the [Doxygen documentation generation tool]( https://www.doxygen.nl/index.html). This means you may see the API tagged at the level of source-code and via our [web-based documentation]( @@ -203,7 +208,7 @@ will be displayed to the user as a warning if `master` or `slave` are ever used. As with all changes to the gem5 source, these changes will have to go through -our Gerrit code review system before being merged into the `develop` branch, +code review on GitHub before being merged into the `develop` branch, and eventually making its way to our `stable` branch as part of a gem5 release. In line with our API policy, these deprecated APIs must exist in a marked-as-deprecated state for two gem5 major release cycles. After this they diff --git a/_pages/documentation/general_docs/architecture_support/arm_implementation.md b/_pages/documentation/general_docs/architecture_support/arm_implementation.md index aed4cc987a..93a430e2b3 100644 --- a/_pages/documentation/general_docs/architecture_support/arm_implementation.md +++ b/_pages/documentation/general_docs/architecture_support/arm_implementation.md @@ -8,6 +8,9 @@ permalink: /documentation/general_docs/architecture_support/arm_implementation/ # ARM Implementation + ## Supported features and modes The ARM Architecture models within gem5 support an [ARMv8.0-A](https://developer.arm.com/docs/den0024/latest/armv8-a-architecture-and-processors/armv8-a) profile of the ARM® architecture with multi-processor extensions. diff --git a/_pages/documentation/general_docs/architecture_support/index.md b/_pages/documentation/general_docs/architecture_support/index.md index b06f71482e..a3b78308d3 100644 --- a/_pages/documentation/general_docs/architecture_support/index.md +++ b/_pages/documentation/general_docs/architecture_support/index.md @@ -7,7 +7,8 @@ permalink: /documentation/general_docs/architecture_support/ --- # Architecture Support - + {: .outdated-notice} The information and hyperlinks in this page may not be accurate. diff --git a/_pages/documentation/general_docs/architecture_support/isa_parser.md b/_pages/documentation/general_docs/architecture_support/isa_parser.md index fb7e10620a..cb7954b66f 100644 --- a/_pages/documentation/general_docs/architecture_support/isa_parser.md +++ b/_pages/documentation/general_docs/architecture_support/isa_parser.md @@ -6,6 +6,9 @@ parent: architecture_support permalink: documentation/general_docs/architecture_support/isa_parser/ --- + + # ISA Parser The gem5 ISA description language is a custom language designed specifically for generating the class definitions and decoder function needed by gem5. This section provides a practical, informal overview of the language itself. A formal grammar for the language is embedded in the "yacc" portion of the parser (look for the functions starting with p\_ in isa\_parser.py). A second major component of the parser processes C-like code specifications to extract instruction characteristics; this aspect is covered in the section [Code parsing](#code-parsing). diff --git a/_pages/documentation/general_docs/architecture_support/x86_microop_isa.md b/_pages/documentation/general_docs/architecture_support/x86_microop_isa.md index ed309d59dc..5311ec33cf 100644 --- a/_pages/documentation/general_docs/architecture_support/x86_microop_isa.md +++ b/_pages/documentation/general_docs/architecture_support/x86_microop_isa.md @@ -6,6 +6,9 @@ parent: architecture_support permalink: documentation/general_docs/architecture_support/x86_microop_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. diff --git a/_pages/documentation/general_docs/building/extras.md b/_pages/documentation/general_docs/building/extras.md index 030790566e..a2ae80b0f5 100644 --- a/_pages/documentation/general_docs/building/extras.md +++ b/_pages/documentation/general_docs/building/extras.md @@ -7,12 +7,15 @@ permalink: /documentation/general_docs/building/EXTRAS authors: Jason Lowe-Power --- + + # Building EXTRAS The `EXTRAS` SCons option is a way to add functionality in gem5 without adding your files to the gem5 source tree. Specifically, it allows you to identify one or more directories that will get compiled in with gem5 as if they appeared under the 'src' part of the gem5 tree, without requiring the code to be actually located under 'src'. It's present to allow user to compile in additional functionality (typically additional SimObject classes) that isn't or can't be distributed with gem5. This is useful for maintaining local code that isn't suitable for incorporating into the gem5 source tree, or third-party code that can't be incorporated due to an incompatible license. Because the EXTRAS location is completely independent of the gem5 repository, you can keep the code under a different version control system as well. The main drawback of the EXTRAS feature is that, by itself, it only supports adding code to gem5, not modifying any of the base gem5 code. One use of the EXTRAS feature is to support EIO traces. The trace reader for EIO is licensed under the SimpleScalar license, and due to the incompatibility of that license with gem5's BSD license, the code to read these traces is not included in the gem5 distribution. Instead, the EIO code is distributed via a separate "encumbered" [repository](https://github.com/gem5/gem5). + The following examples show how to compile the EIO code. By adding to or modifying the extras path, any other suitable extra could be compiled in. To compile in code using EXTRAS simply execute the following diff --git a/_pages/documentation/general_docs/building/index.md b/_pages/documentation/general_docs/building/index.md index c883868071..129eca5fbe 100644 --- a/_pages/documentation/general_docs/building/index.md +++ b/_pages/documentation/general_docs/building/index.md @@ -12,14 +12,14 @@ authors: Bobby R. Bruce ## Supported operating systems and environments gem5 has been designed with a Linux environment in mind. We test regularly -on **Ubuntu 20.04**, **Ubuntu 22.04** and **Ubuntu 24.04** to ensure gem5 functions well in +on **Ubuntu 22.04** and **Ubuntu 24.04** to ensure gem5 functions well in these environments. Though **any Linux based OS should function if the correct dependencies are installed**. We ensure that gem5 is compilable with both gcc and clang (see [Dependencies](#dependencies) below for compiler version information). -As of gem5 21.0, **we support building and running gem5 with Python 3.6+ -only**. gem5 20.0 was our last version of gem5 to provide support for Python +As of gem5 v25.0, **we support building and running gem5 with Python 3.9+ only**. +gem5 20.0 was our last version of gem5 to provide support for Python 2. If running gem5 in a suitable OS/environment is not possible, we have provided @@ -30,14 +30,14 @@ information on this. ## Dependencies * **git** : gem5 uses git for version control. -* **gcc**: gcc is used to compiled gem5. **Version >=10 must be used**. We -support up to gcc Version 13. -* **Clang**: Clang can also be used. At present, we support Clang 7 to -Clang 16 (inclusive). +* **gcc**: GCC is used to compiled gem5. As of gem5 v25.0, we support GCC 11 to +GCC 14 (inclusive). +* **Clang**: Clang can also be used. As of gem5 v25.0, we support Clang 14 to +Clang 19 (inclusive). * **SCons** : gem5 uses SCons as its build environment. SCons 3.0 or greater must be used. -* **Python 3.6+** : gem5 relies on Python development libraries. gem5 can be -compiled and run in environments using Python 3.6+. +* **Python 3.9+** : gem5 relies on Python development libraries. gem5 can be +compiled and run in environments using Python 3.9+. * **protobuf 2.1+** (Optional): The protobuf library is used for trace generation and playback. * **Boost** (Optional): The Boost library is a set of general purpose C++ @@ -49,7 +49,7 @@ implementation. If compiling gem5 on Ubuntu 24.04, or related Linux distributions, you may install all these dependencies using APT: -``` +```bash sudo apt install build-essential scons python3-dev git pre-commit zlib1g zlib1g-dev \ libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev \ libboost-all-dev libhdf5-serial-dev python3-pydot python3-venv python3-tk mypy \ @@ -61,10 +61,11 @@ sudo apt install build-essential scons python3-dev git pre-commit zlib1g zlib1g- If compiling gem5 on Ubuntu 22.04, or related Linux distributions, you may install all these dependencies using APT: -``` +```bash sudo apt install build-essential git m4 scons zlib1g zlib1g-dev \ libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev \ - python3-dev libboost-all-dev pkg-config python3-tk + python3-dev doxygen libboost-all-dev libhdf5-serial-dev python3-pydot \ + libpng-dev libelf-dev pkg-config pip python3-venv black python3-tk wget ``` ### Setup on Ubuntu 20.04 (gem5 >= v21.0) @@ -72,72 +73,76 @@ sudo apt install build-essential git m4 scons zlib1g zlib1g-dev \ If compiling gem5 on Ubuntu 20.04, or related Linux distributions, you may install all these dependencies using APT: -``` +```bash sudo apt install build-essential git m4 scons zlib1g zlib1g-dev \ libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev \ python3-dev python-is-python3 libboost-all-dev pkg-config gcc-10 g++-10 \ python3-tk ``` - ### Docker For users struggling to setup an environment to build and run gem5, we provide the following Docker Images: Ubuntu 24.04 with all optional dependencies: -[ghcr.io/gem5/ubuntu-24.04_all-dependencies:v24-0]( -https://ghcr.io/gem5/ubuntu-24.04_all-dependencies:v24-0) -([source Dockerfile](https://github.com/gem5/gem5/blob/v24.0.0.0/util/dockerfiles/ubuntu-24.04_all-dependencies/Dockerfile)). +[ghcr.io/gem5/ubuntu-24.04_all-dependencies:v25-0]( +https://ghcr.io/gem5/ubuntu-24.04_all-dependencies:v25-0) +([source Dockerfile](https://github.com/gem5/gem5/blob/v25.0.0.0/util/dockerfiles/ubuntu-24.04_all-dependencies/Dockerfile)). Ubuntu 24.04 with minimum dependencies: -[ghcr.io/gem5/ubuntu-24.04_min-dependencies:v24-0]( -https://ghcr.io/gem5/ubuntu-24.04_min-dependencies:v24-0) -([source Dockerfile](https://github.com/gem5/gem5/blob/v24.0.0.0/util/dockerfiles/ubuntu-24.04_min-dependencies/Dockerfile)). +[ghcr.io/gem5/ubuntu-24.04_min-dependencies:v25-0]( +https://ghcr.io/gem5/ubuntu-24.04_min-dependencies:v25-0) +([source Dockerfile](https://github.com/gem5/gem5/blob/v25.0.0.0/util/dockerfiles/ubuntu-24.04_min-dependencies/Dockerfile)). Ubuntu 22.04 with all optional dependencies: -[ghcr.io/gem5/ubuntu-22.04_all-dependencies:v23-0]( -https://ghcr.io/gem5/ubuntu-22.04_all-dependencies:v23-0) ([source Dockerfile]( -https://github.com/gem5/gem5/blob/v23.0.1.0/util/dockerfiles/ubuntu-22.04_all-dependencies/Dockerfile)). +[ghcr.io/gem5/ubuntu-22.04_all-dependencies:v25-0]( +https://ghcr.io/gem5/ubuntu-22.04_all-dependencies:v25-0) ([source Dockerfile]( +https://github.com/gem5/gem5/blob/v25.0.0.0/util/dockerfiles/ubuntu-22.04_all-dependencies/Dockerfile)). -Ubuntu 20.04 with all optional dependencies: -[ghcr.io/gem5/ubuntu-20.04_all-dependencies:v23-0]( -https://ghcr.io/gem5/ubuntu-20.04_all-dependencies:v23-0) ([source Dockerfile]( -https://github.com/gem5/gem5/blob/v23.0.1.0/util/dockerfiles/ubuntu-20.04_all-dependencies/Dockerfile)). +Ubuntu 20.04 with all optional dependencies, which is no longer being maintained: +[ghcr.io/gem5/ubuntu-20.04_all-dependencies:v24-0]( +https://ghcr.io/gem5/ubuntu-20.04_all-dependencies:v24-0) ([source Dockerfile]( +https://github.com/gem5/gem5/blob/v24.0.0.0/util/dockerfiles/ubuntu-20.04_all-dependencies/Dockerfile)). -Ubuntu 18.04 with all optional dependencies: -[ghcr.io/gem5/ubuntu-18.04_all-dependencies:v23-0]( -https://ghcr.io/gem5/ubuntu-18.04_all-dependencies:v23-0) ([source Dockerfile]( -https://github.com/gem5/gem5/blob/v23.0.1.0/util/dockerfiles/ubuntu-18.04_all-dependencies/Dockerfile)). +Ubuntu 18.04 with all optional dependencies, which is no longer being maintained: +[ghcr.io/gem5/ubuntu-18.04_all-dependencies:v22-1]( +https://ghcr.io/gem5/ubuntu-18.04_all-dependencies:v22-1) ([source Dockerfile]( +https://github.com/gem5/gem5/blob/v22.1.0.0/util/dockerfiles/ubuntu-18.04_all-dependencies/Dockerfile)). To obtain a docker image: -``` +```bash docker pull ``` -E.g., for Ubuntu 20.04 with all optional dependencies: +E.g., for Ubuntu 24.04 with all optional dependencies: + +```bash +# For the latest version +docker pull ghcr.io/gem5/ubuntu-24.04_all-dependencies:latest + +# For the version created for a certain gem5 release +docker pull ghcr.io/gem5/ubuntu-24.04_all-dependencies:v25-0 -``` -docker pull ghcr.io/gem5/ubuntu-20.04_all-dependencies:v23-0 ``` Then, to work within this environment, we suggest using the following: -``` +```bash docker run -u $UID:$GID --volume :/gem5 --rm -it ``` Where `` is the full path of the gem5 in your file system, and -`` is the image pulled (e.g., -ghcr.io/gem5/ubuntu-22.04_all-dependencies:v23-0`). +`` is the image pulled (e.g. +`docker pull ghcr.io/gem5/ubuntu-24.04_all-dependencies:latest`). From this environment, you will be able to build and run gem5 from the `/gem5` directory. ## Getting the code -``` +```bash git clone https://github.com/gem5/gem5 ``` @@ -151,7 +156,7 @@ tree, usually near the files they're associated with. Within the root of the gem5 directory, gem5 can be built with SCons using: -``` +```bash scons build/{ISA}/gem5.{variant} -j {cpus} ``` @@ -164,6 +169,7 @@ some systems. We therefore strongly advise allocating more threads if possible. The valid ISAs are: +* ALL - recommended, as it has all ISAs and all Ruby protocols as of gem5 v24.1 * ARM * NULL * MIPS @@ -199,10 +205,10 @@ These versions are summarized in the following table. |**opt** |X |X | |**fast** |X | | -For example, to build gem5 on 4 threads with `opt` and targeting x86: +For example, to build gem5 on 4 threads with `opt` and with all ISAs: -``` -scons build/X86/gem5.opt -j 4 +```bash +scons build/ALL/gem5.opt -j 4 ``` In addition, users may make use of the "gprof" and "pperf" build options to @@ -210,10 +216,10 @@ enable profiling: * **gprof** allows gem5 to be used with the gprof profiling tool. It can be enabled by compiling with the `--gprof` flag. E.g., -`scons build/ARM/gem5.debug --gprof`. +`scons build/ALL/gem5.debug --gprof`. * **pprof** allows gem5 to be used with the pprof profiling tool. It can be enabled by compiling with the `--pprof` flag. E.g., -`scons build/X86/gem5.debug --pprof`. +`scons build/ALL/gem5.debug --pprof`. ## Build with Kconfig @@ -223,13 +229,19 @@ Please see [here](https://www.gem5.org/documentation/general_docs/kconfig_build_ Once compiled, gem5 can then be run using: -``` +```console ./build/{ISA}/gem5.{variant} [gem5 options] {simulation script} [script options] ``` -Running with the `--help` flag will display all the available options: +If you are building gem5 from a pre-compiled binary, gem5 can be run with the following command: +```console +gem5 [gem5 options] {simulation script} [script options] ``` + +Running with the `--help` flag will display all the available options: + +```txt Usage ===== gem5.opt [gem5 options] script.py [script options] diff --git a/_pages/documentation/general_docs/checkpoints.md b/_pages/documentation/general_docs/checkpoints.md index 87ab34024b..83db5b330d 100644 --- a/_pages/documentation/general_docs/checkpoints.md +++ b/_pages/documentation/general_docs/checkpoints.md @@ -6,30 +6,44 @@ parent: checkpoints permalink: /documentation/general_docs/checkpoints/ --- -# Checkpoints # -Checkpoints are essentially snapshops of a simulation. You would want to use a checkpoint when your simulation takes an extremely long time (which is almost always the case) so you can resume from that checkpoint at a later time with the DerivO3CPU. -## Creation ## -First of all, you need to create a checkpoint. Each checkpoint as saved in a new directory named 'cpt.TICKNUMBER', where TICKNUMBER refers to the tick value at which this checkpoint was created. There are several ways in which a checkpoint can be created: + + +# Checkpoints + +Checkpoints are essentially snapshots of a simulation. You would want to use a checkpoint when your simulation takes an extremely long time (which is almost always the case) so you can resume from that checkpoint at a later time with the DerivO3CPU. + +## Creation + + + +First of all, you need to create a checkpoint. Each checkpoint as saved in a new directory named 'cpt.TICKNUMBER', where TICKNUMBER refers to the tick value at which this checkpoint was created. There are several ways in which a checkpoint can be created: + * After booting the gem5 simulator, execute the command m5 checkpoint. One can execute the command manually using m5term, or include it in a run script to do this automatically after the Linux kernel has booted up. * There is a pseudo instruction that can be used for creating checkpoints. For example, one may include this pseudo instruction in an application program, so that the checkpoint is created when the application has reached a certain state. * The option **-****-take-checkpoints** can be provided to the python scripts (fs.py, ruby_fs.py) so that checkpoints are dumped periodically. The option **-****-checkpoint-at-end** can be used for creating the checkpoint at the end of the simulation. Take a look at the file **configs/common/Options.py** for these options. + While creating checkpoints with Ruby memory model, it is necessary to use the MOESI hammer protocol. This is because checkpointing the correct memory state requires that the caches are flushed to the memory. This flushing operation is currently supported only with the MOESI hammer protocol. -## Restoring ## +## Restoring + + Restoring from a checkpoint can usually be easily done from the command line, e.g.: -``` - build//gem5.debug configs/example/fs.py -r N +```console + build/ALL/gem5.debug configs/example/fs.py -r N OR - build//gem5.debug configs/example/fs.py --checkpoint-restore=N + build/ALL/gem5.debug configs/example/fs.py --checkpoint-restore=N ``` + + The number N is integer that represents checkpoint number which usually starts from 1 then increases incrementally to 2,3,4... By default, gem5 assumes that the checkpoint is to be restored using Atomic CPUs. This may not work if the checkpoint was recorded using Timing / Detailed / Inorder CPU. One can mention the option
**-****-restore-with-cpu \** on the command line. The cpu type supplied with this option is then used for restoring from the checkpoint. -## Detailed example: Parsec ## +## Detailed example: Parsec + In the following section we would describe how checkpoints are created for workloads PARSEC benchmark suite. However similar procedure can be followed to create checkpoint for other workloads beyond PARSEC suite. Following are the high level steps of creating checkpoint: 1. Annotate each workload with start and end of Region of Interest and with start and end of work units in the program. @@ -39,7 +53,8 @@ In the following section we would describe how checkpoints are created for workl 5. Take warm up cache trace for Ruby before reaching most interesting portion of the program and take the final checkpoint. In each of the following sections we explain each of the above steps in more details. -### Annotating workloads ### +### Annotating workloads + Annotation is required for two purposes: for defining region of program beyond the initialization section of a program and for defining logical units of work in each of the workloads. Workloads in PARSEC benchmark suite, already has annotating demarcating start and end of portion of program without program initialization section and program finalization section. We just use gem5 specific annotation for start of Region of Interest. The start of the Region of Interest (ROI) is marked by **m5_roi_begin()** and the end of ROI is demarcated by **m5_roi_end()**. @@ -47,8 +62,13 @@ Workloads in PARSEC benchmark suite, already has annotating demarcating start an Due to large simulation time its not always possible to simulate whole program. Moreover, unlike single threaded programs, simulating for a given number instructions in multi-threaded workloads is not a correct way to simulate portion of a program due to possible presence of instructions spinning on synchronization variable. Thus it is important define semantically meaningful logical units of work in each workload. Simulating for a given number of workuints in a multi-threaded workloads gives a reasonable way of simulating portion of workloads as the problem of instructions spinning on synchronization variables. # Switchover/Fastforwarding + ## Sampling + + + Sampling (switching between functional and detailed models) can be implemented via your Python script. In your script you can direct the simulator to switch between two sets of CPUs. To do this, in your script setup a list of tuples of (oldCPU, newCPU). If there are multiple CPUs you wish to switch simultaneously, they can all be added to that list. For example: + ```python run_cpu1 = SimpleCPU() switch_cpu1 = DetailedCPU(switched_out=True) @@ -56,12 +76,15 @@ run_cpu2 = SimpleCPU() switch_cpu2 = FooCPU(switched_out=True) switch_cpu_list = [(run_cpu1,switch_cpu1),(run_cpu2,switch_cpu2)] ``` + Note that the CPU that does not immediately run should have the parameter "switched_out=True". This keeps those CPUs from adding themselves to the list of CPUs to run; they will instead get added when you switch them in. In order for gem5 to instantiate all of your CPUs, you must make the CPUs that will be switched in a child of something that is in the configuration hierarchy. Unfortunately at the moment some configuration limitations force the switch CPU to be placed outside of the System object. The Root object is the next most convenient place to place the CPU, as shown below: + ```python m5.simulate(500) # simulate for 500 cycles m5.switchCpus(switch_cpu_list) m5.simulate(500) # simulate another 500 cycles after switching ``` + Note that gem5 may have to simulate for a few cycles prior to switching CPUs due to any outstanding state that may be present in the CPUs being switched out. diff --git a/_pages/documentation/general_docs/common-errors.md b/_pages/documentation/general_docs/common-errors.md index c60220df84..a7eb766ef9 100644 --- a/_pages/documentation/general_docs/common-errors.md +++ b/_pages/documentation/general_docs/common-errors.md @@ -6,6 +6,10 @@ parent: common-errors permalink: /documentation/general_docs/common-errors/ --- + + Here are some common issues that users run into when using gem5, and information on how to fix them on how to fix them. ## Segmentation Fault @@ -66,7 +70,6 @@ build/ALL/cpu/base.cc:186: fatal: Number of processes (cpu.workload) (0) assigne This type of error can cover situations such as wrong file types or invalid values being passed to gem5, or unconnected ports, just to name a couple examples. This should give you more information on the issue at hand, but if there still isn't enough information, using some of the [debugging techniques](https://www.gem5.org/documentation/general_docs/debugging_and_testing/debugging/trace_based_debugging) within gem5, such as gdb or debug flags may help. - ## Panic If you encounter a panic error, that usually indicates that something is wrong with gem5 itself. @@ -121,6 +124,7 @@ IOError: Can't find file 'linux-bigswap2.img' on path. Looking within this file should give you more information to help debug, though if this isn't enough, you can look [here](https://www.gem5.org/documentation/general_docs/debugging_and_testing/debugging/trace_based_debugging) to enable trace based debugging for further information. ## PreCommit + If you're running into errors when pushing code to the develop branch, one potential issue is that you may not be passing the precommit checks that gem5 requires before any changes are submitted. If you see within Gerrit that you have the following error on your verified check, you can navigate to the logs that were output by the tests. @@ -150,6 +154,8 @@ When running these commands, pre-commit will both detect any style issues, and a ## Change-ID + + If you're running into issues getting you continuous integration tests to pass on GitHub, you may be forgetting to add a Change-Id to your commit message. Though we have migrated away from using Gerrit, we still require the addition of a Change-Id. In order to amend your commit and have all our checks pass, you must install the commit message hook from Gerrit. diff --git a/_pages/documentation/general_docs/compiling_workloads/index.md b/_pages/documentation/general_docs/compiling_workloads/index.md index 2e1ad0801e..05d672293e 100644 --- a/_pages/documentation/general_docs/compiling_workloads/index.md +++ b/_pages/documentation/general_docs/compiling_workloads/index.md @@ -12,16 +12,17 @@ author: "Hoa Nguyen" ## Cross Compilers A cross compiler is a compiler set up to run on one ISA but generate binaries which run on another. + You may need one if you intend to simulate a system which uses a particular ISA, Alpha for instance, but don't have access to actual Alpha hardware. There are various sources for cross compilers. The following are some of them. -1. [ARM](https://packages.debian.org/stretch/gcc-arm-linux-gnueabihf). +1. [ARM](https://packages.debian.org/stretch/gcc-arm-linux-gnueabihf). 2. [RISC-V](https://github.com/riscv/riscv-gnu-toolchain). ## QEMU Alternatively, you can use QEMU and a disk image to run the desired ISA in emulation. -To create more recent disk images, see [this page](/documentation/general_docs/fullsystem/disk). +To create more recent disk images, see [this page](/documentation/general_docs/fullsystem/disks). The following is a youtube video of working with image files using qemu on Ubuntu 12.04 64bit. diff --git a/_pages/documentation/general_docs/cpu_models/execution_basics.md b/_pages/documentation/general_docs/cpu_models/execution_basics.md index cdbad1f70d..7d375e7cde 100644 --- a/_pages/documentation/general_docs/cpu_models/execution_basics.md +++ b/_pages/documentation/general_docs/cpu_models/execution_basics.md @@ -6,12 +6,24 @@ parent: cpu_models permalink: /documentation/general_docs/cpu_models/execution_basics --- + + # Execution basic +## gem5 bootcamp 2024 module on instructions + +The 2024 gem5 bootcamp included a session on learning how instructions work in gem5 and how to add new instructions in gem5. + +The slides can be found on the [2024 bootcamp website](https://bootcamp.gem5.org/#03-Developing-gem5-models/05-modeling-cores). + ## gem5 bootcamp 2022 module on instruction execution gem5 bootcamp (2022) had a session on learning how instructions work in gem5 and how to add new instructions in gem5. -The slides presented in the session can be found [here](https://ucdavis365-my.sharepoint.com/:p:/g/personal/jlowepower_ucdavis_edu/EeRIKzkdUJBDlaa9AmzERusBp28hxMfkyIOp-_2H5L9AqQ?e=RoMFUD). + The youtube video of the recorded bootcamp module on gem5 instructions is available [here](https://youtu.be/Z5B02jkNpck). diff --git a/_pages/documentation/general_docs/cpu_models/index.md b/_pages/documentation/general_docs/cpu_models/index.md index d4c5ddfab2..acc9c95daf 100644 --- a/_pages/documentation/general_docs/cpu_models/index.md +++ b/_pages/documentation/general_docs/cpu_models/index.md @@ -6,9 +6,15 @@ parent: cpu_models permalink: /documentation/general_docs/cpu_models/ --- +## gem5 bootcamp 2024 module on using CPU models + +The 2024 gem5 bootcamp had a session on learning the use of different gem5 CPU models. + +The slides can be found on [2024 bootcamp website](https://bootcamp.gem5.org/#02-Using-gem5/04-cores) + ## gem5 bootcamp 2022 module on using CPU models gem5 bootcamp (2022) had a session on learning the use of different gem5 CPU models. -The slides presented in the session can be found [here](https://ucdavis365-my.sharepoint.com/:p:/g/personal/jlowepower_ucdavis_edu/EYRn68yb9nZJk9Puf7dV40YBm25hQ91WCXnEwyjqniqeVQ?e=7Xo0). + The youtube video of the recorded bootcamp module on gem5 CPU models is available [here](https://youtu.be/cDv-g-c0XCY). \ No newline at end of file diff --git a/_pages/documentation/general_docs/cpu_models/minor_cpu.md b/_pages/documentation/general_docs/cpu_models/minor_cpu.md index 643180fae1..6f70c6d2fb 100644 --- a/_pages/documentation/general_docs/cpu_models/minor_cpu.md +++ b/_pages/documentation/general_docs/cpu_models/minor_cpu.md @@ -7,12 +7,17 @@ permalink: /documentation/general_docs/cpu_models/minor_cpu author: Andrew Bardsley --- -Minor CPU Model + +Minor CPU Model + This document contains a description of the structure and function of the [Minor](http://doxygen.gem5.org/release/current/namespaceMinor.html) gem5 in-order processor model. + It is recommended reading for anyone who wants to understand [Minor](http://doxygen.gem5.org/release/current/namespaceMinor.html)'s internal organisation, design decisions, C++ implementation and Python configuration. A @@ -23,7 +28,7 @@ and to explain its general structure without being too slavish about naming every function and data type. ## What is Minor? - + [Minor](http://doxygen.gem5.org/release/current/namespaceMinor.html) is an in-order processor model with a fixed pipeline but configurable data structures and execute behaviour. It is intended to be used to model processors with strict diff --git a/_pages/documentation/general_docs/cpu_models/o3cpu.md b/_pages/documentation/general_docs/cpu_models/o3cpu.md index b3972cf570..20fc412430 100644 --- a/_pages/documentation/general_docs/cpu_models/o3cpu.md +++ b/_pages/documentation/general_docs/cpu_models/o3cpu.md @@ -6,6 +6,8 @@ parent: cpu_models permalink: /documentation//general_docs/cpu_models/O3CPU --- + + # **O3CPU** Table of Contents @@ -16,7 +18,7 @@ Table of Contents 4. [ISA independence](##ISA-independence) 5. [Interaction with ThreadContext](##Interaction-with-ThreadContext**) -The O3CPU is our new detailed model for the v2.0 release. It is an out of order CPU model loosely based on the Alpha 21264. This page will give you a general overview of the O3CPU model, the pipeline stages and the pipeline resources. We have made efforts to keep the code well documented, so please browse the code for exact details on how each part of the O3CPU works. +The O3CPU is an out of order CPU model loosely based on the Alpha 21264. This page will give you a general overview of the O3CPU model, the pipeline stages and the pipeline resources. ## **Pipeline stages** diff --git a/_pages/documentation/general_docs/cpu_models/simplecpu.md b/_pages/documentation/general_docs/cpu_models/simplecpu.md index 31581951df..f71a798508 100644 --- a/_pages/documentation/general_docs/cpu_models/simplecpu.md +++ b/_pages/documentation/general_docs/cpu_models/simplecpu.md @@ -5,6 +5,11 @@ doc: gem5 documentation parent: cpu_models permalink: /documentation/general_docs/cpu_models/SimpleCPU --- + + + # **SimpleCPU** The SimpleCPU is a purely functional, in-order model that is suited for cases where a detailed model is not necessary. This can include warm-up periods, client systems that are driving a host, or just testing to make sure a program works. diff --git a/_pages/documentation/general_docs/cpu_models/tracecpu.md b/_pages/documentation/general_docs/cpu_models/tracecpu.md index 2c658866e7..62e6de1850 100644 --- a/_pages/documentation/general_docs/cpu_models/tracecpu.md +++ b/_pages/documentation/general_docs/cpu_models/tracecpu.md @@ -5,6 +5,11 @@ parent: cpu_models doc: gem5 documentation permalink: /documentation/general_docs/cpu_models/TraceCPU --- + + + # **TraceCPU** Table of Contents diff --git a/_pages/documentation/general_docs/cpu_models/visualization.md b/_pages/documentation/general_docs/cpu_models/visualization.md index b4085350ef..65e2d3f185 100644 --- a/_pages/documentation/general_docs/cpu_models/visualization.md +++ b/_pages/documentation/general_docs/cpu_models/visualization.md @@ -6,6 +6,10 @@ parent: cpu_models permalink: /documentation/general_docs/cpu_models/visualization/ --- + + # Visualization This page contains information about different types of information visualization that is integrated or can be used with gem5. diff --git a/_pages/documentation/general_docs/debugging_and_testing/debugging/debugger_based_debugging.md b/_pages/documentation/general_docs/debugging_and_testing/debugging/debugger_based_debugging.md index 84cb89fe64..77611c1797 100644 --- a/_pages/documentation/general_docs/debugging_and_testing/debugging/debugger_based_debugging.md +++ b/_pages/documentation/general_docs/debugging_and_testing/debugging/debugger_based_debugging.md @@ -7,6 +7,10 @@ permalink: /documentation/general_docs/debugging_and_testing/debugging/debugger_ author: Bobby R. Bruce --- + + # Debugger-based Debugging If traces alone are not sufficient, you'll need to inspect what gem5 is doing @@ -24,13 +28,16 @@ You can create one or more DebugEvents when you invoke gem5 using the debugger prompt using the `schedBreak()` function. The following example session illustrates both of these approaches: + ``` -% gdb m5/build//gem5.debug +% gdb m5/build/ALL/gem5.debug GNU gdb 6.1 Copyright 2002 Free Software Foundation, Inc. [...] (gdb) run --debug-break=2000 configs/run.py -Starting program: /z/stever/bk/m5/build//gem5.debug --debug-break=2000 configs/run.py +Starting program: /z/stever/bk/m5/build/ALL/gem5.debug --debug-break=2000 configs/run.py M5 Simulator System [...] warn: Entering event queue @ 0. Starting simulation... @@ -85,10 +92,9 @@ You can debug configuration scripts with the [Python debug (PDB)]( https://docs.python.org/3/library/pdb.html) just as you would other Python scripts. You can enter PDB before your configuration script is executed by giving the `--pdb` argument to the gem5 binary. Another approach is to put the -following line in your configuration script (e.g., `fs.py` or `se.py`) wherever -you would like to enter the debugger: +following line in your configuration script wherever you would like to enter the debugger: -``` +```python import pdb; pdb.set_trace() ``` @@ -106,19 +112,23 @@ Valgrind is a dynamic analysis tool used (primarily) to profile a target application and detect the source of run-time errors, as well as detect memory leaks. + For Valgrind to function, the target gem5 binary must have been compiled to include debugging information. Therefore, the `gem5.debug` binaries must be used. Due to difficulties with Valgrind working with tcmalloc, `gem5.debug` must be compiled without using the `--without-tcmalloc` flag: -``` -scons --without-tcmalloc build/{ISA}/gem5.debug +```bash +scons --without-tcmalloc build/ALL/gem5.debug ``` To run a check using Valgrind, execute the following: -``` -valgrind --leak-check=yes --suppressions=util/valgrind-suppressions build/{Target ISA}/gem5.debug {gem5 arguments} +```bash +valgrind --leak-check=yes --suppressions=util/valgrind-suppressions build/ALL/gem5.debug {gem5 arguments} ``` The above will run the gem5 and do two things: @@ -137,7 +147,7 @@ If a run-time error is received, Valgrind will return an output which looks like the following (taken from the [Valgrind Quick Start Guide]( http://valgrind.org/docs/manual/quick-start.html)): -``` +```txt ==19182== Invalid write of size 4 ==19182== at 0x804838F: f (example.c:6) ==19182== by 0x80483AB: main (example.c:11) @@ -154,7 +164,7 @@ called by the `main` method at line 11 (also in `example.c`). Valgrind may also return warnings about memory leaks, such as: -``` +```txt ==19182== 40 bytes in 1 blocks are definitely lost in loss record 1 of 1 ==19182== at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130) ==19182== by 0x8048385: f (a.c:5) diff --git a/_pages/documentation/general_docs/debugging_and_testing/debugging/debugging_simulated_code.md b/_pages/documentation/general_docs/debugging_and_testing/debugging/debugging_simulated_code.md index c2327ee38c..3259d85f19 100644 --- a/_pages/documentation/general_docs/debugging_and_testing/debugging/debugging_simulated_code.md +++ b/_pages/documentation/general_docs/debugging_and_testing/debugging/debugging_simulated_code.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/debugging_and_testing/debugging/debugging author: Bobby R. Bruce --- + + # Debugging Simulated Code gem5 has built-in support for gdb's remote debugger interface. If you are @@ -64,7 +66,7 @@ cpus you will need to match the cpu id with the corresponding port number for the remote gdb session. For example, using the following sample output from gem5, calling the kernel debugger for cpu 3 requires the kernel debugger to be listening on port 7001. - + ``` %./build//gem5.debug configs/example/fs.py ... diff --git a/_pages/documentation/general_docs/debugging_and_testing/debugging/trace_baced_debugging.md b/_pages/documentation/general_docs/debugging_and_testing/debugging/trace_baced_debugging.md index e6908ab576..be540ada2a 100644 --- a/_pages/documentation/general_docs/debugging_and_testing/debugging/trace_baced_debugging.md +++ b/_pages/documentation/general_docs/debugging_and_testing/debugging/trace_baced_debugging.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/debugging_and_testing/debugging/trace_bas author: Bobby R. Bruce --- + + # Trace-based Debugging ## Introduction @@ -18,6 +20,8 @@ debug flag (e.g., `Bus`, `Cache`, `Ethernet`, `Disk`, etc.). To turn on the messages for a particular flag, use the `--debug-flags` command line argument. Multiple flags can be specified by giving a list of strings, e.g.: + + ``` build//gem5.opt --debug-flags=Bus,Cache configs/examples/fs.py ``` @@ -77,7 +81,7 @@ ExecSymbol flag (e.g., `--debug-flags=Exec,-ExecSymbol`). If some supposedly innocuous change has caused gem5 to stop working correctly, you can compare trace outputs from before and after the change using the -tracediff script in the `src/util` directory. Comments in the script describe +tracediff script in the `util` directory. Comments in the script describe how to use it. ### Reducing trace file size @@ -405,6 +409,8 @@ an emulator like qemu. That's likely a little slower and compares execution against the emulator and not real hardware, but it can still help identify bugs. + + ### ISA support Currently `SPARC`, `ARM`, and `x86` support state. ARM's support is currently diff --git a/_pages/documentation/general_docs/debugging_and_testing/directed_testers/garnet_synthetic_traffic.md b/_pages/documentation/general_docs/debugging_and_testing/directed_testers/garnet_synthetic_traffic.md index 640784e8ab..80ca49cf75 100644 --- a/_pages/documentation/general_docs/debugging_and_testing/directed_testers/garnet_synthetic_traffic.md +++ b/_pages/documentation/general_docs/debugging_and_testing/directed_testers/garnet_synthetic_traffic.md @@ -7,6 +7,10 @@ permalink: /documentation/general_docs/debugging_and_testing/directed_testers/ga author: Bobby R. Bruce --- + + # Garnet Synthetic Traffic The Garnet Synthetic Traffic provides a framework for simulating the Garnet @@ -41,6 +45,8 @@ scons setconfig build/NULL RUBY_PROTOCOL_GARNET_STANDALONE=y scons build/NULL/gem5.debug ``` + + Example command: ``` diff --git a/_pages/documentation/general_docs/debugging_and_testing/directed_testers/ruby_random_tester.md b/_pages/documentation/general_docs/debugging_and_testing/directed_testers/ruby_random_tester.md index 9bad57b660..042f018afb 100644 --- a/_pages/documentation/general_docs/debugging_and_testing/directed_testers/ruby_random_tester.md +++ b/_pages/documentation/general_docs/debugging_and_testing/directed_testers/ruby_random_tester.md @@ -7,6 +7,9 @@ permalink: /documentation/general_docs/debugging_and_testing/directed_testers/ru author: Bobby R. Bruce --- + + # Ruby Random Tester A cache coherence protocol usually has several different types of state @@ -20,10 +23,12 @@ tester are present in the directory `src/cpu/testers/rubytest`. The file of the test. For example, the following command can be used for testing a protocol: -``` -./build/X86/gem5.fast ./configs/example/ruby_random_test.py +```bash +./build/NULL/gem5.fast ./configs/example/ruby_random_test.py ``` +Note: As of gem5 v24.1, the above command will not work if the ALL build is used. + Though one can specify many different options to the random tester, some of them are note worthy. @@ -35,7 +40,6 @@ them are note worthy. |`-l`, `--checks` |Number of loads to be performed. | |`--random_seed` |Seed for initialization of the random number generator. | - Testing a coherence protocol with the random tester is a tedious task and requires patience. First, build gem5 with the protocol to be tested. Then, run the ruby random tester as mentioned above. Initially one should run the tester diff --git a/_pages/documentation/general_docs/debugging_and_testing/index.md b/_pages/documentation/general_docs/debugging_and_testing/index.md index 6ec93868f1..4950080524 100644 --- a/_pages/documentation/general_docs/debugging_and_testing/index.md +++ b/_pages/documentation/general_docs/debugging_and_testing/index.md @@ -7,4 +7,11 @@ permalink: /documentation/general_docs/debugging_and_testing/ author: Bobby R. Bruce --- -TODO +## gem5 bootcamp 2024 module on debugging and testing + +The 2024 gem5 bootcamp had sessions on debugging and testing in gem5. + +The slides for debugging in gem5 can be found on the 2024 bootcamp website, +[03-Developing-gem5-models/02-debugging-gem5](https://bootcamp.gem5.org/#03-Developing-gem5-models/02-debugging-gem5). + +The slides for testing in gem5 can be found in [06-Contributing/02-testing](https://bootcamp.gem5.org/#06-Contributing/02-testing). diff --git a/_pages/documentation/general_docs/developement/coding_style.md b/_pages/documentation/general_docs/developement/coding_style.md index 0e591f80d7..5a108a601c 100644 --- a/_pages/documentation/general_docs/developement/coding_style.md +++ b/_pages/documentation/general_docs/developement/coding_style.md @@ -7,7 +7,13 @@ permalink: /documentation/general_docs/development/coding_style/ --- # C/C++ Coding Style -We strive to maintain a consistent coding style in the gem5 C/C++ source code to make the source more readable and maintainable. This necessarily involves compromise among the multiple developers who work on this code. We feel that we have been successful in finding such a compromise, as each of the primary M5 developers is annoyed by at least one of the rules below. We ask that you abide by these guidelines as well if you develop code that you would like to contribute back to M5. An Emacs c++-mode style embodying the indentation rules is available in the source tree at util/emacs/m5-c-style.el. + +We strive to maintain a consistent coding style in the gem5 C/C++ source code to make the source more readable and maintainable. + + +We ask that you abide by these guidelines as well if you develop code that you would like to contribute back to M5. + ## Indentation and Line Breaks @@ -19,6 +25,19 @@ Indentation should use spaces only (no tabs), as tab widths are not always set c Lines must be a maximum of 79 characters long. +For functions with long names and/or numerous arguments that must be split over +multiple lines, it is preferred to indent later lines so they line up with the +first argument in the first line. However, if the file you are working in +uses a different format, please follow the file's existing format. + +```c++ +if (a > 0) { + obnoxiously_named_function_with_lots_of_args(verbose_arg1, + verbose_arg2, + verbose_arg3); +} +``` + ## Braces For control blocks (if, while, etc.), opening braces must be on the same line as the control keyword with a space between the closing parenthesis and the opening brace. @@ -50,7 +69,10 @@ if (...) { ... } ``` + + For function definitions or class declarations, the opening brace must be in the first column of the following line. @@ -107,7 +129,6 @@ There should be: * no space between function names and opening parentheses for arguments * no space immediately inside parentheses, except for very complex expressions. Complex expressions are preferentially broken into multiple simpler expressions using temporary variables. - For pointer and reference argument declarations, either of the following are acceptable: ```c++ @@ -121,6 +142,7 @@ or FooType* fooPtr; FooType& fooRef; ``` + However, style should be kept consistent within a file. If you are editing an existing file, please keep consistent with the existing code. If you are writing new code in a new file, feel free to choose the style of your preference. ## Naming @@ -229,6 +251,7 @@ If you need to have a period in the brief description, follow it with a backslas * e.g.\ This is a brief description with an internal period. */ ``` + Blank lines within these comments are interpreted as paragraph breaks to help you make the documentation more readble. ### Special commands @@ -380,6 +403,7 @@ It remains to be seen what groups we can come up with. Not sure what other doxygen features we want to use. ## M5 Status Messages + ### Fatal v. Panic There are two error functions defined in `src/base/logging.hh:` `panic()` and `fatal()`. While these two functions have roughly similar effects (printing an error message and terminating the simulation process), they have distinct purposes and use cases. The distinction is documented in the comments in the header file, but is repeated here for convenience because people often get confused and use the wrong one. diff --git a/_pages/documentation/general_docs/developement/release_procedures.md b/_pages/documentation/general_docs/developement/release_procedures.md index e9dc00ea71..c53f022bce 100644 --- a/_pages/documentation/general_docs/developement/release_procedures.md +++ b/_pages/documentation/general_docs/developement/release_procedures.md @@ -18,7 +18,7 @@ At least two weeks prior to a release a staging branch is created from the devel This staging branch is rigorously tested and only bug fixes or inconsequential changes (format fixes, typo fixes, etc.) are permitted to be be submitted to this branch. The staging branch is updated with the following changes: - + * The `-werror` is removed. This ensures that gem5 compiles on newer compilers as new/stricter compiler warnings are incorporated. For example: . @@ -28,9 +28,9 @@ For example: . For example: . * The [`ext/testlib/configuration.py`](https://github.com/gem5/gem5/blob/stable/ext/testlib/configuration.py) file's `default.resource_url` field is updated to point towards the correct Google Cloud release bucket (see [the Cloud Bucket release procedures](#gem5-resources-google-cloud-bucket)). For example: . -* The Resource downloader, `src/python/gem5/resources/downloader.py`, has a function `def _resources_json_version_required()`. This must be updated to the correct version of the `resources.json` file to use (see the [gem5 resources repository release procedures](#gem5-resources-repository)) for more information on this). +* The Resource downloader, `src/python/gem5/resources/downloader.py`, has a function `def _resources_json_version_required()`. This must be updated to the correct version of the `resources.json` file to use (see the [gem5 resources repository release procedures](#gem5-resources-repository) for more information on this). * The `tests/weekly.sh`, `tests/nightly.sh`, `tests/compiler-tests.sh`, and `tests/jenkins/presubmit.sh` should be updated ensure they remain stable across different gem5 releases. This is achieved by: - 1. Fix the docker pulls images by appending the version (example [here](https://gem5-review.googlesource.com/c/public/gem5/+/54470). This will be done after following the [docker image release procedures](#the-docker-images). + 1. Fix the docker pulls images by appending the version (example [here](https://gem5-review.googlesource.com/c/public/gem5/+/54470)). This will be done after following the [docker image release procedures](#the-docker-images). 2. Ensure the download links are downloading from the correct Google Cloud bucket for the release version. * Hardcode the `rocm_patches/ROCclr.patch` download link in `util/dockerfiles/gcn-gpu` to the correct Google bucket. * Update the `ext/sst/README.md` file for the current version. This simply means updating the download links. @@ -49,6 +49,8 @@ It has been customary to create a blog post on outlining t While appreciated, it is not mandatory. **Important notes:** + + * You must a member of the "Project Owners" or "google/gem5-admins@googlegroups.com" Gerrit permission groups to push to the stable branch. Please contact Bobby R. Bruce (bbruce@ucdavis.edu) for help pushing to the gem5 stable branch. @@ -63,7 +65,7 @@ Unlike the gem5 repo, changes to the gem5 resources repo may be submitted to the As with the gem5 repository, a staging branch is created at least two weeks prior to a release. The purpose of this staging branch is identical to that of the main gem5 repository, and it is merged into both the stable and develop branches upon a gem5 release. Prior to this the following changes should be applied to the staging branch: - + * A new Google Cloud Bucket directory should be created for that version (see the [the Cloud Bucket release procedures](#gem5-resources-google-cloud-bucket)), and all the resources from the staging branch must match that found within that Google Cloud Bucket directory (i.e., the compiled resources within the bucket are built from the sources in the staging branch). * URL download links in the resources repo should be updated to point towards the correct Google Cloud Bucket directory. * The `resources.json` file, found in the root of the repository, must be updated for the current release. @@ -73,6 +75,7 @@ The `previous-version` list must be updated to support all versions prior, inclu Each previous version must map to a file that may be downloaded. * The `resources.json` `url_base` field must be updated to the correct directory from the Google Cloud Bucket. + When merged into the develop branch, the URL download links should reverted back to `http://dist.gem5.org/dist/develop`. Immediately prior to merging, the stable branch is tagged with the previous release version ID. @@ -80,6 +83,7 @@ For example, if the staging branch is for `v22.2,` and the content on the stable This is because we want users to be able to revert the gem5 resources to get sources compatible with previous gem5 releases. Therefore, if a user wished to get the resources sources compatible with the the v20.1 release, they'd checkout the revision tagged as `v20.1` on the stable branch. + ### gem5 resources Google Cloud Bucket The built gem5 resources are found within the gem5 Google Cloud Bucket. @@ -111,11 +115,11 @@ Please contact Bobby R. Bruce (bbruce@ucdavis.edu) for help pushing resources to Currently hosted in [`util/dockerfiles`](https://github.com/gem5/gem5/tree/stable/util/dockerfiles/) in the gem5 repository, we have a series of Dockerfiles which can be built to produce environments in which gem5 can be built and run. These images are mostly used for testing purposes. -The [`ubuntu-20.04_all-dependencies`](https://github.com/gem5/gem5/tree/stable/util/dockerfiles/ubuntu-20.04_all-dependencies/) Dockerfile is the one most suitable for users who wish to build and execute gem5 in a supported environment. +The [`ubuntu-24.04_all-dependencies`](https://github.com/gem5/gem5/tree/stable/util/dockerfiles/ubuntu-24.04_all-dependencies/) Dockerfile is the one most suitable for users who wish to build and execute gem5 in a supported environment. We provide pre-built Docker images hosted at under "gem5". All the Dockerfiles found in `util/dockerfiles` have been built and stored there. -For instance, `ubuntu-20.04_all-dependencies` can be found at (and can thereby be obtained with `docker pull ghcr.io/gem5/ubuntu-20.04_all-dependencies`). +For instance, `ubuntu-24.04_all-dependencies` can be found at (and can thereby be obtained with `docker pull ghcr.io/gem5/ubuntu-24.04_all-dependencies`). The Docker images are continually built from the Dockerfiles found on the develop branch. Therefore the docker image with the `latest` tag is that in-sync with the Dockerfiles found on the gem5 repo's develop branch. @@ -125,9 +129,11 @@ The purpose of this is so users of an older versions of gem5, may obtain images I.e., a user of gem5 `v21.0` may obtain the `v21.0` version of the `ubuntu-20.04_all-dependencies` with `docker pull ghcr.io/gem5/ubuntu-20.04_all-dependencies:v21-0`. **Important notes:** + * If changes to the Dockerfile are done on the staging branch, then these changes will need to be pushed to manually. * Special permissions are needed to push to the . Please contact Bobby R. Bruce (bbruce@ucdavis.edu) for help pushing images. + * It is a future goal of ours to move [the Dockerfiles from `util/dockerfiles` to gem5-resources](https://gem5.atlassian.net/browse/GEM5-1044). ## gem5 website repository @@ -141,7 +147,9 @@ E.g., it contains the changes needed to apply to the website when the new versio As the stable branch may be updated at any time (as long as those updates relate to the current release), stable is merged periodically into develop. As with the gem5 resources, and the main gem5 repository, a staging branch is created from the develop branch at least two weeks prior to a gem5 release. -The staging branch needs updated so that the documentation is up-to-date with the upcoming release. +The staging branch needs to be updated so that the documentation is up-to-date with the upcoming release. + + Of particular note, references to gem5 resources, hosted on the Google Cloud bucket should be updated. For example, links to, say , would need to be updated to when transitioning from `v21-0` to `v21-1`. @@ -162,7 +170,7 @@ doxygen ``` The html will be output to `src/doxygen/html`. - + The gem5 Doxygen website is hosted as a static webpage in a Google Cloud Bucket. The directory structure is as follows: @@ -204,10 +212,11 @@ gsutil -m cp -r gs://doxygen.gem5.org/release/current gs://doxygen.gem5.org/rele The final step is to add a link to this gem5 Doxygen version on the website, via the [`_data/documentation.yml` file](https://github.com/gem5/website/blob/stable/_data/documentation.yml). For example: . - **Important Notes:** -* The gem5 develop branch Doxygen website is updated daily via an automated build process. + +* The gem5 develop branch Doxygen website is updated daily via an automated build process. The footer on the Doxygen website will state when the page was generated. + * Special permissions are needed to push to the Google Cloud Bucket. Please contact Bobby R. Bruce (bbruce@ucdavis.edu) for help pushing to the Google Cloud Bucket. diff --git a/_pages/documentation/general_docs/fullsystem/building_android_m.md b/_pages/documentation/general_docs/fullsystem/building_android_m.md index 424ce4b14b..e7a9c45155 100644 --- a/_pages/documentation/general_docs/fullsystem/building_android_m.md +++ b/_pages/documentation/general_docs/fullsystem/building_android_m.md @@ -6,6 +6,8 @@ parent: fullsystem permalink: /documentation/general_docs/fullsystem/building_android_m --- + + # Building Android Marshmallow This guide gives detailed step-by-step instructions on building an Android Marshmallow image along with a working kernel and .dtb file that work with gem5. diff --git a/_pages/documentation/general_docs/fullsystem/building_arm_kernel.md b/_pages/documentation/general_docs/fullsystem/building_arm_kernel.md index 47d85bfe29..ff4a14ec2a 100644 --- a/_pages/documentation/general_docs/fullsystem/building_arm_kernel.md +++ b/_pages/documentation/general_docs/fullsystem/building_arm_kernel.md @@ -6,6 +6,8 @@ parent: fullsystem permalink: /documentation/general_docs/fullsystem/building_arm_kernel --- + + # Building ARM Kernel This page contains instructions for building up-to-date kernels for gem5 running on ARM. diff --git a/_pages/documentation/general_docs/fullsystem/devices.md b/_pages/documentation/general_docs/fullsystem/devices.md index 3183bfc54e..c0379f7050 100644 --- a/_pages/documentation/general_docs/fullsystem/devices.md +++ b/_pages/documentation/general_docs/fullsystem/devices.md @@ -6,6 +6,8 @@ doc: gem5 documentation permalink: documentation/general_docs/fullsystem/devices --- + + # Devices in full system mode ## I/O Device Base Classes diff --git a/_pages/documentation/general_docs/fullsystem/disks.md b/_pages/documentation/general_docs/fullsystem/disks.md index 49572c78df..d0bf04564d 100644 --- a/_pages/documentation/general_docs/fullsystem/disks.md +++ b/_pages/documentation/general_docs/fullsystem/disks.md @@ -6,6 +6,8 @@ parent: fullsystem permalink: documentation/general_docs/fullsystem/disks --- + + # Creating disk images for full system mode In full-system mode, gem5 relies on a disk image with an installed operating system to run simulations. diff --git a/_pages/documentation/general_docs/fullsystem/guest_binaries.md b/_pages/documentation/general_docs/fullsystem/guest_binaries.md index 540fbbee69..ce6d9df0e1 100644 --- a/_pages/documentation/general_docs/fullsystem/guest_binaries.md +++ b/_pages/documentation/general_docs/fullsystem/guest_binaries.md @@ -7,6 +7,8 @@ author: Giacomo Travaglini * TOC {:toc} + + We provide a set of useful prebuilt binaries users can download (in case they don't want to recompile them from scratch). diff --git a/_pages/documentation/general_docs/fullsystem/m5term.md b/_pages/documentation/general_docs/fullsystem/m5term.md index 9d1e9e1552..5550f422dd 100644 --- a/_pages/documentation/general_docs/fullsystem/m5term.md +++ b/_pages/documentation/general_docs/fullsystem/m5term.md @@ -5,6 +5,9 @@ doc: gem5 documentation parent: fullsystem permalink: /documentation/general_docs/fullsystem/m5term --- + + + # m5 term The m5term program allows the user to connect to the simulated console interface that full-system gem5 provides. Simply change into the util/term directory and build m5term: ``` diff --git a/_pages/documentation/general_docs/gem5_resources.md b/_pages/documentation/general_docs/gem5_resources.md index 0a16e4cc65..2d91915dd4 100644 --- a/_pages/documentation/general_docs/gem5_resources.md +++ b/_pages/documentation/general_docs/gem5_resources.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/gem5_resources/ authors: Bobby R. Bruce, Kunal Pai, Parth Shah --- + + # gem5 Resources gem5 Resources is a repository providing sources for artifacts known and @@ -32,6 +34,7 @@ release of gem5. To find a specific resource with the gem5 Resources, we recommend using the [gem5 Resources Website](https://resources.gem5.org). Detailed information on how searching, filtering and sorting works on this website is on this [help page](https://resources.gem5.org/help). + The gem5 Resources are hosted on our Google Cloud Bucket. Links to the resources can be found [gem5 resources README.md file]( https://gem5.googlesource.com/public/gem5-resources/+/refs/heads/stable/README.md). @@ -62,8 +65,10 @@ The `obtain_resource` function accepts the following parameters: When you find the Workload that you want to use in your simulation, navigate to the 'Usage' tab of that Workload. + For the purpose of this tutorial, let's assume that the Workload you are looking for is `riscv-ubuntu-20.04-boot`, found [here](https://resources.gem5.org/resources/riscv-ubuntu-20.04-boot). In the ['Usage'](https://resources.gem5.org/resources/riscv-ubuntu-20.04-boot/usage) tab of this Workload, you will find the code that can be pasted in a gem5 simulation to use this Workload. + In this case, the code is `Workload("riscv-ubuntu-20.04-boot")`. To use the `Workload` class, you require the following import statement: @@ -81,6 +86,7 @@ The `Workload` class accepts the following parameters: ## Using a Custom Resource in gem5 + To use a Custom Resource in gem5, we recommend using one of the supported data sources formats in gem5. Currently, we support MongoDB Atlas, local JSON files and remote JSON files. You can use your own config file by overriding the `GEM5_DEFAULT_CONFIG` variable while running a file. @@ -103,6 +109,7 @@ The HEAD of the `stable` branch will point towards a set of resource sources compatible with the latest release of gem5 (which can be obtained via `git clone https://github.com/gem5/gem5.git`). + Please consult the [README.md]( https://gem5.googlesource.com/public/gem5-resources/+/refs/heads/stable/README.md) file for information on compiling individual gem5 resources. Where license @@ -215,6 +222,7 @@ We strongly advise contributors follow our [Style Guide]( /documentation/general_docs/development/coding_style/) where possible and appropriate. + Any change will then be reviewed via our [Gerrit code review system]( https://gem5-review.googlesource.com). Once fully accepted and merged into the gem5 resources repository, please contact Bobby R. Bruce diff --git a/_pages/documentation/general_docs/gpu_models/gpufs.md b/_pages/documentation/general_docs/gpu_models/gpufs.md index 85e0176712..0bf1808350 100644 --- a/_pages/documentation/general_docs/gpu_models/gpufs.md +++ b/_pages/documentation/general_docs/gpu_models/gpufs.md @@ -6,6 +6,8 @@ parent: gpu_models permalink: /documentation/general_docs/gpu_models/gpufs --- + + # **Full System AMD GPU model** The Full System AMD GPU model simulates a GPU at the "gfx9" ISA level, as opposed to the intermediate language level. This page will give you a general overview of how to use this model, the software stack the model uses, and provide resources that detail the model and how it is implemented. **It is recommended to use Full System instead of System Emulation as Full System supports the latest versions of the GPU software stack.** diff --git a/_pages/documentation/general_docs/gpu_models/vega.md b/_pages/documentation/general_docs/gpu_models/vega.md index faf2c9e774..6b0207b258 100644 --- a/_pages/documentation/general_docs/gpu_models/vega.md +++ b/_pages/documentation/general_docs/gpu_models/vega.md @@ -6,6 +6,10 @@ parent: gpu_models permalink: /documentation/general_docs/gpu_models/vega --- + + # **System Emulation AMD VEGA GPU model** Table of Contents diff --git a/_pages/documentation/general_docs/kconfig_build_system.md b/_pages/documentation/general_docs/kconfig_build_system.md index d1773759a1..3467e8caf0 100644 --- a/_pages/documentation/general_docs/kconfig_build_system.md +++ b/_pages/documentation/general_docs/kconfig_build_system.md @@ -6,8 +6,10 @@ parent: kconfig_build_system permalink: /documentation/general_docs/kconfig_build_system/ --- -This guide is intended for advanced users who need to build gem5 (>=23.1) with -multiple ISAs or customize the build options, such as the Ruby memory protocol. + + +This guide is intended for advanced users who need to customize the build +options, such as the Ruby memory protocol. Familiarity with the Kconfig system is required. ## Build gem5 with the Kconfig Build System diff --git a/_pages/documentation/general_docs/kvm_setup.md b/_pages/documentation/general_docs/kvm_setup.md index 748ed54987..b9d3bc0031 100644 --- a/_pages/documentation/general_docs/kvm_setup.md +++ b/_pages/documentation/general_docs/kvm_setup.md @@ -5,6 +5,8 @@ permalink: /documentation/general_docs/using_kvm/ author: Mahyar Samani and Bobby R. Bruce --- + + Kernel-based Virtual Machine (KVM) is a Linux kernel module allowing creating a virtual machine managed by the kernel. On recent x86 and ARM processors, KVM supports hardware-assisted virtualization, enabling running the virtual machine at close to native speed. gem5's `KVMCPU` enables this feature in gem5, with the trade-offs being architectual statistics are not being recorded by gem5. @@ -62,12 +64,19 @@ Now if you run the `groups` command below you should see `kvm` and `libvirt`. ## Proving KVM is working -The "configs/example/gem5_library/x86-ubuntu-run.py" file is a gem5 configuration that will create a simulation which boots a Ubuntu 18.04 image using KVM. +The "configs/example/gem5_library/x86-ubuntu-run-with-kvm.py" file is a gem5 configuration that will create a simulation which boots a Ubuntu 24.04 image using KVM. It can be executed with the following: ```console -scons build/X86/gem5.opt -j`nproc` -./build/X86/gem5.opt configs/example/gem5_library/x86-ubuntu-run-with-kvm.py +scons build/ALL/gem5.opt -j`nproc` +./build/ALL/gem5.opt configs/example/gem5_library/x86-ubuntu-run-with-kvm.py +``` + +If you are using a pre-built gem5 binary, use the following command: + +```console +gem5 configs/example/gem5_library/x86-ubuntu-run-with-kvm.py + ``` If the simulation runs successfully, you have successfully installed KVM and can use it with gem5. diff --git a/_pages/documentation/general_docs/m5ops.md b/_pages/documentation/general_docs/m5ops.md index ed831343c5..615f1c4cd1 100644 --- a/_pages/documentation/general_docs/m5ops.md +++ b/_pages/documentation/general_docs/m5ops.md @@ -5,6 +5,7 @@ doc: gem5 documentation parent: m5ops permalink: /documentation/general_docs/m5ops/ --- + # M5ops diff --git a/_pages/documentation/general_docs/memory_system/classic-coherence-protocol.md b/_pages/documentation/general_docs/memory_system/classic-coherence-protocol.md index f83b59bb7b..84b29db61a 100644 --- a/_pages/documentation/general_docs/memory_system/classic-coherence-protocol.md +++ b/_pages/documentation/general_docs/memory_system/classic-coherence-protocol.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/memory_system/classic-coherence-protocol/ author: Jason Lowe-Power --- + + # Classic Memory System coherence M5 2.0b4 introduced a substantially rewritten and streamlined cache diff --git a/_pages/documentation/general_docs/memory_system/classic_caches.md b/_pages/documentation/general_docs/memory_system/classic_caches.md index 7e76fd2b08..88338c70c1 100644 --- a/_pages/documentation/general_docs/memory_system/classic_caches.md +++ b/_pages/documentation/general_docs/memory_system/classic_caches.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/memory_system/classic_caches/ author: Jason Lowe-Power --- + + # Classic Caches The default cache is a non-blocking cache with MSHR (miss status holding diff --git a/_pages/documentation/general_docs/memory_system/gem5_memory_system.md b/_pages/documentation/general_docs/memory_system/gem5_memory_system.md index d9c392751e..948815be79 100644 --- a/_pages/documentation/general_docs/memory_system/gem5_memory_system.md +++ b/_pages/documentation/general_docs/memory_system/gem5_memory_system.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/memory_system/gem5_memory_system/ author: Djordje Kovacevi --- + + # The gem5 Memory System The document describes memory subsystem in gem5 with focus on program flow @@ -18,6 +20,8 @@ Model that is used in this document consists of two out-of-order (O3) ARM v7 CPUs with corresponding L1 data caches and Simple Memory. It is created by running gem5 with the following parameters: + + ``` configs/example/fs.py –-caches –-cpu-type=arm_detailed –-num-cpus=2 ``` diff --git a/_pages/documentation/general_docs/memory_system/index.md b/_pages/documentation/general_docs/memory_system/index.md index 89b109a2c8..aef171e2ef 100644 --- a/_pages/documentation/general_docs/memory_system/index.md +++ b/_pages/documentation/general_docs/memory_system/index.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/memory_system/ author: Jason Lowe-Power --- + + # Memory system M5's new memory system (introduced in the first 2.0 beta release) was diff --git a/_pages/documentation/general_docs/memory_system/indexing_policies.md b/_pages/documentation/general_docs/memory_system/indexing_policies.md index 3425ce41c2..a1a3f2923c 100644 --- a/_pages/documentation/general_docs/memory_system/indexing_policies.md +++ b/_pages/documentation/general_docs/memory_system/indexing_policies.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/memory_system/indexing_policies/ author: Jason Lowe-Power --- + + # Indexing Policies Indexing policies determine the locations to which a block is mapped diff --git a/_pages/documentation/general_docs/memory_system/replacement_policies.md b/_pages/documentation/general_docs/memory_system/replacement_policies.md index 8b51221757..83ed0d65c1 100644 --- a/_pages/documentation/general_docs/memory_system/replacement_policies.md +++ b/_pages/documentation/general_docs/memory_system/replacement_policies.md @@ -7,6 +7,10 @@ permalink: /documentation/general_docs/memory_system/replacement_policies/ author: Jason Lowe-Power --- + + # Replacement Policies Gem5 has multiple implemented replacement policies. Each one uses its diff --git a/_pages/documentation/general_docs/moving_to_github.md b/_pages/documentation/general_docs/moving_to_github.md index b4da77fed5..8c6137ab33 100644 --- a/_pages/documentation/general_docs/moving_to_github.md +++ b/_pages/documentation/general_docs/moving_to_github.md @@ -6,6 +6,8 @@ parent: moving_to_github permalink: /documentation/general_docs/moving_to_github/ --- + + # Moving Active Changes from Gerrit to GitHub As we transition to using GitHub to host the gem5 project, we need to have a way to move any active changes from Gerrit onto GitHub for review. If your change won’t be ready to be merged by the time Gerrit becomes read-only, follow the steps below to create a pull request with your changes for review on GitHub. diff --git a/_pages/documentation/general_docs/ruby/CHI.md b/_pages/documentation/general_docs/ruby/CHI.md index a36723d680..e313d29e49 100644 --- a/_pages/documentation/general_docs/ruby/CHI.md +++ b/_pages/documentation/general_docs/ruby/CHI.md @@ -7,6 +7,10 @@ permalink: /documentation/general_docs/ruby/CHI/ author: Tiago Mück --- + + # CHI The CHI ruby protocol provides a single cache controller that can be reused at multiple levels of the cache hierarchy and configured to model multiple instances of MESI and MOESI cache coherency protocols. This implementation is based of [Arm's AMBA 5 CHI specification](https://developer.arm.com/documentation/ihi0050/D/) and provides a scalable framework for the design space exploration of large SoC designs. diff --git a/_pages/documentation/general_docs/ruby/Garnet_standalone.md b/_pages/documentation/general_docs/ruby/Garnet_standalone.md index 2c17839202..278b29f18a 100644 --- a/_pages/documentation/general_docs/ruby/Garnet_standalone.md +++ b/_pages/documentation/general_docs/ruby/Garnet_standalone.md @@ -7,6 +7,10 @@ permalink: /documentation/general_docs/ruby/Garnet_standalone/ author: Jason Lowe-Power --- + + # Garnet Standalone This is a dummy cache coherence protocol that is used to operate Garnet diff --git a/_pages/documentation/general_docs/ruby/MESI_Two_Level.md b/_pages/documentation/general_docs/ruby/MESI_Two_Level.md index 6ee49a6900..75cddcb82f 100644 --- a/_pages/documentation/general_docs/ruby/MESI_Two_Level.md +++ b/_pages/documentation/general_docs/ruby/MESI_Two_Level.md @@ -7,6 +7,9 @@ permalink: /documentation/general_docs/ruby/MESI_Two_Level/ author: Jason Lowe-Power --- + + # MESI Two Level ### **Protocol Overview** diff --git a/_pages/documentation/general_docs/ruby/MI_example.md b/_pages/documentation/general_docs/ruby/MI_example.md index cc51f3a97f..d5e5e9d064 100644 --- a/_pages/documentation/general_docs/ruby/MI_example.md +++ b/_pages/documentation/general_docs/ruby/MI_example.md @@ -6,6 +6,11 @@ parent: ruby permalink: /documentation/general_docs/ruby/MI_example/ author: Jason Lowe-Power --- + + + # MI Example @@ -25,7 +30,7 @@ author: Jason Lowe-Power ### Related Files - - **src/mem/protocols** + - **src/mem/ruby/protocol** - **MI_example-cache.sm**: cache controller specification - **MI_example-dir.sm**: directory controller specification - **MI_example-dma.sm**: dma controller specification diff --git a/_pages/documentation/general_docs/ruby/MOESI_CMP_directory.md b/_pages/documentation/general_docs/ruby/MOESI_CMP_directory.md index 804e8c14d4..1b5ca3f195 100644 --- a/_pages/documentation/general_docs/ruby/MOESI_CMP_directory.md +++ b/_pages/documentation/general_docs/ruby/MOESI_CMP_directory.md @@ -7,6 +7,9 @@ permalink: /documentation/general_docs/ruby/MOESI_CMP_directory/ author: Jason Lowe-Power --- + + # MOESI CMP Directory ### Protocol Overview @@ -22,7 +25,7 @@ author: Jason Lowe-Power ### Related Files - - **src/mem/protocols** + - **src/mem/ruby/protocol** - **MOESI_CMP_directory-L1cache.sm**: L1 cache controller specification - **MOESI_CMP_directory-L2cache.sm**: L2 cache controller diff --git a/_pages/documentation/general_docs/ruby/MOESI_CMP_token.md b/_pages/documentation/general_docs/ruby/MOESI_CMP_token.md index 2caca17f97..248e875619 100644 --- a/_pages/documentation/general_docs/ruby/MOESI_CMP_token.md +++ b/_pages/documentation/general_docs/ruby/MOESI_CMP_token.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/ruby/MOESI_CMP_token/ author: Jason Lowe-Power --- + + # MOESI CMP token ### Protocol Overview @@ -23,7 +25,7 @@ author: Jason Lowe-Power ### Related Files - - **src/mem/protocols** + - **src/mem/ruby/protocol** - **MOESI_CMP_token-L1cache.sm**: L1 cache controller specification - **MOESI_CMP_token-L2cache.sm**: L2 cache controller diff --git a/_pages/documentation/general_docs/ruby/MOESI_hammer.md b/_pages/documentation/general_docs/ruby/MOESI_hammer.md index 469b8a889e..8cbbcb2ca0 100644 --- a/_pages/documentation/general_docs/ruby/MOESI_hammer.md +++ b/_pages/documentation/general_docs/ruby/MOESI_hammer.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/ruby/MOESI_hammer/ author: Jason Lowe-Power --- + + # MOESI Hammer This is an implementation of AMD's Hammer protocol, which is used in @@ -17,7 +19,7 @@ directory mode. ### Related Files - - **src/mem/protocols** + - **src/mem/ruby/protocol** - **MOESI_hammer-cache.sm**: cache controller specification - **MOESI_hammer-dir.sm**: directory controller specification - **MOESI_hammer-dma.sm**: dma controller specification diff --git a/_pages/documentation/general_docs/ruby/cache-coherence-protocols.md b/_pages/documentation/general_docs/ruby/cache-coherence-protocols.md index 2ebf842fea..18f12b84da 100644 --- a/_pages/documentation/general_docs/ruby/cache-coherence-protocols.md +++ b/_pages/documentation/general_docs/ruby/cache-coherence-protocols.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/ruby/cache-coherence-protocols/ author: Jason Lowe-Power --- + + # Cache Coherence Protocols ## Common Notations and Data Structures diff --git a/_pages/documentation/general_docs/ruby/garnet-2.md b/_pages/documentation/general_docs/ruby/garnet-2.md index cdaf77d96d..e3a4618d79 100644 --- a/_pages/documentation/general_docs/ruby/garnet-2.md +++ b/_pages/documentation/general_docs/ruby/garnet-2.md @@ -11,6 +11,10 @@ author: Jason Lowe-Power [here](/documentation/general_docs/ruby/interconnection-network/).** ### Garnet2.0: An On-Chip Network Model for Heterogeneous SoCs + + Garnet2.0 is a detailed interconnection network model inside gem5. It is in active development, and patches with more features will be diff --git a/_pages/documentation/general_docs/ruby/garnet_synthetic_traffic.md b/_pages/documentation/general_docs/ruby/garnet_synthetic_traffic.md index ab8ddc6f2b..9711b55286 100644 --- a/_pages/documentation/general_docs/ruby/garnet_synthetic_traffic.md +++ b/_pages/documentation/general_docs/ruby/garnet_synthetic_traffic.md @@ -7,6 +7,10 @@ permalink: /documentation/general_docs/ruby/garnet_synthetic_traffic/ author: Jason Lowe-Power --- + + # Garnet Synthetic Traffic The Garnet Synthetic Traffic provides a framework for simulating the [Garnet network](/documentation/general_docs/ruby/garnet-2) with controlled inputs. This is useful for network testing/debugging, or for network-only simulations with synthetic traffic. @@ -25,6 +29,8 @@ The Garnet Synthetic Traffic provides a framework for simulating the [Garnet net First build gem5 with the [Garnet_standalone](/documentation/general_docs/ruby/Garnet_standalone.md) coherence protocol. The Garnet_standalone protocol is ISA-agnostic, and hence we build it with the NULL ISA. + + For gem5 <= 23.0: ``` diff --git a/_pages/documentation/general_docs/ruby/heterogarnet.md b/_pages/documentation/general_docs/ruby/heterogarnet.md index f32e4d8195..f0f5e0ddc2 100644 --- a/_pages/documentation/general_docs/ruby/heterogarnet.md +++ b/_pages/documentation/general_docs/ruby/heterogarnet.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/ruby/heterogarnet/ author: Srikant Bharadwaj --- + + **More details of the gem5 Ruby Interconnection Network are [here](/documentation/general_docs/ruby/interconnection-network "wikilink").** **Details about the earlier Garnet version can be found [here](/documentation/general_docs/ruby/garnet-2 "wikilink").** diff --git a/_pages/documentation/general_docs/ruby/index.md b/_pages/documentation/general_docs/ruby/index.md index 2c28283a2e..13a77d6562 100644 --- a/_pages/documentation/general_docs/ruby/index.md +++ b/_pages/documentation/general_docs/ruby/index.md @@ -7,6 +7,10 @@ permalink: /documentation/general_docs/ruby/ author: Jason Lowe-Power --- + + # Ruby Ruby implements a detailed simulation model for the memory subsystem. It @@ -201,6 +205,8 @@ refer to previous sections describing each component in isolation. ## Directory Structure + + - **src/mem/** - **protocols**: SLICC specification for coherence protocols - **slicc**: implementation for SLICC parser and code generator diff --git a/_pages/documentation/general_docs/ruby/interconnection-network.md b/_pages/documentation/general_docs/ruby/interconnection-network.md index dfeae630d8..0bd79ae041 100644 --- a/_pages/documentation/general_docs/ruby/interconnection-network.md +++ b/_pages/documentation/general_docs/ruby/interconnection-network.md @@ -7,6 +7,8 @@ permalink: /documentation/general_docs/ruby/interconnection-network/ author: Jason Lowe-Power --- + + # Interconnection Network The various components of the interconnection network model inside diff --git a/_pages/documentation/general_docs/ruby/slicc.md b/_pages/documentation/general_docs/ruby/slicc.md index 0a1606d780..1043bf9422 100644 --- a/_pages/documentation/general_docs/ruby/slicc.md +++ b/_pages/documentation/general_docs/ruby/slicc.md @@ -7,6 +7,11 @@ permalink: /documentation/general_docs/ruby/slicc/ author: Jason Lowe-Power --- + + + # SLICC SLICC is a domain specific language for specifying cache coherence diff --git a/_pages/documentation/general_docs/statistics/statistics.md b/_pages/documentation/general_docs/statistics/statistics.md index 3776b992ed..8f28124f25 100644 --- a/_pages/documentation/general_docs/statistics/statistics.md +++ b/_pages/documentation/general_docs/statistics/statistics.md @@ -6,6 +6,8 @@ doc: gem5 documentation permalink: /documentation/general_docs/statistics/ --- + + # Stats Package The philosophy of the stats package at the moment is to have a single base class called Stat which is merely a hook into every other aspect of the stat that may be important. Thus, this Stat base class has virtual functions to name, set precision for, set flags for, and initialize size for all the stats. For all Vector based stats, it is very important to do the initialization before using the stat so that appropriate storage allocation can occur. For all other stats, naming and flag setting is also important, but not as important for the actual proper execution of the binary. The way this is set up in the code is to have a regStats() pass in which all stats can be registered in the stats database and initialized. diff --git a/_pages/documentation/general_docs/statistics/stats-api.md b/_pages/documentation/general_docs/statistics/stats-api.md index 540e126030..753a503db5 100644 --- a/_pages/documentation/general_docs/statistics/stats-api.md +++ b/_pages/documentation/general_docs/statistics/stats-api.md @@ -6,6 +6,8 @@ doc: gem5 documentation permalink: /documentation/general_docs/statistics/api --- + + # Statistics APIs ## Contents diff --git a/_pages/documentation/general_docs/thermal_model.md b/_pages/documentation/general_docs/thermal_model.md index 2cbadf1b55..389a2399ca 100644 --- a/_pages/documentation/general_docs/thermal_model.md +++ b/_pages/documentation/general_docs/thermal_model.md @@ -6,6 +6,8 @@ parent: thermal_model permalink: /documentation/general_docs/thermal_model --- + + # Power and Thermal Model This document gives an overview of the power and thermal modelling diff --git a/_pages/documentation/index.md b/_pages/documentation/index.md index b0da1c440b..61fcae6f5c 100644 --- a/_pages/documentation/index.md +++ b/_pages/documentation/index.md @@ -9,8 +9,15 @@ author: Jason Lowe-Power # gem5 Documentation +## gem5 Bootcamp 2024 + +As of gem5 v24.0, the most comprehensive, up to date guide for learning how to use gem5 is the +material from the [summer 2024 gem5 bootcamp](https://bootcamp.gem5.org/). + ## Learning gem5 +**Notice: Many parts of Learning gem5 are outdated. Some sections of Learning gem5 have been updated for gem5 v24.1 based on content from the 2024 gem5 bootcamp, but others have not. Proceed with caution!** + [Learning gem5](learning_gem5/introduction/) gives a prose-heavy introduction to using gem5 for computer architecture research written by Jason Lowe-Power. This is a great resource for junior researchers who plan on using gem5 heavily for a research project. @@ -31,7 +38,7 @@ Please contact Jason (jason@lowepower.com) or create a PR if you find any errors [gem5 101](learning_gem5/gem5_101) is a set of assignments mostly from Wisconsin's graduate computer architecture classes (CS 752, CS 757, and CS 758) which will help you learn to use gem5 for research. ## gem5 API documentation - + You can find the doxygen-based documentation here: ## Other general gem5 documentation diff --git a/_pages/documentation/learning_gem5/part1/part1_1_building.md b/_pages/documentation/learning_gem5/part1/part1_1_building.md index 7ab3083ec1..459395c1f6 100644 --- a/_pages/documentation/learning_gem5/part1/part1_1_building.md +++ b/_pages/documentation/learning_gem5/part1/part1_1_building.md @@ -13,6 +13,12 @@ Building gem5 This chapter covers the details of how to set up a gem5 development environment and build gem5. +If you have a pre-built binary +----------------------------- + +If you are running gem5 using a pre-built binary, you can skip this section. +The pre-built binary uses the ALL build and can be used to run all ISAs and all Ruby coherence protocols. + Requirements for gem5 --------------------- @@ -21,11 +27,11 @@ See [gem5 requirements](http://www.gem5.org/documentation/general_docs/building# On Ubuntu, you can install all of the required dependencies with the following command. The requirements are detailed below. -``` +```bash sudo apt install build-essential git m4 scons zlib1g zlib1g-dev libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev python-dev python ``` -1. git ([Git](https://git-scm.com/)): +1. git ([Git](https://git-scm.com/)): : The gem5 project uses [Git](https://git-scm.com/) for version control. [Git](https://git-scm.com/) is a distributed version control system. More information about @@ -33,22 +39,23 @@ sudo apt install build-essential git m4 scons zlib1g zlib1g-dev libprotobuf-dev Git should be installed by default on most platforms. However, to install Git in Ubuntu use - ``` - sudo apt install git - ``` + ```bash + sudo apt install git + ``` -2. gcc 10+ +2. gcc 11+ : You may need to use environment variables to point to a non-default version of gcc. On Ubuntu, you can install a development environment with - ``` + ```bash sudo apt install build-essential ``` - **We support GCC Versions >=10, up to GCC 13** + **We support GCC Versions >=11, up to GCC 14** + 3. [SCons 3.0+](http://www.scons.org/) : gem5 uses SCons as its build environment. SCons is like make on steroids and uses Python scripts for all aspects of the build @@ -56,18 +63,19 @@ sudo apt install build-essential git m4 scons zlib1g zlib1g-dev libprotobuf-dev To get SCons on Ubuntu use - ``` - sudo apt install scons - ``` + ```bash + sudo apt install scons + ``` -4. Python 3.6+ +4. Python 3.9+ : gem5 relies on the Python development libraries. To install these on Ubuntu use - ``` - sudo apt install python3-dev - ``` + ```bash + sudo apt install python3-dev + ``` + 5. [protobuf](https://developers.google.com/protocol-buffers/) 2.1+ (**Optional**) : "Protocol buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data." In gem5, @@ -77,9 +85,9 @@ sudo apt install build-essential git m4 scons zlib1g zlib1g-dev libprotobuf-dev not a required package, unless you plan on using it for trace generation and playback. - ``` - sudo apt install libprotobuf-dev protobuf-compiler libgoogle-perftools-dev - ``` + ```bash + sudo apt install libprotobuf-dev protobuf-compiler libgoogle-perftools-dev + ``` 6. [Boost](https://www.boost.org/) (**Optional**) : The Boost library is a set of general purpose C++ libraries. It is a @@ -94,7 +102,7 @@ Getting the code Change directories to where you want to download the gem5 source. Then, to clone the repository, use the `git clone` command. -``` +```bash git clone https://github.com/gem5/gem5 ``` @@ -104,10 +112,10 @@ code. Your first gem5 build --------------------- -Let's start by building a basic x86 system. Currently, you must compile -gem5 separately for every ISA that you want to simulate. Additionally, -if using ruby-intro-chapter, you have to have separate compilations for -every cache coherence protocol. +Let's start by building a basic x86 system. As of gem5 v22.1, you can +compile the ALL build, which includes all ISAs. As of gem5 v24.1, the +ALL build also includes all Ruby cache coherence protocols. This is +relevant if you are using the ruby-intro-chapter. To build gem5, we will use SCons. SCons uses the SConstruct file (`gem5/SConstruct`) to set up a number of variables and then uses the @@ -121,16 +129,15 @@ options (ISA and cache coherence protocol) that you use to compile gem5. There are a number of default compilations options in the `build_opts` directory. These files specify the parameters used to build gem5 which have -non-default values. We'll use the X86 defaults and specify that we -want to compile all of the CPU models. You can look at the file -`build_opts/X86` to see the (kconfig) settings which have non-default values. -For gem5 <= 23.0, You can also specify these options on the command line to +non-default values. We'll use the ALL defaults. You can look at the file +`build_opts/ALL` to see the (kconfig) settings which have non-default values. +For gem5 <= 23.0, you can also specify these options on the command line to override any default values. For gem5 >= 23.1, You can use kconfig tools like setconfig, menuconfig, or guiconfig to modify these settings in an existing build directory. -``` -python3 `which scons` build/X86/gem5.opt -j9 +```bash +python3 `which scons` build/ALL/gem5.opt -j9 ``` > **gem5 binary types** @@ -160,75 +167,83 @@ python3 `which scons` build/X86/gem5.opt -j9 > unlikely your code has major bugs. > The main argument passed to SCons is what you want to build, -`build/X86/gem5.opt`. In this case, we are building gem5.opt (an +`build/ALL/gem5.opt`. In this case, we are building gem5.opt (an optimized binary with debug symbols). We want to build gem5 in the -directory build/X86. Since this directory currently doesn't exist, SCons -will look in `build_opts` to find the parameters for X86. (Note: +directory build/ALL. Since this directory currently doesn't exist, SCons +will look in `build_opts` to find the parameters for the ALL build. (Note: I'm using -j9 here to execute the build on 9 of my 8 cores on my machine. You should choose an appropriate number for your machine, usually cores+1.) -The output should look something like below (For gem5 >= 23.1): +The output should look something like below (For gem5 >= 24.1): +```txt scons: Reading SConscript files ... - Mkdir("/local.chinook/gem5/gem5-tutorial/gem5/build/X86/gem5.build") - Checking for linker -Wl,--as-needed support... yes - Checking for compiler -gz support... yes - Checking for linker -gz support... yes + Mkdir("/local.chinook/gem5/gem5-tutorial/gem5/build/ALL/gem5.build") + Checking for linker -Wl,--as-needed support... (cached) yes + Checking for compiler -gz support... (cached) yes + Checking for linker -gz support... (cached) yes Info: Using Python config: python3-config - Checking for C header file Python.h... yes - Checking Python version... 3.11.5 - Checking for accept(0,0,0) in C++ library None... yes - Checking for zlibVersion() in C++ library z... yes - Checking for pkg-config package protobuf... yes - Checking for clock_nanosleep(0,0,NULL,NULL) in C library None... yes - Checking for timer_create(CLOCK_MONOTONIC, NULL, NULL) in C library None... yes - Checking for C library tcmalloc_minimal... yes - Checking for backtrace_symbols_fd((void *)1, 0, 0) in C library None... yes - Checking for C header file png.h... yes - Checking for C header file fenv.h... yes - Checking for C header file capstone/capstone.h... no - Checking for C header file linux/kvm.h... yes - Checking size of struct kvm_xsave ... yes - Checking for member exclude_host in struct perf_event_attr...yes - Checking for C header file valgrind/valgrind.h... yes - Checking for pkg-config package hdf5-serial... no - Checking for pkg-config package hdf5... no - Checking for H5Fcreate("", 0, 0, 0) in C library hdf5... no - Checking for shm_open("/test", 0, 0) in C library None... yes - Checking for C header file linux/if_tun.h... yes - "ext/Kconfiglib/defconfig.py" --kconfig "/local.chinook/gem5/gem5-tutorial/gem5/build/X86/gem5.build/Kconfig" "/local.chinook/gem5/gem5-tutorial/gem5/build_opts/X86" - Loaded configuration '/local.chinook/gem5/gem5-tutorial/gem5/build_opts/X86' - Configuration saved to '/local.chinook/gem5/gem5-tutorial/gem5/build/X86/gem5.build/config' - Checking whether __i386__ is declared... no - Checking whether __x86_64__ is declared... yes - Checking for compiler -Wno-self-assign-overloaded support... yes - Checking for linker -Wno-free-nonheap-object support... yes + Checking for C header file Python.h... (cached) yes + Checking Python version... (cached) 3.12.3 + Checking for accept(0,0,0) in C++ library None... (cached) yes + Checking for zlibVersion() in C++ library z... (cached) yes + Checking for C library tcmalloc_minimal... (cached) yes + Building in /home/bees/gem5-4th-worktree/build/ALL + "build_tools/kconfig_base.py" "/home/bees/gem5-4th-worktree/build/ALL/gem5.build/Kconfig" "/home/bees/gem5-4th-worktree/src/Kconfig" + Checking for C header file fenv.h... (cached) yes + Checking for C header file png.h... (cached) yes + Checking for clock_nanosleep(0,0,NULL,NULL) in C library None... (cached) yes + Checking for C header file valgrind/valgrind.h... (cached) yes + Checking for pkg-config package hdf5-serial... (cached) yes + Checking for H5Fcreate("", 0, 0, 0) in C library hdf5... (cached) yes + Checking for H5::H5File("", 0) in C++ library hdf5_cpp... (cached) yes + Checking for pkg-config package protobuf... (cached) yes + Checking for shm_open("/test", 0, 0) in C library None... (cached) yes + Checking for backtrace_symbols_fd((void *)1, 0, 0) in C library None... (cached) yes + Checking size of struct kvm_xsave ... (cached) yes + Checking for C header file capstone/capstone.h... (cached) yes + Checking for C header file linux/kvm.h... (cached) yes + Checking for timer_create(CLOCK_MONOTONIC, NULL, NULL) in C library None... (cached) yes + Checking for member exclude_host in struct perf_event_attr...(cached) yes + Checking for C header file linux/if_tun.h... (cached) yes + Checking whether __i386__ is declared... (cached) no + Checking whether __x86_64__ is declared... (cached) yes + Checking for compiler -Wno-self-assign-overloaded support... (cached) yes + Checking for linker -Wno-free-nonheap-object support... (cached) yes + BUILD_TLM not set, not building CHI-TLM integration + scons: done reading SConscript files. scons: Building targets ... - [ISA DESC] X86/arch/x86/isa/main.isa -> generated/inc.d - [NEW DEPS] X86/arch/x86/generated/inc.d -> x86-deps - [ENVIRONS] x86-deps -> x86-environs - [ CXX] X86/sim/main.cc -> .o + [ CXX] ALL/base/Graphics.py.cc -> .o + [ LINK] -> ALL/gem5py_m5 + [ CXX] src/base/atomicio.cc -> ALL/base/atomicio.o + [ CXX] src/base/bitfield.cc -> ALL/base/bitfield.o + .... .... .... - [ SHCXX] nomali/lib/mali_midgard.cc -> .os - [ SHCXX] nomali/lib/mali_t6xx.cc -> .os - [ SHCXX] nomali/lib/mali_t7xx.cc -> .os - [ AR] -> drampower/libdrampower.a - [ SHCXX] nomali/lib/addrspace.cc -> .os - [ SHCXX] nomali/lib/mmu.cc -> .os - [ RANLIB] -> drampower/libdrampower.a - [ SHCXX] nomali/lib/nomali_api.cc -> .os - [ AR] -> nomali/libnomali.a - [ RANLIB] -> nomali/libnomali.a - [ CXX] X86/base/date.cc -> .o - [ LINK] -> X86/gem5.opt - scons: done building targets. + [SO Param] m5.objects.Uart, Uart8250 -> ALL/params/Uart8250.hh + [ CXX] ALL/python/_m5/param_SimpleUart.cc -> .o + [ CXX] ALL/enums/TerminalDump.cc -> .o + [ CXX] ALL/python/_m5/param_Uart8250.cc -> .o + [ CXX] src/dev/serial/serial.cc -> ALL/dev/serial/serial.o + [ CXX] src/dev/serial/simple.cc -> ALL/dev/serial/simple.o + [ CXX] src/dev/serial/terminal.cc -> ALL/dev/serial/terminal.o + [ CXX] src/dev/serial/uart.cc -> ALL/dev/serial/uart.o + [ CXX] src/dev/serial/uart8250.cc -> ALL/dev/serial/uart8250.o + [ CXX] ALL/debug/Terminal.cc -> .o + [ CXX] ALL/debug/TerminalVerbose.cc -> .o + [ CXX] ALL/debug/Uart.cc -> .o + [ CXX] ALL/python/m5/defines.py.cc -> .o + [ CXX] ALL/python/m5/info.py.cc -> .o + [ CXX] src/base/date.cc -> ALL/base/date.o + [ LINK] -> ALL/gem5.opt +scons: done building targets. +``` When compilation is finished you should have a working gem5 executable -at `build/X86/gem5.opt`. The compilation can take a very long time, +at `build/ALL/gem5.opt`. The compilation can take a very long time, often 15 minutes or more, especially if you are compiling on a remote file system like AFS or NFS. @@ -237,8 +252,10 @@ Common errors ### Wrong gcc version +```txt Error: gcc version 5 or newer required. Installed version: 4.4.7 +``` Update your environment variables to point to the right gcc version, or install a more up to date version of gcc. See @@ -253,29 +270,33 @@ causes the issue. gem5 often builds successfully in this case, but may not be able to run. Below is one possible error you may see when you run gem5. +```txt Traceback (most recent call last): File "........../gem5-stable/src/python/importer.py", line 93, in sys.meta_path.append(importer) TypeError: 'dict' object is not callable +``` To fix this, you can force SCons to use your environment's Python -version by running `` python3 `which scons` build/X86/gem5.opt `` instead -of `scons build/X86/gem5.opt`. +version by running `` python3 `which scons` build/ALL/gem5.opt `` instead +of `scons build/ALL/gem5.opt`. ### M4 macro processor not installed If the M4 macro processor isn't installed you'll see an error similar to this: +```txt ... Checking for member exclude_host in struct perf_event_attr...yes Error: Can't find version of M4 macro processor. Please install M4 and try again. +``` Just installing the M4 macro package may not solve this issue. You may nee to also install all of the `autoconf` tools. On Ubuntu, you can use the following command. -``` +```bash sudo apt-get install automake ``` @@ -283,7 +304,7 @@ sudo apt-get install automake Compiling gem5 using protobuf might result in the following error, -``` +```txt In file included from build/X86/cpu/trace/trace_cpu.hh:53, from build/X86/cpu/trace/trace_cpu.cc:38: build/X86/proto/inst_dep_record.pb.h:49:51: error: 'AuxiliaryParseTableField' in namespace 'google::protobuf::internal' does not name a type; did you mean 'AuxillaryParseTableField'? @@ -293,19 +314,22 @@ build/X86/proto/inst_dep_record.pb.h:49:51: error: 'AuxiliaryParseTableField' in The root cause of the problem is discussed here: [https://gem5.atlassian.net/browse/GEM5-1032]. To resolve this problem, you may need to update the version of ProtocolBuffer, -``` + +```bash sudo apt update sudo apt install libprotobuf-dev protobuf-compiler libgoogle-perftools-dev ``` After that, you may need to clean the gem5 build folder **before** recompiling gem5, -``` + +```bash python3 `which scons` --clean --no-cache # cleaning the build folder -python3 `which scons` build/X86/gem5.opt -j 9 # re-compiling gem5 +python3 `which scons` build/ALL/gem5.opt -j 9 # re-compiling gem5 ``` If the problem persists, you may need to completely remove the gem5 build folder **before** compiling gem5 again, -``` + +```bash rm -rf build/ # completely removing the gem5 build folder -python3 `which scons` build/X86/gem5.opt -j 9 # re-compiling gem5 +python3 `which scons` build/ALL/gem5.opt -j 9 # re-compiling gem5 ``` diff --git a/_pages/documentation/learning_gem5/part1/part1_2_simple_config.md b/_pages/documentation/learning_gem5/part1/part1_2_simple_config.md index 7ee4c07f3e..acad4a9042 100644 --- a/_pages/documentation/learning_gem5/part1/part1_2_simple_config.md +++ b/_pages/documentation/learning_gem5/part1/part1_2_simple_config.md @@ -14,7 +14,7 @@ Creating a simple configuration script This chapter of the tutorial will walk you through how to set up a simple simulation script for gem5 and to run gem5 for the first time. It's assumed that you've completed the first chapter of the tutorial and -have successfully built gem5 with an executable `build/X86/gem5.opt`. +have successfully built gem5 with an executable `build/ALL/gem5.opt`. Our configuration script is going to model a very simple system. We'll have just one simple CPU core. This CPU core will be connected to a @@ -24,25 +24,30 @@ also connected to the memory bus. gem5 configuration scripts -------------------------- -The gem5 binary takes, as a parameter, a python script which sets up and +The gem5 binary takes, as a parameter, a Python script which sets up and executes the simulation. In this script, you create a system to simulate, create all of the components of the system, and specify all of the parameters for the system components. Then, from the script, you can begin the simulation. -This script is completely user-defined. You can choose to use any valid + -There are a number of example configuration scripts that ship with gem5 -in `configs/examples`. Most of these scripts are all-encompassing and + + +There are a number of example configuration scripts that ship with gem5 +in `configs/examples`. +The scripts most relevant to a beginner to gem5 are located in `configs/examples/gem5-library`. +These are scripts that are intended to be used with the gem5 standard library, +which provides components that can be connected together to form a complete system. --- @@ -59,13 +64,121 @@ how simulation scripts work. --- +Setting up a configuration script for gem5 v24.1 +================================================ + +**Notice: The content of this section is taken from part 1, section 2 of the 2024 gem5 bootcamp. The slides for the bootcamp can be found [here](https://bootcamp.gem5.org/#01-Introduction/02-getting-started)** + +Let's start by creating a new config file and opening it: + +```bash +mkdir configs/tutorial/part1/ +touch configs/tutorial/part1/simple.py +``` + +This is just a normal python file that will be executed by the embedded +python in the gem5 executable. Therefore, you can use any features and +libraries available in python. + +To set up a basic configuration script, we can start by adding our imports: + +```python +from gem5.prebuilt.demo.x86_demo_board import X86DemoBoard +from gem5.resources.resource import obtain_resource +from gem5.simulate.simulator import Simulator +``` + +Next, add a board to your script: + +```python +board = X86DemoBoard() +``` + +The X86DemoBoard is a prebuilt board that doesn't require further configuration and can be used as a complete system as-is. It is not recommended for use in research, however. + +The source can be found in the gem5 repository at [src/python/gem5/prebuilt/demo/x86_demo_board.py](https://github.com/gem5/gem5/blob/stable/src/python/gem5/prebuilt/demo/x86_demo_board.py) + +It has the following properties: + +* 3GiB DualChannelDDR4_2400 memory +* A 2 core processor using gem5's `TIMING` model +* A private L1, shared L2 cache hierarchy with 64 KiB data and instruction caches and a 8MiB L2 cache. + +As of gem5 v24.1, the X86DemoBoard can support both SE (system emulation) and FS (full system) simulations. + +Next, let's set a workload to run on the board: + +```python +board.set_workload( + obtain_resource("x86-ubuntu-24.04-boot-no-systemd") +) +``` + +The function `obtain_resource` downloads workloads and resources. +For the `x86-ubuntu-24.04-boot-no-systemd`, it downloads a disk image and kernel, and sets default parameters. + +The workload boots Ubuntu without systemd. +There are three exit events in the workload, and the simulation can exit or perform other operations at each exit event. +To change the behavior at an exit event, we will need to set up an exit event handler. + +However, we will only run the simulation for 20 billion ticks, or 20 ms, in this example: + +```python +sim = Simulator(board) +sim.run(20_000_000_000) # 20 billion ticks or 20 ms +``` + +To run the simulation after setting up the configuration script, use the following command: + +```bash +./build/ALL/gem5.opt configs/tutorial/part1/simple.py +``` + +If you are using a pre-built gem5 binary, use the following command: + +```bash +gem5 configs/tutorial/part1/simple.py +``` + +The output should look something like this: + +```txt +gem5 Simulator System. https://www.gem5.org +gem5 is copyrighted software; use the --copyright option for details. + +gem5 version 24.1.0.0 +gem5 compiled Dec 13 2024 14:59:49 +gem5 started Dec 16 2024 13:07:46 +gem5 executing on amarillo, pid 543078 +command line: ./build/ALL/gem5.opt gem5-dev/testing-website-tutorial/tutorial/part1/simple.py + +warn: The X86DemoBoard is solely for demonstration purposes. This board is not known to be be representative of any real-world system. Use with caution. +info: Using default config +warn: Max ticks has already been set prior to setting it through the run call. In these cases the max ticks set through the `run` function is used +Global frequency set at 1000000000000 ticks per second +warn: board.workload.acpi_description_table_pointer.rsdt adopting orphan SimObject param 'entries' +src/mem/dram_interface.cc:690: warn: DRAM device capacity (16384 Mbytes) does not match the address range assigned (2048 Mbytes) +src/mem/dram_interface.cc:690: warn: DRAM device capacity (16384 Mbytes) does not match the address range assigned (2048 Mbytes) +src/sim/kernel_workload.cc:46: info: kernel located at: /home/bees/.cache/gem5/x86-linux-kernel-5.4.0-105-generic + 0: board.pc.south_bridge.cmos.rtc: Real-time clock set to Sun Jan 1 00:00:00 2012 +board.pc.com_1.device: Listening for connections on port 3467 +src/base/statistics.hh:279: warn: One of the stats is a legacy stat. Legacy stat is a stat that does not belong to any statistics::Group. Legacy stat is deprecated. +src/dev/intel_8254_timer.cc:128: warn: Reading current count from inactive timer. +board.remote_gdb: Listening for connections on port 7003 +src/sim/simulate.cc:199: info: Entering event queue @ 0. Starting simulation... +build/ALL/arch/x86/generated/exec-ns.cc.inc:27: warn: instruction 'fninit' unimplemented + +``` + +Setting up a configuration script for gem5 v21.0 +============== Creating a config file ---------------------- Let's start by creating a new config file and opening it: -``` +```bash mkdir configs/tutorial/part1/ touch configs/tutorial/part1/simple.py ``` @@ -74,13 +187,13 @@ This is just a normal python file that will be executed by the embedded python in the gem5 executable. Therefore, you can use any features and libraries available in python. -The first thing we'll do in this file is import the m5 library and all + Next, we'll create the first SimObject: the system that we are going to simulate. The `System` object will be the parent of all the other @@ -90,7 +203,7 @@ ranges, the root clock domain, the root voltage domain, the kernel (in full-system simulation), etc. To create the system SimObject, we simply instantiate it like a normal python class: -``` +```python system = System() ``` @@ -103,7 +216,7 @@ Finally, we have to specify a voltage domain for this clock domain. Since we don't care about system power right now, we'll just use the default options for the voltage domain. -``` +```python system.clk_domain = SrcClockDomain() system.clk_domain.clock = '1GHz' system.clk_domain.voltage_domain = VoltageDomain() @@ -120,7 +233,7 @@ like `'512MB'`. Similarly, with time you can use time units (e.g., `'5ns'`). These will automatically be converted to a common representation, respectively. -``` +```python system.mem_mode = 'timing' system.mem_ranges = [AddrRange('512MB')] ``` @@ -131,7 +244,7 @@ in a single clock cycle to execute, except memory requests, which flow through the memory system. To create the CPU you can simply just instantiate the object: -``` +```python system.cpu = X86TimingSimpleCPU() ``` @@ -170,7 +283,7 @@ system.cpu.dcache_port = system.membus.cpu_side_ports > files. You can simply set the request port `=` to the response port > and they will be connected. For instance: > -> ``` +> ```python > system.cpu.icache_port = system.l1_cache.cpu_side > ``` > @@ -185,7 +298,7 @@ system.cpu.dcache_port = system.membus.cpu_side_ports > configuration is that, it is allowed to have one port on one side, and an > array of ports on the other side. For example: > -> ``` +> ```python > system.cpu.icache_port = system.membus.cpu_side_ports > ``` > @@ -196,7 +309,6 @@ system.cpu.dcache_port = system.membus.cpu_side_ports > > We will discuss ports and MemObject in more detail in the [MemObject chapter](http://www.gem5.org/documentation/learning_gem5/part2/memoryobject/). - --- Next, we need to connect up a few other ports to make sure that our @@ -323,7 +435,7 @@ one positional argument, the simulation script. So, we can simply run gem5 from the root gem5 directory as: ``` -build/X86/gem5.opt configs/tutorial/part1/simple.py +build/ALL/gem5.opt configs/tutorial/part1/simple.py ``` The output should be: diff --git a/_pages/documentation/learning_gem5/part1/part1_3_cache_config.md b/_pages/documentation/learning_gem5/part1/part1_3_cache_config.md deleted file mode 100644 index b4846f8a5b..0000000000 --- a/_pages/documentation/learning_gem5/part1/part1_3_cache_config.md +++ /dev/null @@ -1,395 +0,0 @@ ---- -layout: documentation -title: Adding cache to configuration script -doc: Learning gem5 -parent: part1 -permalink: /documentation/learning_gem5/part1/cache_config/ -author: Jason Lowe-Power ---- - - -Adding cache to the configuration script -======================================== - -Using the [previous configuration script as a starting point](http://www.gem5.org/documentation/learning_gem5/part1/simple_config/), -this chapter will walk through a more complex configuration. We will add -a cache hierarchy to the system as shown in -the figure below. Additionally, this chapter -will cover understanding the gem5 statistics output and adding command -line parameters to your scripts. - -![A system configuration with a two-level cache -hierarchy.](/pages/static/figures/advanced_config.png) - -Creating cache objects ----------------------- - -We are going to use the classic caches, instead of ruby-intro-chapter, -since we are modeling a single CPU system and we don't care about -modeling cache coherence. We will extend the Cache SimObject and -configure it for our system. First, we must understand the parameters -that are used to configure Cache objects. - -> **Classic caches and Ruby** -> -> gem5 currently has two completely distinct subsystems to model the -> on-chip caches in a system, the "Classic caches" and "Ruby". The -> historical reason for this is that gem5 is a combination of m5 from -> Michigan and GEMS from Wisconsin. GEMS used Ruby as its cache model, -> whereas the classic caches came from the m5 codebase (hence -> "classic"). The difference between these two models is that Ruby is -> designed to model cache coherence in detail. Part of Ruby is SLICC, a -> language for defining cache coherence protocols. On the other hand, -> the classic caches implement a simplified and inflexible MOESI -> coherence protocol. -> -> To choose which model to use, you should ask yourself what you are -> trying to model. If you are modeling changes to the cache coherence -> protocol or the coherence protocol could have a first-order impact on -> your results, use Ruby. Otherwise, if the coherence protocol isn't -> important to you, use the classic caches. -> -> A long-term goal of gem5 is to unify these two cache models into a -> single holistic model. - -### Cache - -The Cache SimObject declaration can be found in src/mem/cache/Cache.py. -This Python file defines the parameters which you can set of the -SimObject. Under the hood, when the SimObject is instantiated these -parameters are passed to the C++ implementation of the object. The -`Cache` SimObject inherits from the `BaseCache` object shown below. - -Within the `BaseCache` class, there are a number of *parameters*. For -instance, `assoc` is an integer parameter. Some parameters, like -`write_buffers` have a default value, 8 in this case. The default -parameter is the first argument to `Param.*`, unless the first argument -is a string. The string argument of each of the parameters is a -description of what the parameter is (e.g., -`tag_latency = Param.Cycles("Tag lookup latency")` means that the -`` tag_latency `` controls "The hit latency for this cache"). - -Many of these parameters do not have defaults, so we are required to set -these parameters before calling `m5.instantiate()`. - -* * * * * - -Now, to create caches with specific parameters, we are first going to -create a new file, `caches.py`, in the same directory as simple.py, -`configs/tutorial/part1`. The first step is to import the SimObject(s) -we are going to extend in this file. - -``` -from m5.objects import Cache -``` - -Next, we can treat the BaseCache object just like any other Python class -and extend it. We can name the new cache anything we want. Let's start -by making an L1 cache. - -``` -class L1Cache(Cache): - assoc = 2 - tag_latency = 2 - data_latency = 2 - response_latency = 2 - mshrs = 4 - tgts_per_mshr = 20 -``` - -Here, we are setting some of the parameters of the BaseCache that do not -have default values. To see all of the possible configuration options, -and to find which are required and which are optional, you have to look -at the source code of the SimObject. In this case, we are using -BaseCache. - -We have extended `BaseCache` and set most of the parameters that do not -have default values in the `BaseCache` SimObject. Next, let's two more -sub-classes of L1Cache, an L1DCache and L1ICache - -``` -class L1ICache(L1Cache): - size = '16kB' - -class L1DCache(L1Cache): - size = '64kB' -``` - -Let's also create an L2 cache with some reasonable parameters. - -``` -class L2Cache(Cache): - size = '256kB' - assoc = 8 - tag_latency = 20 - data_latency = 20 - response_latency = 20 - mshrs = 20 - tgts_per_mshr = 12 -``` - -Now that we have specified all of the necessary parameters required for -`BaseCache`, all we have to do is instantiate our sub-classes and -connect the caches to the interconnect. However, connecting lots of -objects up to complex interconnects can make configuration files quickly -grow and become unreadable. Therefore, let's first add some helper -functions to our sub-classes of `Cache`. Remember, these are just Python -classes, so we can do anything with them that you can do with a Python -class. - -To the L1 cache let's add two functions, `connectCPU` to connect a CPU -to the cache and `connectBus` to connect the cache to a bus. We need to -add the following code to the `L1Cache` class. - -``` -def connectCPU(self, cpu): - # need to define this in a base class! - raise NotImplementedError - -def connectBus(self, bus): - self.mem_side = bus.cpu_side_ports -``` - -Next, we have to define a separate `connectCPU` function for the -instruction and data caches, since the I-cache and D-cache ports have a -different names. Our `L1ICache` and `L1DCache` classes now become: - -``` -class L1ICache(L1Cache): - size = '16kB' - - def connectCPU(self, cpu): - self.cpu_side = cpu.icache_port - -class L1DCache(L1Cache): - size = '64kB' - - def connectCPU(self, cpu): - self.cpu_side = cpu.dcache_port -``` - -Finally, let's add functions to the `L2Cache` to connect to the -memory-side and CPU-side bus, respectively. - -``` -def connectCPUSideBus(self, bus): - self.cpu_side = bus.mem_side_ports - -def connectMemSideBus(self, bus): - self.mem_side = bus.cpu_side_ports -``` - -The full file can be found in the gem5 source at -[`configs/learning_gem5/part1/caches.py`](https://github.com/gem5/gem5/blob/stable/configs/learning_gem5/part1/caches.py). - -Adding caches to the simple config file ------------------------------------- - -Now, let's add the caches we just created to the configuration script we -created in the [last chapter](http://www.gem5.org/documentation/learning_gem5/part1/simple_config/). - -First, let's copy the script to a new name. - -``` -cp ./configs/tutorial/part1/simple.py ./configs/tutorial/part1/two_level.py -``` - -First, we need to import the names from the `caches.py` file into the -namespace. We can add the following to the top of the file (after the -m5.objects import), as you would with any Python source. - -``` -from caches import * -``` - -Now, after creating the CPU, let's create the L1 caches: - -``` -system.cpu.icache = L1ICache() -system.cpu.dcache = L1DCache() -``` - -And connect the caches to the CPU ports with the helper function we -created. - -``` -system.cpu.icache.connectCPU(system.cpu) -system.cpu.dcache.connectCPU(system.cpu) -``` - -You need to *remove* the following two lines which connected the cache -ports directly to the memory bus. - -``` -system.cpu.icache_port = system.membus.cpu_side_ports -system.cpu.dcache_port = system.membus.cpu_side_ports -``` - -We can't directly connect the L1 caches to the L2 cache since the L2 -cache only expects a single port to connect to it. Therefore, we need to -create an L2 bus to connect our L1 caches to the L2 cache. The, we can -use our helper function to connect the L1 caches to the L2 bus. - -``` -system.l2bus = L2XBar() - -system.cpu.icache.connectBus(system.l2bus) -system.cpu.dcache.connectBus(system.l2bus) -``` - -Next, we can create our L2 cache and connect it to the L2 bus and the -memory bus. - -``` -system.l2cache = L2Cache() -system.l2cache.connectCPUSideBus(system.l2bus) -system.membus = SystemXBar() -system.l2cache.connectMemSideBus(system.membus) -``` - -Note that `system.membus = SystemXBar()` has been defined before -`system.l2cache.connectMemSideBus` so we can pass it to -`system.l2cache.connectMemSideBus`. Everything else in the file -stays the same! Now we have a complete configuration with a -two-level cache hierarchy. If you run the current file, `hello` -should now finish in 57467000 ticks. The full script can -be found in the gem5 source at -[`configs/learning_gem5/part1/two_level.py`](https://github.com/gem5/gem5/blob/stable/configs/learning_gem5/part1/two_level.py). - -Adding parameters to your script --------------------------------- - -When performing experiments with gem5, you don't want to edit your -configuration script every time you want to test the system with -different parameters. To get around this, you can add command-line -parameters to your gem5 configuration script. Again, because the -configuration script is just Python, you can use the Python libraries -that support argument parsing. Although pyoptparse is officially -deprecated, many of the configuration scripts that ship with gem5 use it -instead of pyargparse since gem5's minimum Python version used to be -2.5. The minimum Python version is now 3.6, so Python's argparse is a better -option when writing new scripts that don't need to interact with the -current gem5 scripts. To get started using :pyoptparse, you can consult -the online Python documentation. - -To add options to our two-level cache configuration, after importing our -caches, let's add some options. - -``` -import argparse - -parser = argparse.ArgumentParser(description='A simple system with 2-level cache.') -parser.add_argument("binary", default="", nargs="?", type=str, - help="Path to the binary to execute.") -parser.add_argument("--l1i_size", - help=f"L1 instruction cache size. Default: 16kB.") -parser.add_argument("--l1d_size", - help="L1 data cache size. Default: Default: 64kB.") -parser.add_argument("--l2_size", - help="L2 cache size. Default: 256kB.") - -options = parser.parse_args() -``` -Note that if you wanted to pass the binary file's path the way shown above -and use it through options, you should specify it as `options.binary`. -For example: - -``` -system.workload = SEWorkload.init_compatible(options.binary) -``` - -Now, you can run -`build/X86/gem5.opt configs/tutorial/part1/two_level.py --help` which -will display the options you just added. - -Next, we need to pass these options onto the caches that we create in -the configuration script. To do this, we'll simply change two\_level\_opts.py -to pass the options into the caches as a parameter to their constructor -and add an appropriate constructor, next. - -``` -system.cpu.icache = L1ICache(options) -system.cpu.dcache = L1DCache(options) -... -system.l2cache = L2Cache(options) -``` - -In caches.py, we need to add constructors (`__init__` functions in -Python) to each of our classes. Starting with our base L1 cache, we'll -just add an empty constructor since we don't have any parameters which -apply to the base L1 cache. However, we can't forget to call the super -class's constructor in this case. If the call to the super class -constructor is skipped, gem5's SimObject attribute finding function will -fail and the result will be -"`RuntimeError: maximum recursion depth exceeded`" when you try to -instantiate the cache object. So, in `L1Cache` we need to add the -following after the static class members. - -``` -def __init__(self, options=None): - super(L1Cache, self).__init__() - pass -``` - -Next, in the `L1ICache`, we need to use the option that we created -(`l1i_size`) to set the size. In the following code, there is guards for -if `options` is not passed to the `L1ICache` constructor and if no -option was specified on the command line. In these cases, we'll just use -the default we've already specified for the size. - -``` -def __init__(self, options=None): - super(L1ICache, self).__init__(options) - if not options or not options.l1i_size: - return - self.size = options.l1i_size -``` - -We can use the same code for the `L1DCache`: - -``` -def __init__(self, options=None): - super(L1DCache, self).__init__(options) - if not options or not options.l1d_size: - return - self.size = options.l1d_size -``` - -And the unified `L2Cache`: - -``` -def __init__(self, options=None): - super(L2Cache, self).__init__() - if not options or not options.l2_size: - return - self.size = options.l2_size -``` - -With these changes, you can now pass the cache sizes into your script -from the command line like below. - -``` -build/X86/gem5.opt configs/tutorial/part1/two_level.py --l2_size='1MB' --l1d_size='128kB' -``` - - gem5 Simulator System. http://gem5.org - gem5 is copyrighted software; use the --copyright option for details. - - gem5 version 21.0.0.0 - gem5 compiled May 17 2021 18:05:59 - gem5 started May 18 2021 00:00:33 - gem5 executing on amarillo, pid 83118 - command line: build/X86/gem5.opt configs/tutorial/part1/two_level.py --l2_size=1MB --l1d_size=128kB - - Global frequency set at 1000000000000 ticks per second - warn: No dot file generated. Please install pydot to generate the dot file and pdf. - warn: DRAM device capacity (8192 Mbytes) does not match the address range assigned (512 Mbytes) - 0: system.remote_gdb: listening for remote gdb on port 7005 - Beginning simulation! - info: Entering event queue @ 0. Starting simulation... - Hello world! - Exiting @ tick 57467000 because exiting with last active thread context - -The full scripts can be found in the gem5 source at -[`configs/learning_gem5/part1/caches.py`](https://github.com/gem5/gem5/blob/stable/configs/learning_gem5/part1/caches.py) and -[`configs/learning_gem5/part1/two_level.py`](https://github.com/gem5/gem5/blob/stable/configs/learning_gem5/part1/two_level.py). diff --git a/_pages/documentation/learning_gem5/part1/part1_3_more_complex_config.md b/_pages/documentation/learning_gem5/part1/part1_3_more_complex_config.md new file mode 100644 index 0000000000..4e70dcc673 --- /dev/null +++ b/_pages/documentation/learning_gem5/part1/part1_3_more_complex_config.md @@ -0,0 +1,901 @@ +--- +layout: documentation +title: Adding cache to configuration script +doc: Learning gem5 +parent: part1 +permalink: /documentation/learning_gem5/part1/cache_config/ +author: Jason Lowe-Power +--- + +More complex config for gem5 v24.1 +=============================== + +**Notice: The material in the following section is taken from section 2, part 1 of the 2024 gem5 bootcamp. The link to the slides is [here](https://bootcamp.gem5.org/#02-Using-gem5/01-stdlib)** + +In the previous section, we learned the basics of setting up a Python configuration script for use with gem5. +The previous section's config script uses the X86DemoBoard, which is pre-configured with caches, memory, etc. +In this section, we will learn how to use other components in the gem5 standard library to set up a simulation. + +What is the gem5 standard library? +---------------------------------- + +The gem5 standard library provides a set of predefined components that can be used to define a system in a configuration script. +Without the standard library, you would have to define every part of your simulation, potentially resulting in scripts with hundreds of lines of code even for the most basic of simulations. + +Main Idea +--------- + +Due to its modular, object-oriented design, gem5 can be thought of as a set of components that can be plugged together to form a simulation. +The types of components are boards, processors, memory systems, and cache hierarchies: + +- Board: The "backbone" of the system. You plug components into the board. The board also contains the system-level things like devices, workload, etc. It's the boards job to negotiate the connections between other components. +- Processor: Processors connect to boards and have one or more cores. +- Cache hierarchy: A cache hierarchy is a set of caches that can be connected to a processor and memory system. +- Memory system: A memory system is a set of memory controllers and memory devices that can be connected to the cache hierarchy. + +Relationship to gem5 models +--------------------------- + +The C++ code in gem5 specifies parameterized models (typically referred to "SimObjects" in most gem5 literature). +These models are then instantiated in the pre-made Python scripts in the gem5 standard library. + +The standard library is a way to wrap these models in a standard API into, what we call, components. + +The gem5 models are fine grained concepts, while components are coarser grained and typically contain many models instantiated with sensible parameters. +For example, a gem5 model could be a core, and a component could be a processor with multiple cores that also specifies bus connections and sets parameters to sensible vlaues. + +If you want to create a new component you are encouraged to extend (i.e., subclass) the components in the standard library or create new components. +This allows you to choose the models within the component and the value of their parameters. + +Setting up the configuration script +----------------------------------- +First, let's make a configuration file: + +```bash +mkdir configs/tutorial/part1/ +touch configs/tutorial/part1/components.py +``` + +Let's add our imports: + +```python +from gem5.components.boards.simple_board import SimpleBoard +from gem5.components.processors.simple_processor import SimpleProcessor +from gem5.components.cachehierarchies.ruby.mesi_two_level_cache_hierarchy import ( + MESITwoLevelCacheHierarchy, +) +from gem5.components.memory.single_channel import SingleChannelDDR4_2400 +from gem5.components.processors.cpu_types import CPUTypes +from gem5.isas import ISA +from gem5.resources.resource import obtain_resource +from gem5.simulate.simulator import Simulator +``` + +Next, let's add our cache hierarchy: + +```python +cache_hierarchy = MESITwoLevelCacheHierarchy( + l1d_size="16KiB", + l1d_assoc=8, + l1i_size="16KiB", + l1i_assoc=8, + l2_size="256KiB", + l2_assoc=16, + num_l2_banks=1, +) +``` + +MESITwoLevelCacheHierarchy is a component that represents a two-level MESI cache hierarchy. +This uses the Ruby memory model. See [here]https://bootcamp.gem5.org/#02-Using-gem5/05-cache-hierarchies for more information about caches in gem5. + +The component for the cache hierarchy is parameterized with the sizes and associativities of the L1 and L2 caches. + +Next, let's add a memory system: + +```python +memory = SingleChannelDDR4_2400() +``` + +This component represents a single-channel DDR3 memory system. + +There is a size parameter that can be used to specify the size of the memory system of the simulated system. +You can reduce the size to save simulation time, or use the default for the memory type (e.g., one channel of DDR3 defaults to 8 GiB). +There are also multi channel memories available. You can see [these](https://bootcamp.gem5.org/#02-Using-gem5/06-memory) gem5 2024 bootcamp slides for more information. + +Next, let's add a processor: + +```python +processor = SimpleProcessor(cpu_type=CPUTypes.TIMING, isa=ISA.ARM, num_cores=1) +``` + +The `SimpleProcessor` is a component that allows you to customize the model for the underlying cores. +The `cpu_type` parameter specifies the type of CPU model to use. + +Next, let's add a board and plug in components: + +```python +board = SimpleBoard( + clk_freq="3GHz", + processor=processor, + memory=memory, + cache_hierarchy=cache_hierarchy, +) +``` + +The SimpleBoard can run any ISA in Syscall Emulation (SE) mode. +It is "Simple" due the relative simplicity of SE mode. +Most boards are tied to a specific ISA and require more complex designs to run Full System (FS) simulation. +You can find the boards in the gem5 standard library at `src/python/gem5/components/boards`. The demo boards are located in `src/python/gem5/prebuilt/demo`. + +Next, set up the workload: + +```python +board.set_workload(obtain_resource("arm-gapbs-bfs-run")) +``` + +The obtain_resource function downloads the files needed to run the specified workload. +In this case "arm-gapbs-bfs-run" is a BFS workload from the GAP Benchmark Suite. +You can see more information about this resources at the gem5 resources website [here](https://resources.gem5.org/resources/arm-gapbs-bfs-run?version=1.0.0). +In general, you can browse all gem5 resources at the [gem5 resources website](https://resources.gem5.org/). + +Next, set up the simulation: + +```python +simulator = Simulator(board=board) +simulator.run() +``` + +You can now run the simulation using + +```bash +./build/ALL/gem5.opt configs/tutorial/part1/components.py + +``` + +The output should look something like this: + +```txt +gem5 Simulator System. https://www.gem5.org +gem5 is copyrighted software; use the --copyright option for details. + +gem5 version 24.1.0.0 +gem5 compiled Dec 13 2024 14:59:49 +gem5 started Dec 16 2024 16:34:29 +gem5 executing on amarillo, pid 575999 +command line: ./build/ALL/gem5.opt gem5-dev/testing-website-tutorial/tutorial/part1/components.py + +info: Using default config +Global frequency set at 1000000000000 ticks per second +src/base/statistics.hh:279: warn: One of the stats is a legacy stat. Legacy stat is a stat that does not belong to any statistics::Group. Legacy stat is deprecated. +src/base/statistics.hh:279: warn: One of the stats is a legacy stat. Legacy stat is a stat that does not belong to any statistics::Group. Legacy stat is deprecated. +board.remote_gdb: Listening for connections on port 7003 +src/sim/simulate.cc:199: info: Entering event queue @ 0. Starting simulation... +src/mem/ruby/system/Sequencer.cc:704: warn: Replacement policy updates recently became the responsibility of SLICC state machines. Make sure to setMRU() near callbacks in .sm files! +src/sim/syscall_emul.cc:86: warn: ignoring syscall set_robust_list(...) +src/sim/syscall_emul.cc:97: warn: ignoring syscall rseq(...) + (further warnings will be suppressed) +src/sim/mem_state.cc:448: info: Increasing stack size by one page. +src/sim/syscall_emul.hh:1117: warn: readlink() called on '/proc/self/exe' may yield unexpected results in various settings. + Returning '/home/bees/.cache/gem5/arm-gapbs-bfs' +src/arch/arm/insts/pseudo.cc:174: warn: instruction 'bti' unimplemented +src/sim/syscall_emul.cc:86: warn: ignoring syscall mprotect(...) +src/sim/syscall_emul.cc:86: warn: ignoring syscall sched_getaffinity(...) +src/sim/mem_state.cc:448: info: Increasing stack size by one page. +src/sim/mem_state.cc:448: info: Increasing stack size by one page. +Generate Time: 0.00503 +Build Time: 0.00201 +Graph has 1024 nodes and 10496 undirected edges for degree: 10 +Trial Time: 0.00011 +Trial Time: 0.00010 +Trial Time: 0.00010 +Trial Time: 0.00009 +Trial Time: 0.00011 +Trial Time: 0.00010 +Trial Time: 0.00010 +Trial Time: 0.00010 +Trial Time: 0.00010 +Trial Time: 0.00013 +Average Time: 0.00010 + +``` + +gem5 stdlib File Structure +-------------------------- + +The gem5 stdlib is located in `src/python/gem5/`. +Of interest here are the `components` and `prebuilt` folders: + +```txt +gem5/src/python/gem5/components +----/boards +----/cachehierarchies +----/memory +----/processors + +gem5/src/python/gem5/prebuilt +----/demo +----/riscvmatched +``` + +The `components` folder contains components with which you can build systems. The `prebuilt` folder contains various prebuilt systems, including demo systems for the X86, Arm, and RISC-V isas, and riscvmatched, which is a model of SiFive Unmatched. + +```txt +gem5/src/python/gem5/components +----/boards + ----/simple + ----/arm_board + ----/riscv_board + ----/x86_board +----/cachehierarchies +----/memory +----/processors +``` + +Boards are what components plug into. The SimpleBoard has SE mode only, the ArmBoard has FS mode only, and X86Board and RiscvBoard have both FS and SE mode. + +gem5/src/python/gem5/components +----/boards +----/cachehierarchies + ----/chi + ----/classic + ----/ruby +----/memory +----/processors + +Cache hierarchy components have a fixed interface to processors and memory. + +- Ruby: detailed cache coherence and interconnect +- CHI: Arm CHI-based protocol implemented in Ruby +- Classic caches: Hierarchy of crossbars with inflexible coherence + +As of gem5 v24.1, it is possible to use any Ruby cache coherence protocol with the ALL gem5 build. +This is the build included in pre-compiled binaries. + +```txt +gem5/src/python/gem5/components +----/boards +----/cachehierarchies +----/memory + ----/single_channel + ----/multi_channel + ----/dramsim + ----/dramsys + ----/hbm +----/processors +``` + +The memory directory contains pre-configured (LP)DDR3/4/5 DIMMs. Single and multi channel memory systems are available. +There is integration with DRAMSim and DRAMSys, which while not needed for accuracy, is useful for comparisons. +The `hbm` directory is an HBM stack. + +```txt +gem5/src/python/gem5/components +----/boards +----/cachehierarchies +----/memory +----/processors + ----/generators + ----/simple + ----/switchable +``` + +The `processors` directory mostly contains configurable processors to build off of. + +Generators create synthetic traffic, but act like processors. They have linear, random, and more interesting patterns. + +Simple processors only have default parameters and one ISA. + +Switchable processors allow you to change processor types during simulation. + +More on processors +------------------ + +Processors are made up of cores. +Cores have a "BaseCPU" as a member. This is the actual CPU model. +`Processor` is what interfaces with `CacheHierarchy` and `Board` +Processors are organized, structured sets of cores. They define how cores connect with each other and with outside components and the board though standard interface. + +**gem5 has three (or four or five) different processor models** + +They are as follows: + +`CPUTypes.TIMING`: A simple in-order CPU model +This is a "single cycle" CPU. Each instruction takes the time to fetch and executes immediately. +Memory operations take the latency of the memory system. +OK for doing memory-centric studies, but not good for most research. + +`CPUTypes.O3`: An out-of-order CPU model +Highly detailed model based on the Alpha 21264. +Has ROB, physical registers, LSQ, etc. +Don't use SimpleProcessor if you want to configure this. + +`CPUTypes.MINOR`: An in-order core model +A high-performance in-order core model. +Configurable four-stage pipeline +Don't use SimpleProcessor if you want to configure this. + +`CPUTypes.ATOMIC`: Used in "atomic" mode (more later) +`CPUTypes.KVM`: This is covered in detail in the [2024 gem5 bootcamp](https://bootcamp.gem5.org/#02-Using-gem5/08-accelerating-simulation). + + +FS vs SE mode +------------- + +SE mode relays application syscalls to the host OS. This means we don't need to simulate an OS for applications to run. + +In addition, we can access host resources such as files of libraries to dynamically link in. + +Don't treat SE mode as "FS but faster": You must understand what you're simulating and whether it will impact results. +Not all syscalls will ever be implemented: We'd love to have all the syscalls implemented but Linux changes rapidly. We try to cover common use-cases but we can't cover everything. If a Syscall is missing, you can implement it, ignore it, or use FS mode. +Binaries with elevated privileges do not work in SE mode: If you're running a binary that requires elevated privileges, you'll need to run it in FS mode. + +FS mode does everything SE mode does (and more!) but can take longer to get to the region of interest. You have to wait for the OS to boot each time (unless you accelerate the simulation). + +However, as SE mode doesn't simulate the OS, you risk missing important events triggered via syscalls, I/O, or the operating system, which may mean your simulated system doesn't properly reflect the real system. + +Think through what SE mode is doing and if it's right for your use-case. If in doubt, use FS mode. It's (generally) not worth the risk using SE mode if you're not sure. + +Full Boot Example +----------------- + +For an example of a configuration file that runs the entire boot of Ubuntu 24.04 on an X86 system, see [the gem5 stdlib documentation](../../gem5-stdlib/2-tutorial-x86-fs.md). Of note is that we need to define an exit event handler in order to get through the entire boot: + +```python +def exit_event_handler(): + print("First exit: kernel booted") + yield False # gem5 is now executing systemd startup + print("Second exit: Started `after_boot.sh` script") + # The after_boot.sh script is executed after the kernel and systemd have + # booted. + # Here we switch the CPU type to Timing. + print("Switching to Timing CPU") + processor.switch() + yield False # gem5 is now executing the `after_boot.sh` script + print("Third exit: Finished `after_boot.sh` script") + # The after_boot.sh script will run a script if it is passed via + # m5 readfile. This is the last exit event before the simulation exits. + yield True + +simulator = Simulator( + board=board, + on_exit_event={ + ExitEvent.EXIT: exit_event_handler(), + }, +) +``` + +At the first exit event, the generator yields False to continue the simulation. At the second exit event, the generator switches the CPUs, then yields False again. At the third exit event, it yields `True` to end the simulation. + +There are various types of exit events. The Simulator has default behavior for these events, but they can be overridden. + +```python +ExitEvent.EXIT +ExitEvent.CHECKPOINT +ExitEvent.FAIL +ExitEvent.SWITCHCPU +ExitEvent.WORKBEGIN +ExitEvent.WORKEND +ExitEvent.USER_INTERRUPT +ExitEvent.MAX_TICK +``` + +Key idea: The Simulator object controls simulation +-------------------------------------------------- + +To place our idea of gem5: + +models (or SimObjects) are the fine-grained objects that are connected together in Python scripts to form a simulation. +components are the coarse-grained objects that are connected defined as a set of configured models in Python scripts to form and delivered as part of the Standard Library +The standard library allows users to specify a board and specify the properties of the board by specify the components that are connected to it. +The Simulator takes a board and launches the simulation and gives an API which allows for control of the simulation: specifying the simulation stopping and restarting condition, replacing components "on the fly", defining when the simulation should stop and start, etc. +See [src/python/gem5/simulate/simulator.py](https://github.com/gem5/gem5/blob/stable/src/python/gem5/simulate/simulator.py) for the Simulator source. + +Simulator parameters are as follows: + +board: The Board to simulate (required) +full_system: Whether to simulate a full system (default: False, can be inferred from the board, not needed specified in most cases) +on_exit_event: A complex data structure that allows you to control the simulation. The simulator exits for many reasons, this allows you to customize what happens. We just saw an example. +checkpoint_path: If we're restoring from a checkpoint, this is the path to the checkpoint. More on checkpoints later. +id: An optional name for this simulation. Used in multisim. More on this in the future. + +Some useful functions are below: + +run(): Run the simulation +get/set_max_ticks(max_tick): Set the absolute tick to stop simulation. Generates a MAX_TICK exit event that can be handled. +schedule_max_insts(inst_number): Set the number of instructions to run before stopping. Generates a MAX_INSTS exit event that can be handled. Note that if running multiple cores, this happens if any core reaches this number of instructions. +get_stats(): Get the statistics from the simulation. Returns a dictionary of statistics. + +See [src/python/gem5/simulate/simulator.py](https://github.com/gem5/gem5/blob/stable/src/python/gem5/simulate/simulator.py) for more details. + +Creating new standard library components +----------------------------------------- + +The gem5 standard library is designed around extension and encapsulation, not parametarization. +If you want to create a component with different parameters, extend using object-oriented semantics. + +We will now create a new component. We will specialize/extend the "BaseCPUProcessor" to create an ARM processor with a singular out-of-order core. + +First, let's add our imports: + +```python +from gem5.components.boards.simple_board import SimpleBoard +from gem5.components.cachehierarchies.ruby.mesi_two_level_cache_hierarchy import ( + MESITwoLevelCacheHierarchy, +) +from gem5.components.memory.single_channel import SingleChannelDDR4_2400 +from gem5.resources.resource import obtain_resource +from gem5.simulate.simulator import Simulator +from gem5.isas import ISA + +from gem5.components.processors.base_cpu_core import BaseCPUCore +from gem5.components.processors.base_cpu_processor import BaseCPUProcessor + +from m5.objects import ArmO3CPU +from m5.objects import TournamentBP +``` + +Next, let's make a new subclass to specialize the core's parameters: + +```python +class MyOutOfOrderCore(BaseCPUCore): + def __init__(self, width, rob_size, num_int_regs, num_fp_regs): + super().__init__(ArmO3CPU(), ISA.ARM) + self.core.fetchWidth = width + self.core.decodeWidth = width + self.core.renameWidth = width + self.core.issueWidth = width + self.core.wbWidth = width + self.core.commitWidth = width + + self.core.numROBEntries = rob_size + + self.core.numPhysIntRegs = num_int_regs + self.core.numPhysFloatRegs = num_fp_regs + + self.core.branchPred = TournamentBP() + + self.core.LQEntries = 128 + self.core.SQEntries = 128 +``` + +Next, let's make a processor using this core. The `BaseCPUProcessor` assumes a list of cores that are `BaseCPUCores`. We'll just make one core and pass the parameters to it: + +```python +class MyOutOfOrderProcessor(BaseCPUProcessor): + def __init__(self, width, rob_size, num_int_regs, num_fp_regs): + cores = [MyOutOfOrderCore(width, rob_size, num_int_regs, num_fp_regs)] + super().__init__(cores) +``` + +Next, let's use these components to set up a processor for the simulation: + +```python +my_ooo_processor = MyOutOfOrderProcessor( + width=8, rob_size=192, num_int_regs=256, num_fp_regs=256 +) +``` + +Finally, let's set up the rest of the simulation: + +```python +main_memory = SingleChannelDDR4_2400(size="2GB") + +cache_hierarchy = MESITwoLevelCacheHierarchy( + l1d_size="16kB", + l1d_assoc=8, + l1i_size="16kB", + l1i_assoc=8, + l2_size="256kB", + l2_assoc=16, + num_l2_banks=1, +) +board = SimpleBoard( + processor=my_ooo_processor, + memory=main_memory, + cache_hierarchy=cache_hierarchy, + clk_freq="3GHz", +) + +board.set_workload(obtain_resource("arm-gapbs-bfs-run")) + +simulator = Simulator(board) +simulator.run() +``` + +You can now run this simulation with the following command, assuming that your configuration script is named `config.py`: + +```bash +./build/ALL/gem5.opt config.py +``` + +If you have a pre-built binary, you can simply use the following command: + +```bash +gem5 config.py +``` + +gem5 v21.0: Adding cache to the configuration script +==================================================== + +Using the [previous configuration script as a starting point](http://www.gem5.org/documentation/learning_gem5/part1/simple_config/), +this chapter will walk through a more complex configuration. We will add +a cache hierarchy to the system as shown in +the figure below. Additionally, this chapter +will cover understanding the gem5 statistics output and adding command +line parameters to your scripts. + +![A system configuration with a two-level cache +hierarchy.](/pages/static/figures/advanced_config.png) + +Creating cache objects +---------------------- + +We are going to use the classic caches, instead of ruby-intro-chapter, +since we are modeling a single CPU system and we don't care about +modeling cache coherence. We will extend the Cache SimObject and +configure it for our system. First, we must understand the parameters +that are used to configure Cache objects. + +> **Classic caches and Ruby** +> +> gem5 currently has two completely distinct subsystems to model the +> on-chip caches in a system, the "Classic caches" and "Ruby". The +> historical reason for this is that gem5 is a combination of m5 from +> Michigan and GEMS from Wisconsin. GEMS used Ruby as its cache model, +> whereas the classic caches came from the m5 codebase (hence +> "classic"). The difference between these two models is that Ruby is +> designed to model cache coherence in detail. Part of Ruby is SLICC, a +> language for defining cache coherence protocols. On the other hand, +> the classic caches implement a simplified and inflexible MOESI +> coherence protocol. +> +> To choose which model to use, you should ask yourself what you are +> trying to model. If you are modeling changes to the cache coherence +> protocol or the coherence protocol could have a first-order impact on +> your results, use Ruby. Otherwise, if the coherence protocol isn't +> important to you, use the classic caches. +> +> A long-term goal of gem5 is to unify these two cache models into a +> single holistic model. + +### Cache + +The Cache SimObject declaration can be found in src/mem/cache/Cache.py. +This Python file defines the parameters which you can set of the +SimObject. Under the hood, when the SimObject is instantiated these +parameters are passed to the C++ implementation of the object. The +`Cache` SimObject inherits from the `BaseCache` object shown below. + +Within the `BaseCache` class, there are a number of *parameters*. For +instance, `assoc` is an integer parameter. Some parameters, like +`write_buffers` have a default value, 8 in this case. The default +parameter is the first argument to `Param.*`, unless the first argument +is a string. The string argument of each of the parameters is a +description of what the parameter is (e.g., +`tag_latency = Param.Cycles("Tag lookup latency")` means that the +`` tag_latency `` controls "The hit latency for this cache"). + +Many of these parameters do not have defaults, so we are required to set +these parameters before calling `m5.instantiate()`. + +* * * * * + +Now, to create caches with specific parameters, we are first going to +create a new file, `caches.py`, in the same directory as simple.py, +`configs/tutorial/part1`. The first step is to import the SimObject(s) +we are going to extend in this file. + +``` +from m5.objects import Cache +``` + +Next, we can treat the BaseCache object just like any other Python class +and extend it. We can name the new cache anything we want. Let's start +by making an L1 cache. + +``` +class L1Cache(Cache): + assoc = 2 + tag_latency = 2 + data_latency = 2 + response_latency = 2 + mshrs = 4 + tgts_per_mshr = 20 +``` + +Here, we are setting some of the parameters of the BaseCache that do not +have default values. To see all of the possible configuration options, +and to find which are required and which are optional, you have to look +at the source code of the SimObject. In this case, we are using +BaseCache. + +We have extended `BaseCache` and set most of the parameters that do not +have default values in the `BaseCache` SimObject. Next, let's two more +sub-classes of L1Cache, an L1DCache and L1ICache + +``` +class L1ICache(L1Cache): + size = '16kB' + +class L1DCache(L1Cache): + size = '64kB' +``` + +Let's also create an L2 cache with some reasonable parameters. + +``` +class L2Cache(Cache): + size = '256kB' + assoc = 8 + tag_latency = 20 + data_latency = 20 + response_latency = 20 + mshrs = 20 + tgts_per_mshr = 12 +``` + +Now that we have specified all of the necessary parameters required for +`BaseCache`, all we have to do is instantiate our sub-classes and +connect the caches to the interconnect. However, connecting lots of +objects up to complex interconnects can make configuration files quickly +grow and become unreadable. Therefore, let's first add some helper +functions to our sub-classes of `Cache`. Remember, these are just Python +classes, so we can do anything with them that you can do with a Python +class. + +To the L1 cache let's add two functions, `connectCPU` to connect a CPU +to the cache and `connectBus` to connect the cache to a bus. We need to +add the following code to the `L1Cache` class. + +``` +def connectCPU(self, cpu): + # need to define this in a base class! + raise NotImplementedError + +def connectBus(self, bus): + self.mem_side = bus.cpu_side_ports +``` + +Next, we have to define a separate `connectCPU` function for the +instruction and data caches, since the I-cache and D-cache ports have a +different names. Our `L1ICache` and `L1DCache` classes now become: + +``` +class L1ICache(L1Cache): + size = '16kB' + + def connectCPU(self, cpu): + self.cpu_side = cpu.icache_port + +class L1DCache(L1Cache): + size = '64kB' + + def connectCPU(self, cpu): + self.cpu_side = cpu.dcache_port +``` + +Finally, let's add functions to the `L2Cache` to connect to the +memory-side and CPU-side bus, respectively. + +``` +def connectCPUSideBus(self, bus): + self.cpu_side = bus.mem_side_ports + +def connectMemSideBus(self, bus): + self.mem_side = bus.cpu_side_ports +``` + +The full file can be found in the gem5 source at +[`configs/learning_gem5/part1/caches.py`](https://github.com/gem5/gem5/blob/stable/configs/learning_gem5/part1/caches.py). + +Adding caches to the simple config file +------------------------------------ + +Now, let's add the caches we just created to the configuration script we +created in the [last chapter](http://www.gem5.org/documentation/learning_gem5/part1/simple_config/). + +First, let's copy the script to a new name. + +``` +cp ./configs/tutorial/part1/simple.py ./configs/tutorial/part1/two_level.py +``` + +First, we need to import the names from the `caches.py` file into the +namespace. We can add the following to the top of the file (after the +m5.objects import), as you would with any Python source. + +``` +from caches import * +``` + +Now, after creating the CPU, let's create the L1 caches: + +``` +system.cpu.icache = L1ICache() +system.cpu.dcache = L1DCache() +``` + +And connect the caches to the CPU ports with the helper function we +created. + +``` +system.cpu.icache.connectCPU(system.cpu) +system.cpu.dcache.connectCPU(system.cpu) +``` + +You need to *remove* the following two lines which connected the cache +ports directly to the memory bus. + +``` +system.cpu.icache_port = system.membus.cpu_side_ports +system.cpu.dcache_port = system.membus.cpu_side_ports +``` + +We can't directly connect the L1 caches to the L2 cache since the L2 +cache only expects a single port to connect to it. Therefore, we need to +create an L2 bus to connect our L1 caches to the L2 cache. The, we can +use our helper function to connect the L1 caches to the L2 bus. + +``` +system.l2bus = L2XBar() + +system.cpu.icache.connectBus(system.l2bus) +system.cpu.dcache.connectBus(system.l2bus) +``` + +Next, we can create our L2 cache and connect it to the L2 bus and the +memory bus. + +``` +system.l2cache = L2Cache() +system.l2cache.connectCPUSideBus(system.l2bus) +system.membus = SystemXBar() +system.l2cache.connectMemSideBus(system.membus) +``` + +Note that `system.membus = SystemXBar()` has been defined before +`system.l2cache.connectMemSideBus` so we can pass it to +`system.l2cache.connectMemSideBus`. Everything else in the file +stays the same! Now we have a complete configuration with a +two-level cache hierarchy. If you run the current file, `hello` +should now finish in 57467000 ticks. The full script can +be found in the gem5 source at +[`configs/learning_gem5/part1/two_level.py`](https://github.com/gem5/gem5/blob/stable/configs/learning_gem5/part1/two_level.py). + +Adding parameters to your script +-------------------------------- + +When performing experiments with gem5, you don't want to edit your +configuration script every time you want to test the system with +different parameters. To get around this, you can add command-line +parameters to your gem5 configuration script. Again, because the +configuration script is just Python, you can use the Python libraries +that support argument parsing. Although pyoptparse is officially +deprecated, many of the configuration scripts that ship with gem5 use it +instead of pyargparse since gem5's minimum Python version used to be +2.5. The minimum Python version is now 3.6, so Python's argparse is a better +option when writing new scripts that don't need to interact with the +current gem5 scripts. To get started using :pyoptparse, you can consult +the online Python documentation. + +To add options to our two-level cache configuration, after importing our +caches, let's add some options. + +``` +import argparse + +parser = argparse.ArgumentParser(description='A simple system with 2-level cache.') +parser.add_argument("binary", default="", nargs="?", type=str, + help="Path to the binary to execute.") +parser.add_argument("--l1i_size", + help=f"L1 instruction cache size. Default: 16kB.") +parser.add_argument("--l1d_size", + help="L1 data cache size. Default: Default: 64kB.") +parser.add_argument("--l2_size", + help="L2 cache size. Default: 256kB.") + +options = parser.parse_args() +``` +Note that if you wanted to pass the binary file's path the way shown above +and use it through options, you should specify it as `options.binary`. +For example: + +``` +system.workload = SEWorkload.init_compatible(options.binary) +``` + +Now, you can run +`build/ALL/gem5.opt configs/tutorial/part1/two_level.py --help` which +will display the options you just added. + +Next, we need to pass these options onto the caches that we create in +the configuration script. To do this, we'll simply change two\_level\_opts.py +to pass the options into the caches as a parameter to their constructor +and add an appropriate constructor, next. + +``` +system.cpu.icache = L1ICache(options) +system.cpu.dcache = L1DCache(options) +... +system.l2cache = L2Cache(options) +``` + +In caches.py, we need to add constructors (`__init__` functions in +Python) to each of our classes. Starting with our base L1 cache, we'll +just add an empty constructor since we don't have any parameters which +apply to the base L1 cache. However, we can't forget to call the super +class's constructor in this case. If the call to the super class +constructor is skipped, gem5's SimObject attribute finding function will +fail and the result will be +"`RuntimeError: maximum recursion depth exceeded`" when you try to +instantiate the cache object. So, in `L1Cache` we need to add the +following after the static class members. + +``` +def __init__(self, options=None): + super(L1Cache, self).__init__() + pass +``` + +Next, in the `L1ICache`, we need to use the option that we created +(`l1i_size`) to set the size. In the following code, there is guards for +if `options` is not passed to the `L1ICache` constructor and if no +option was specified on the command line. In these cases, we'll just use +the default we've already specified for the size. + +``` +def __init__(self, options=None): + super(L1ICache, self).__init__(options) + if not options or not options.l1i_size: + return + self.size = options.l1i_size +``` + +We can use the same code for the `L1DCache`: + +``` +def __init__(self, options=None): + super(L1DCache, self).__init__(options) + if not options or not options.l1d_size: + return + self.size = options.l1d_size +``` + +And the unified `L2Cache`: + +``` +def __init__(self, options=None): + super(L2Cache, self).__init__() + if not options or not options.l2_size: + return + self.size = options.l2_size +``` + +With these changes, you can now pass the cache sizes into your script +from the command line like below. + +``` +build/ALL/gem5.opt configs/tutorial/part1/two_level.py --l2_size='1MB' --l1d_size='128kB' +``` + + gem5 Simulator System. http://gem5.org + gem5 is copyrighted software; use the --copyright option for details. + + gem5 version 21.0.0.0 + gem5 compiled May 17 2021 18:05:59 + gem5 started May 18 2021 00:00:33 + gem5 executing on amarillo, pid 83118 + command line: build/X86/gem5.opt configs/tutorial/part1/two_level.py --l2_size=1MB --l1d_size=128kB + + Global frequency set at 1000000000000 ticks per second + warn: No dot file generated. Please install pydot to generate the dot file and pdf. + warn: DRAM device capacity (8192 Mbytes) does not match the address range assigned (512 Mbytes) + 0: system.remote_gdb: listening for remote gdb on port 7005 + Beginning simulation! + info: Entering event queue @ 0. Starting simulation... + Hello world! + Exiting @ tick 57467000 because exiting with last active thread context + +The full scripts can be found in the gem5 source at +[`configs/learning_gem5/part1/caches.py`](https://github.com/gem5/gem5/blob/stable/configs/learning_gem5/part1/caches.py) and +[`configs/learning_gem5/part1/two_level.py`](https://github.com/gem5/gem5/blob/stable/configs/learning_gem5/part1/two_level.py). diff --git a/_pages/documentation/learning_gem5/part1/part1_5_gem5_example_configs.md b/_pages/documentation/learning_gem5/part1/part1_5_gem5_example_configs.md index 3f42b81e30..eb1d0c503c 100644 --- a/_pages/documentation/learning_gem5/part1/part1_5_gem5_example_configs.md +++ b/_pages/documentation/learning_gem5/part1/part1_5_gem5_example_configs.md @@ -7,8 +7,42 @@ permalink: /documentation/learning_gem5/part1/example_configs/ author: Jason Lowe-Power --- +gem5 v24.1: Using the gem5 standard library configuration scripts +================================================================= + +The introduction of the gem5 standard library has changed the way +that gem5 configuration scripts are written. Many of the older +configuration scripts mentioned in the gem5 v21.0 section below are +now deprecated in favor of configuration scripts for the gem5 standard +library, located at `configs/example/gem5_library`. + +A brief look at the directory structure is as follows: + +```txt +gem5_library + | + |- caches #contains a configuration script for the octopi cache + | + |- checkpoints #scripts for taking and restoring from checkpoints + | + |- dramsys #scripts for using gem5 with dramsys + | + |- looppoints #scripts for taking and restoring from looppoints + | + |- multisim #scripts for launching multiple simulations at once using multisim + | + |- spatter_gen #scripts for SpatterGen + | + |- (various example configuration scripts not sorted into a subdirectory) -Using the default configuration scripts +``` + +The example configuration scripts placed directly in the gem5_library directory +are similar to what you've seen in previous parts of Learning gem5, but with more +variety, e.g. different ISAs, boards, and workloads. The source for these scripts +can be viewed [here](https://github.com/gem5/gem5/tree/stable/configs/example/gem5_library). + +gem5 v21.0: Using the default configuration scripts ======================================= In this chapter, we'll explore using the default configuration scripts diff --git a/_pages/documentation/learning_gem5/part2/part2_1_helloobject.md b/_pages/documentation/learning_gem5/part2/part2_1_helloobject.md index 310d67f4a0..f8466cdfc4 100644 --- a/_pages/documentation/learning_gem5/part2/part2_1_helloobject.md +++ b/_pages/documentation/learning_gem5/part2/part2_1_helloobject.md @@ -234,7 +234,7 @@ The below example assumes you are using the x86 ISA, but nothing in our object requires an ISA so, this will work with any of gem5's ISAs. ``` -scons build/X86/gem5.opt +scons build/ALL/gem5.opt ``` Step 5: Create the config scripts to use your new SimObject diff --git a/_pages/documentation/learning_gem5/part2/part2_2_debugging.md b/_pages/documentation/learning_gem5/part2/part2_2_debugging.md index 6542a469ef..86748a5865 100644 --- a/_pages/documentation/learning_gem5/part2/part2_2_debugging.md +++ b/_pages/documentation/learning_gem5/part2/part2_2_debugging.md @@ -30,7 +30,7 @@ following output. Note that this generates *a lot* of output to the console (about 7 MB). ``` - build/X86/gem5.opt --debug-flags=DRAM configs/learning_gem5/part1/simple.py | head -n 50 + build/ALL/gem5.opt --debug-flags=DRAM configs/learning_gem5/part1/simple.py | head -n 50 ``` gem5 Simulator System. http://gem5.org @@ -91,7 +91,7 @@ flags shows details of how each instruction is executed by the simulated CPU. ``` - build/X86/gem5.opt --debug-flags=Exec configs/learning_gem5/part1/simple.py | head -n 50 + build/ALL/gem5.opt --debug-flags=Exec configs/learning_gem5/part1/simple.py | head -n 50 ``` gem5 Simulator System. http://gem5.org @@ -152,7 +152,7 @@ flags. You can see this, and all of the available debug flags, by running gem5 with the `--debug-help` parameter. ``` - build/X86/gem5.opt --debug-help + build/ALL/gem5.opt --debug-help ``` Base Flags: @@ -239,8 +239,8 @@ Now, if you recompile gem5 and run it with the "HelloExample" debug flag, you get the following result. ``` -scons build/X86/gem5.opt -build/X86/gem5.opt --debug-flags=HelloExample configs/learning_gem5/part2/run_hello.py +scons build/ALL/gem5.opt +build/ALL/gem5.opt --debug-flags=HelloExample configs/learning_gem5/part2/run_hello.py ``` gem5 Simulator System. http://gem5.org diff --git a/_pages/documentation/reporting_problems.md b/_pages/documentation/reporting_problems.md index f9981415eb..7ae036ffa7 100644 --- a/_pages/documentation/reporting_problems.md +++ b/_pages/documentation/reporting_problems.md @@ -28,6 +28,8 @@ reporting an issue: 2. Ensure you're compiling and running the latest version of [gem5]( https://github.com/gem5/gem5). The issue may have already been resolved. +Also check the `develop` version of gem5, as it will have bug fixes that +haven't been incorporated into `stable` yet. 3. Check changes [currently under review on our GitHub system]( https://github.com/gem5/gem5/pulls/). It's possible a fix to diff --git a/_pages/getting_started.md b/_pages/getting_started.md index ebf628cb5a..da6f04ebb9 100644 --- a/_pages/getting_started.md +++ b/_pages/getting_started.md @@ -30,7 +30,7 @@ The [building gem5](/documentation/general_docs/building) provides more details ``` cd gem5 -scons build/X86/gem5.opt -j +scons build/ALL/gem5.opt -j ``` Now that you have a gem5 binary, you can run your first simulation! @@ -40,7 +40,7 @@ In this example, the script creates a *very* simple system and executes a "hello More information about the script can be found in the [Simple Config chapter](/documentation/learning_gem5/part1/simple_config) of the [Learning gem5](/documentation/learning_gem5/introduction) book. ``` -build/X86/gem5.opt configs/learning_gem5/part1/simple.py +build/ALL/gem5.opt configs/learning_gem5/part1/simple.py ``` After running this command, you'll see gem5's output as well as `Hello world`, which comes from the hello world binary! diff --git a/_pages/join-slack.md b/_pages/join-slack.md index bde97c8d37..f1db9ff3e9 100644 --- a/_pages/join-slack.md +++ b/_pages/join-slack.md @@ -6,7 +6,7 @@ permalink: /join-slack/ - +

You will be redirected to the gem5 Slack invite soon!

diff --git a/_pages/publications.md b/_pages/publications.md index 55a20a6399..65cae5892b 100644 --- a/_pages/publications.md +++ b/_pages/publications.md @@ -18,7 +18,7 @@ tabs: * [**The gem5 Simulator**](https://dl.acm.org/doi/10.1145/2024716.2024718). Nathan Binkert, Bradford Beckmann, Gabriel Black, Steven K. Reinhardt, Ali Saidi, Arkaprava Basu, Joel Hestness, Derek R. Hower, Tushar Krishna, Somayeh Sardashti, Rathijit Sen, Korey Sewell, Muhammad Shoaib, Nilay Vaish, Mark D. Hill, and David A. Wood. ACM SIGARCH Computer Architecture News, May 2011. [ doi: [10.1145/2024716.2024718](https://dl.acm.org/doi/10.1145/2024716.2024718) ] [ [pdf](https://dl.acm.org/doi/pdf/10.1145/2024716.2024718) ] - +# Are there any newer papers that should be added to this page? - name: Special Features of gem5 id: special-features content: |