website: DO NOT MERGE - updates and notes on documentation for gem5 v25.0

_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).
+
+<!-- This should probably be updated to say that support for anything other
+than Arm, RISCV, and X86 isn't good -->
+<!-- Should Alpha be removed from this list? The release notes say it was deprecated in gem5 v20.0.0.0-->
+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)-->.
 
 #### 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 <!-- Is Android still relevant? -->
         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
+<!-- According to the release notes, support for the Alpha ISA was dropped in v20.0.0.0-->
+  <!-- - **Alpha**: gem5 models a DEC Tsunami system in sufficient detail 
         to boot unmodified Linux 2.4/2.6, FreeBSD, or L4Ka::Pistachio.
         We have also booted HP/Compaq's Tru64 5.1 operating system in
-        the past, though we no longer actively maintain that capability.
+        the past, though we no longer actively maintain that capability. -->
 
 #### 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).
 
+<!-- When Giacomo updated the Trace CPU documentation, his commit message said 
+something about the Trace CPU not being a CPU anymore. This section may need
+to be updated.
+ -->
 #### 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.
 
+<!-- This part was added only 8 months ago, but the linked image is from 2015.
+The link is also broken. This part should probably be updated 
+ -->
 #### 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. 

_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:

_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).
+
 <!-- Could use a nice picture here showing the main modules of the stdlib and how they relate -->
 
 ## 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.
 
+<!-- This section should also point toward hypercall documentation once it is up -->
+
 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/).

_pages/documentation/gem5-stdlib/1-tutorial-hello-world.md

@@ -7,30 +7,37 @@ permalink: /documentation/gem5-stdlib/hello-world-tutorial
 author: Bobby R. Bruce
 ---
 
+<!-- The full code example at the bottom of the page works fine and 
+is up to date
+ -->
+
 ## 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.
 This simulation will setup a system consisting of a single-core processor, running in Atomic mode, connected directly to main memory with no caches, I/O, or other components.
 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 <number of threads>
+scons build/ALL/gem5.opt -j <number of threads>
 ```
 
+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:
 
 ```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
 ```
 
@@ -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.
 
-<!-- It would be nice to describe here how to find out what resources are available -->
+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,30 +162,34 @@ 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!
 ```
 
 It should be obvious from this point that a _board's_ parameters may be altered to test other designs.
 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.