RELEASE-NOTES.md

   1 # Version 20.1.0.2
   2
   3 **[HOTFIX]** This hotfix release fixes known two bugs:
   4
   5 * A "ValueError: invalid literal for int() with base..." error was being thrown in certain circumstances due to a non-integer being passed to "MemorySize" via a division operation. This has been rectified.
   6 * An assertion in Stats could be triggered due to a name collision between two ThreadStateStats objects, due to both erroneously sharing the same ThreadID. This has been fixed.
   7
   8 # Version 20.1.0.1
   9
  10 **[HOTFIX]** A patch was applied to fix the Garnet network interface stats.
  11 Previously, the flit source delay was computed using both tick and cycles.
  12 This bug affected the overall behavior of the Garnet Network Model.
  13
  14 # Version 20.1.0.0
  15
  16 Thank you to everyone that made this release possible!
  17 This has been a very productive release with [150 issues](https://gem5.atlassian.net/), over 650  commits (a 25% increase from the 20.0 release), and 58 unique contributors (a 100% increase!).
  18
  19 ## Process changes
  20
  21 We are no longer using the "master" branch.
  22 Instead, we will have two branches:
  23
  24 * "stable": This will point to the latest stable release (gem5-20.1 as of today)
  25 * "develop": This is the latest development code that will be merged in to the "stable" branch at each release.
  26
  27 We suggest all *users* use the stable (default) branch.
  28 However, to contribute your fixes and new changes to gem5, it should be contributed to the develop branch.
  29 See CONTRIBUTING.md for more details.
  30
  31 gem5 has also implemented a project code of conduct.
  32 See the CODE-OF-CONDUCT.md file for details.
  33 In the code of conduct "we pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community."
  34
  35 ## New features in 20.1
  36
  37 ### New DRAM interface: Contributed by *Wendy Elsasser*
  38
  39 You can find details about this on the [gem5 blog](http://www.gem5.org/2020/05/27/memory-controller.html) or Wendy's talks on YouTube: [Talk on new interface and NVM](https://www.youtube.com/watch?v=t2PRoZPwwpk) and the [talk on LPDDR5](https://www.youtube.com/watch?v=ttJ9_I_Avyc)
  40
  41 * **[PYTHON API CHANGE]**: The DRAM models are now *DRAM interfaces* which is a child of the *memory controller*. Example change shown [in the blog post](http://www.gem5.org/project/2020/07/18/gem5-20-1.html).
  42   * The DRAM is split into a memory controller and a DRAM interface
  43   * `SimpleMemory` is no longer a drop-in replacement for a DRAM-based memory controller.
  44 * LPDDR5 model added
  45 * NVM model added
  46 * New memory controller model that can use both NVM and DRAM
  47
  48 ### Improved on-chip interconnect model, HeteroGarnet: Contributed by *Srikant Bharadwaj*
  49
  50 You can find details about this on the [gem5 blog](http://www.gem5.org/2020/05/27/heterogarnet.html) and [Srikant's talk on YouTube](https://www.youtube.com/watch?v=AH9r44r2lHA).
  51
  52 * **[USER-FACING CHANGE]**: The network type options are now "simple" and "garnet" instead of "garnet2.0". (If "garnet2.0" is used, you will get a warning until gem5-20.2)
  53 * Added models for clock domain crossings and serialization/deserialization (SERDES)
  54
  55 ### Transactional memory support: Contributed by *Timothy Hayes*
  56
  57 You can find details on the [Jira issue](https://gem5.atlassian.net/browse/GEM5-587)
  58
  59 * gem5 now supports Arm TME (transactional memory extensions)
  60 * Transactional memory is only implemented in the `MESI_Three_Level_HTM` Ruby protocol, and it is only implemented in Ruby.
  61 * This implements a checkpointing mechanism for the architectural state and buffering of speculative memory updates.
  62 * IBM POWER and x86 HTM extensions have *not* been implemented.
  63
  64 ### Other new features
  65
  66 * External simulator integrations
  67   * Added support for DRAMSim3
  68   * Added back support for DRAMSim2
  69 * Armv8-A Self Hosted Debug extension added
  70 * KVM support for Armv8-A  hosts without GICv2 hardware
  71 * Implemented Secure EL2 for Armv8-A
  72
  73 ## Removed features
  74
  75 * Dropped support for mercurial version control
  76
  77 ## New supported platforms
  78
  79 * GCC up to 10.2 is now supported. Minimum GCC is now 5.0.
  80 * Clang up to version 9. Minimum Clang is now 3.9.
  81
  82 ## Platforms no longer support
  83
  84 * **[USER-FACING CHANGE]**: Python 2 is officially deprecated. We will drop support for Python 2 in the next release. In this release you will get a warning if you're using Python 2.
  85 * **[USER-FACING CHANGE]**: We have dropped support for GCC 4.X
  86 * **[USER-FACING CHANGE]**: We have dropped support for Scons 2.x (Note: this is the default in Ubuntu 16.04. Use pip to install a newer scons.)
  87
  88 See <http://www.gem5.org/documentation/general_docs/building> for gem5's current dependencies.
  89
  90 ## Other changes
  91
  92 ### Deprecating "master" and "slave"
  93
  94 * **[API CHANGE]**: The names "master" and "slave" have been deprecated
  95   * Special thanks to Lakin Smith, Shivani Parekh, Eden Avivi, and Emily Brickey.
  96   * Below is a guide to most of the name changes.
  97   * The goal was to replace problematic language with more descriptive and precise terms.
  98 * There may be some bugs introduced with this change as there were many places in the Python configurations which relied on "duck typing".
  99 * This change is mostly backwards compatible and warning will be issued until at least gem5-20.2.
 100
 101 ```
 102 MasterPort -> RequestorPort
 103 SlavePort -> ResponsePort
 104
 105 xbar.slave -> xbar.cpu_side
 106 xbar.master -> xbar.mem_side
 107
 108 MasterId -> RequestorId
 109 ```
 110
 111 ### Testing improvements
 112
 113 * We now have Jenkins server (<http://jenkins.gem5.org/>) running nightly and other large tests. Special thanks to Mike Upton for setting this up!
 114   * Nightly tests run the "long" regression tests (many tests added).
 115   * Compiler tests run gem5 build for many targets and all compilers once a week.
 116 * Updated CI tester (kokoro) to use a more up-to-date environment.
 117 * Improved the testing infrastructure.
 118   * Almost all testing resources now available in [gem5-resources repository](https://gem5.googlesource.com/public/gem5-resources/).
 119   * Generally cleaned up the `tests/` directory in mainline gem5.
 120   * Many general testlib improvements.
 121
 122 ### More changes
 123
 124 * **[PYTHON API CHANGE]**: m5.stats.dump() root argument renamed to roots to reflect the fact that it now takes a list of SimObjects
 125 * **[USER-FACING CHANGE]**: Checkpoint compatibility may be broken by the following changes
 126   * <https://gem5-review.googlesource.com/c/public/gem5/+/25145>
 127   * <https://gem5-review.googlesource.com/c/public/gem5/+/31874>
 128 * **[API CHANGE]** Changed `setCPU` to `setThreadContext` in Interrupts
 129 * Added a `Compressor` namespace.
 130 * **[API CHANGE]** The `Callback` class was removed and replaced with C++ lambdas.
 131 * Many objects' stats have been updated to the "new" stats style.
 132 * Many more objects have had their APIs formalized. See <http://www.gem5.org/documentation/general_docs/gem5-apis>
 133
 134 ----------------------------------------------------------------------------------------------------
 135
 136 # Version 20.0.0.3
 137
 138 **[HOTFIX]** When using the ARM ISA, gem5 could crash when a guest tried to call m5ops. This was due to `m5ops_base` being incorrectly declared in `src/arch/arm/ArmSystem.py`. A fix was applied to remove this declaration.
 139
 140 # Version 20.0.0.2
 141
 142 **[HOTFIX]** A patch was applied to fix the RubyPrefetcher with MESI_Three_Level. Prior to this fix a segfault occurred.
 143
 144 # Version 20.0.0.1
 145
 146 **[HOTFIX]** A fix was applied to stop incorrect clock frequences being reported due to rounding errors.
 147
 148 # Version 20.0.0.0
 149
 150 Welcome to our first "official" gem5 release!
 151 gem5 v19.0.0.0 was a "test" release, but this one has release notes, so it must be official!
 152
 153 Thank you to everyone that made this release possible!
 154 This has been a very productive release with over [70 issues closed](https://gem5.atlassian.net/), over 500 commits, and 31 unique contributors.
 155 Below are some of the highlights, though I'm sure I've missed some important changes.
 156
 157 ## New features
 158
 159 * [gem5-resources repository](https://gem5.googlesource.com/public/gem5-resources/)
 160   * This new repository will store all of the *sources* (e.g., code) used to create testing and research resources. This includes disk images, testing binaries, kernel binaries, etc.
 161   * Binaries created with the sources are hosted on dist.gem5.org.
 162   * Details on the new page for resources: <http://www.gem5.org/documentation/general_docs/gem5_resources>.
 163 * Memory SimObjects can now be initialized using an image file using the image_file parameter.
 164 * **[USER-FACING CHANGE]** The m5 utility has been revamped with a new build system based on scons, tests, and updated and more consistent feature support.
 165   * To build, now use `scons build/<arch>/out/m5`, not `make`.
 166   * [Documentation](http://www.gem5.org/documentation/general_docs/m5ops/) coming soon.
 167 * Robust support for marshalling data from a function call inside the simulation to a function within gem5 using a predefined set of rules.
 168   * Developers can specify an ABI for guest<->simulator calls and then "just call functions".
 169   * Unifies pseudo-inst, syscall, and other support.
 170   * Code within gem5 has been updated. However, users which added new pseudo-ops may have to update their code.
 171 * **[PYTHON API CHANGE]** Workload configuration pulled out into its own object, simplifying the System object and making workload configuration more modular and flexible.
 172   * All full system config/run scripts must be updated (e.g., anything that used the `LinuxX86System` or similar SimObject).
 173   * Many of the parameters of `System` are now parameters of the `Workload` (see `src/sim/Workload.py`).
 174     * For instance, many parameters of `LinuxX86System` are now part of `X86FsLinux` which is now the `workload` parameter of the `System` SimObject.
 175   * See https://gem5-review.googlesource.com/c/public/gem5/+/24283/ and https://gem5-review.googlesource.com/c/public/gem5/+/26466 for more details.
 176 * Sv39 paging has been added to the RISC-V ISA, bringing gem5 close to running Linux on RISC-V.
 177   * (Some) Baremetal OSes are now supported.
 178 * Improvements to DRAM model:
 179   * Added support for verifying available command bandwidth.
 180   * Added support for multi-cycle commands.
 181   * Added new timing parameters.
 182   * Added ability to interleave bursts.
 183   * Added LPDDR5 configurations.
 184 * **[Developer change]** We are beginning to document gem5 APIs.
 185   * Currently, only SimObjects and the APIs they depend on have been documented.
 186   * We are using doxygen to mark "stable APIs" and will use manual code review to make sure the APIs stay stable.
 187   * More information will be coming during gem5-20.1 development.
 188
 189 ## Removed features
 190
 191 * Support for the ALPHA ISA has been dropped.
 192   * All ALPHA ISA code has been removed
 193   * Old "rcS" scripts for ALPHA have been removed
 194
 195 ## New supported platforms
 196
 197 * Compiling and running gem5 with Python 3 is now fully supported.
 198   * Lots of code changes required for this.
 199   * There may still be some python code that's not up to date. Please open a [Jira ticket](https://gem5.atlassian.net/) if you find any code that doesn't work with python3.
 200 * gem5 now supports Ubuntu 20.04.
 201 * Compiling gem5 with GCC 8 and 9 is now supported.
 202 * Compiling with clang up to version 9 is now supported.
 203
 204 ## Testing improvements
 205
 206 * Scons-based tests have been migrated to the testlib framework.
 207   * Tests can now be run with `tests/main.py`, except for the unittests.
 208   * Please consult TESTING.md for more information on how these may be run.
 209 * We are continuing to work on CI tests. Most of the plumbing is there for Google Cloud Build integration. See [the Jira issue](https://gem5.atlassian.net/browse/GEM5-237) for details.
 210
 211 ## Other API changes
 212
 213 * **[API CHANGE]** Ruby's prefetcher renamed to RubyPrefetcher.
 214   * Any SLICC protocols with prefetchers need to be updated.
 215   * Some config scripts for Ruby protocols with prefetchers may need to be updated.
 216 * **[API CHANGE]** SE mode improvements.
 217   * Better support for the mmap and related syscalls.
 218   * A new virtual memory area API for tracking SE mode allocations.
 219   * When implementing syscalls, the way that guest memory is allocated changes. All code in gem5 is updated, but if there are any external syscalls, they may need be updated.
 220 * **[COMMAND LINE CHANGE]** The `--disk-image` argument to `fs.py` is now optional.
 221   * However, the disk image names *are no longer implied*.
 222   * The script still implicitly searches `M5_PATH`, but the name of the disk image must be specified.
 223 * **[API CHANGE]** SLICC `queueMemory` is now `enqueue`.
 224   * All protocol configs must be updated with another message buffer in the memory controllers (directories).
 225   * All protocol SLICC files must replace `queueMemoryRead` and `queueMemoryWrite` with `enqueue` to another "special" message buffer named `memQueue`.
 226   * This allows finite buffering between the cache controllers and DRAMCtrl.
 227 * **[API CHANGE]** Added Prefetcher namespace
 228   * All prefetchers' names have changed from `*Prefetcher` to `Prefetcher::*`
 229   * If you have any prefetchers that are not in the gem5 mainline, your code will likely need to be updated.
 230
 231 ## Other changes
 232
 233 * Implemented ARMv8.3-CompNum, SIMD complex number extension.
 234 * Support for Arm Trusted Firmware + u-boot with the new VExpress_GEM5_Foundation platform
 235 * Removed author list from source files.
 236   * This was originally so future people would know who to contact.
 237   * However, it was difficult to maintain and quickly out of date.
 238   * Copyright is unchanged.
 239 * Improvements to gem5's power model.
 240 * MESI_Three_Level Ruby protocol bugfixes.
 241 * Ruby functional reads now work in more cases.
 242 * Indirect branch stats work correctly now.