Changes for ISCA tutorial

.devcontainer/devcontainer.json

@@ -1,10 +1,10 @@
 {
     "name": "gem5 Development Container",
-    "image": "ghcr.io/gem5/devcontainer:latest",
+    "image": "ghcr.io/gem5/devcontainer:isca2024",
     "hostRequirements": {
-        "cpus": 2,
-        "memory": "16gb",
-        "storage": "32gb"
+        "cpus": 1,
+        "memory": "8gb",
+        "storage": "64gb"
      },
     "customizations": {
         "vscode": {
@@ -20,7 +20,8 @@
                 "ms-vscode.cpptools-extension-pack",
                 "ms-vscode.cpptools-themes",
                 "ms-vscode.makefile-tools",
-                "Tsinghua-Hexin-Joint-Institute.gem5-slicc"
+                "Tsinghua-Hexin-Joint-Institute.gem5-slicc",
+                "ms-python.black-formatter"
             ]
         }
     },
@@ -30,5 +31,6 @@
         "ghcr.io/devcontainers-contrib/features/actionlint:1": {},
         "ghcr.io/devcontainers-contrib/features/vscode-cli:1": {}
     },
-    "onCreateCommand": "./.devcontainer/on_create.sh"
-}
+    "onCreateCommand": "./.devcontainer/on_create.sh",
+    "postStartCommand": "./.devcontainer/post_start.sh"
+}

.devcontainer/on_create.sh

@@ -15,4 +15,18 @@ git config --global pull.rebase true
 
 ./util/pre-commit-install.sh
 
-popd # gem5
+popd # gem5
+
+# Pre-download the resources we use
+
+gem5 pre-download-resources.py
+
+docker pull ghcr.io/gem5/gcn-gpu:v24-0
+
+wget http://dist.gem5.org/dist/v24-0/test-progs/square/square
+
+wget https://storage.googleapis.com/dist.gem5.org/dist/v24-0/gpu-fs/kernel/vmlinux-gpu-ml-isca
+
+# Note: this unzips to 55 GB so must in on /tmp.
+# See post_start.sh where it is unzipped each time the devcontainer starts
+wget https://storage.googleapis.com/dist.gem5.org/dist/v24-0/gpu-fs/diskimage/x86-ubuntu-gpu-ml-isca.gz

.devcontainer/post_start.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+if [ ! -f /tmp/x86-ubuntu-gpu-ml-isca ]; then
+  cp x86-ubuntu-gpu-ml-isca.gz /tmp
+  gunzip /tmp/x86-ubuntu-gpu-ml-isca.gz
+fi
+
+ln -s /tmp/x86-ubuntu-gpu-ml-isca .

.gitignore

@@ -1,5 +1,6 @@
 # Ignore all m5out directories and build directories
 **/m5out/
+**/checkpoint/
 
 # Jekyll stuff
 _site/
@@ -12,3 +13,9 @@ typings/
 .vscode/*.log
 
 __pycache__
+
+# Ignore downloaded files
+square
+vmlinux-gpu-ml-isca
+x86-ubuntu-gpu-ml-isca
+x86-ubuntu-gpu-ml-isca.gz

.vscode/settings.json

@@ -1,12 +1,8 @@
 {
-    "python.formatting.provider": "black",
-    "python.analysis.stubPath": "typings",
     "python.analysis.extraPaths": ["gem5/src/python"],
-    "python.formatting.blackArgs": [
-        "--line-length",
-        "79"
-    ],
     "editor.rulers": [
         79
-    ]
+    ],
+    "files.trimTrailingWhitespace": true,
+    "files.insertFinalNewline": true
 }

README.md

@@ -7,35 +7,37 @@ It has been built with the assumption users will utilize [Codespaces](https://gi
 The repository contains the following directories:
 
 * [docker](docker) :
-The source code for the Docker image used by [.devcontainer/Dockerfile](.devcontainer/Dockerfile) to create the Codespace Docker container.
+The source code for the Docker image used by the [Dockerfile](gem5/util/dockerfiles/devcontainer/Dockerfile) to create the Codespace Docker container.
 * gem5 :
-v22.0.0.1 of gem5.
+v24.0.0.0 of gem5.
 * gem5-resources :
-gem5-resources which may be used with v22.0 of gem5.
+gem5-resources which may be used with v24.0 of gem5.
 * materials: Example materials used as part of the tutorial.
-* modules: Source for the accompying website: https://gem5bootcamp.github.io/gem5-bootcamp-env
+* modules: Source for the accompanying website: <https://gem5bootcamp.github.io/gem5-bootcamp-env> (This link is not up to date.)
 The website contains links to slides, presentation videos, and notes for the tutorials.
 
 **Note:** 'gem5' and 'gem5-resources' are submodules though the [.devcontainer/devcontainer.json](.devcontainer/devcontainer.json) file specifies that a `git submodule update --init --recursive` command is executed when the Codespace Docker container is created.
 
-The container used by Codespaces is built from [.devcontainer/Dockerfile](.devcontainer/Dockerfile).
+The container used by Codespaces is built from [Dockerfile](gem5/util/dockerfiles/devcontainer/Dockerfile).
 It contains:
 
 * All gem5 dependencies (inc. optional dependencies).
 * Prebuilt gem5 binaries:
-  * `/usr/local/bin/gem5-x86`
-  * `/usr/local/bin/gem5-arm`
-  * `/usr/local/bin/gem5-riscv`
+  * `/usr/local/bin/gem5` (gem5 ALL ISAs with CHI protocol)
+  * `/usr/local/bin/gem5-default` (default gem5 ALL build with MESI_Two_Level)
+  * `/usr/local/bin/gem5-vega` (x86-only with GPU protocol)
+  * `/usr/local/bin/gem5-vega-se` (same as above, but compiled with 20.04)
 * A RISCV64 and an AARCH64 GNU cross-compiler:
   * RISCV64 GNU cross-compiler found in `/opt/cross-compiler/riscv64-linux/`.
   * AARCH64 GNU cross-compiler found in `/opt/cross-compiler/aarch64-linux/`.
+* ROCm development environment 6.1.2 (note, this is why the container is based on 22.04 instead of 24.04)
 
 ## Beginners' example
 
 The following can be used within the Codespace container to run a basic gem5 simulation straight away:
 
 ```
-gem5-arm gem5/configs/example/gem5_library/arm-hello.py
+gem5 gem5/configs/example/gem5_library/arm-hello.py
 ```
 
 This will execute a "Hello world!" program inside a simulated ARM system.
@@ -44,12 +46,13 @@ This will execute a "Hello world!" program inside a simulated ARM system.
 
 In this project we have two submodules: 'gem5' and 'gem5-resources'.
 These are automatically obtained when the codespaces is initialized.
-At the time of writing the 'gem5' directory is checked out to the stable branch at v22.0.0.1.
-The 'gem5-resources' repository is checkoued out to revision '871e715', which should contain resources with known compatibility with gem5 v22.0.
+At the time of writing the 'gem5' directory is checked out to the stable branch at v24.0.0.0.
+The 'gem5-resources' repository is checked out to revision '97532302', which should contain resources with known compatibility with gem5 v24.0.
 
-To update the git submodules to be in-sync with their remote origins (that hosted on our [googlesource](https://gem5.googlesource.com)), execute the following command:
+To update the git submodules to be in-sync with their remote origins (that hosted on our [GitHub](https://github.com/gem5/gem5)), execute the following command:
 
 ```sh
+git submodule sync   # Only needed if submodule remotes changed
 git submodule update --remote
 ```
 
@@ -61,7 +64,7 @@ git commit -m "git submodules updated"
 git push
 ```
 
-## Best practises
+## Best practices
 
 ### Using branches
 
@@ -116,3 +119,12 @@ To see a list of all available branches you can execute:
 ```sh
 git branch
 ```
+
+## Note on running GPU SE
+
+You can use docker.
+Below is an example command
+
+```sh
+docker run -v $PWD:$PWD -v /usr/local/bin:/usr/local/bin -w $PWD ghcr.io/gem5/gcn-gpu:v24-0 gem5-vega-se gem5/configs/example/apu_se.py -n 3 -c square
+```

materials/isca24/01-basic.py

@@ -0,0 +1,10 @@
+"""
+This will start Linux boot on X86DemoBoard and run for 20 billion cycles.
+Used as a very simple example.
+
+run with `gem5-mesi 01-basic.py`
+"""
+
+from gem5.prebuilt.demo.x86_demo_board import X86DemoBoard
+from gem5.resources.resource import obtain_resource
+from gem5.simulate.simulator import Simulator

materials/isca24/02-components.py

@@ -0,0 +1,21 @@
+"""
+This will build a classic caches based system to run a simple x86 SE workload.
+IS takes about 40 seconds.
+
+Run with `gem5 02-components.py`
+"""
+
+from gem5.components.boards.simple_board import SimpleBoard
+from gem5.components.cachehierarchies.classic.private_l1_shared_l2_cache_hierarchy import (
+    PrivateL1SharedL2CacheHierarchy,
+)
+from gem5.components.memory.single_channel import SingleChannelDDR4_2400
+
+from gem5.components.processors.cpu_types import CPUTypes
+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
+

materials/isca24/03-processor.py

@@ -0,0 +1,65 @@
+"""
+Script with a specialized O3 CPU
+IS takes about 2-3 minutes with this script
+
+Run with `gem5 03-processor.py`
+"""
+
+from gem5.components.boards.simple_board import SimpleBoard
+from gem5.components.cachehierarchies.classic.private_l1_shared_l2_cache_hierarchy import (
+    PrivateL1SharedL2CacheHierarchy,
+)
+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 X86O3CPU
+from m5.objects import TournamentBP
+
+class MyOutOfOrderCore(BaseCPUCore):
+    def __init__(self, width, rob_size, num_int_regs, num_fp_regs):
+        pass
+
+class MyOutOfOrderProcessor(BaseCPUProcessor):
+    def __init__(self, width, rob_size, num_int_regs, num_fp_regs):
+        """
+        :param width: sets the width of fetch, decode, raname, issue, wb, and
+        commit stages.
+        :param rob_size: determine the number of entries in the reorder buffer.
+        :param num_int_regs: determines the size of the integer register file.
+        :param num_int_regs: determines the size of the vector/floating point
+        register file.
+        """
+        pass
+
+
+main_memory = SingleChannelDDR4_2400(size="2GB")
+
+caches = PrivateL1SharedL2CacheHierarchy(
+    l1d_size="32KiB",
+    l1d_assoc=8,
+    l1i_size="32KiB",
+    l1i_assoc=8,
+    l2_size="256KiB",
+    l2_assoc=16,
+)
+
+my_ooo_processor = MyOutOfOrderProcessor(
+    width=8, rob_size=192, num_int_regs=256, num_fp_regs=256
+)
+
+board = SimpleBoard(
+    processor=my_ooo_processor,
+    memory=main_memory,
+    cache_hierarchy=caches,
+    clk_freq="3GHz",
+)
+
+board.set_workload(obtain_resource("x86-npb-is-size-s-run"))
+
+simulator = Simulator(board)
+simulator.run()

materials/isca24/04-kvm.py

@@ -0,0 +1,88 @@
+"""
+Simple example to play around with KVM
+Takes about 30 seconds to boot to the interactive prompt.
+
+Run with gem5-mesi 04-kvm.py
+"""
+
+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 SingleChannelDDR4_2400
+from gem5.components.processors.cpu_types import CPUTypes
+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 simulation requires using KVM with gem5 compiled for X86 simulation
+# and with MESI_Two_Level cache coherence protocol.
+requires(
+    isa_required=ISA.X86,
+    coherence_protocol_required=CoherenceProtocol.MESI_TWO_LEVEL,
+    kvm_required=True,
+)
+
+from gem5.components.cachehierarchies.ruby.mesi_two_level_cache_hierarchy import (
+    MESITwoLevelCacheHierarchy,
+)
+
+cache_hierarchy = MESITwoLevelCacheHierarchy(
+    l1d_size="32KiB",
+    l1d_assoc=8,
+    l1i_size="32KiB",
+    l1i_assoc=8,
+    l2_size="512KiB",
+    l2_assoc=16,
+    num_l2_banks=1,
+)
+
+# Main memory
+memory = SingleChannelDDR4_2400(size="3GiB")
+
+# This is a switchable CPU. We first boot Ubuntu using KVM, then the guest
+# will exit the simulation by calling "m5 exit" (see the `command` variable
+# below, which contains the command to be run in the guest after booting).
+# Upon exiting from the simulation, the Exit Event handler will switch the
+# CPU type (see the ExitEvent.EXIT line below, which contains a map to
+# a function to be called when an exit event happens).
+processor = SimpleSwitchableProcessor(
+    starting_core_type=CPUTypes.KVM,
+    switch_core_type=CPUTypes.TIMING,
+    isa=ISA.X86,
+    num_cores=1,
+)
+
+# Here we tell the KVM CPU (the starting CPU) not to use perf.
+for proc in processor.start:
+    proc.core.usePerf = False
+
+# Here we setup the board. The X86Board allows for Full-System X86 simulations.
+board = X86Board(
+    clk_freq="3GHz",
+    processor=processor,
+    memory=memory,
+    cache_hierarchy=cache_hierarchy,
+)
+
+workload = obtain_resource("x86-ubuntu-24.04-boot-with-systemd")
+board.set_workload(workload)
+board.append_kernel_arg("interactive=true") # don't execute default script
+
+def on_exit():
+    pass
+
+simulator = Simulator(
+    board=board,
+    on_exit_event={
+        ExitEvent.EXIT: on_exit(),
+    },
+)
+
+simulator.run()