From 442923c414d5d3f3d94d462ed0f9baae83db177f Mon Sep 17 00:00:00 2001 From: Jason Lowe-Power Date: Mon, 17 Jul 2023 10:41:51 -0700 Subject: [PATCH] Add feature to output citations automatically based on configuration (#90) This change adds a new file to m5out which is citations.bib. This file will contain the citations to the papers which describe the aspects of the gem5 simulator that the simulation uses. In other words, each simulation configuration could generate a different bib file referencing different works. Each SimObject can now have a set of citations associated with it. After the system is built (in `instantiate`), the citations.bib file is created by parsing all SimObjects that have been instantiated and taking the union of their associated citations. This commit is not meant to add all citations, but to act as an example for others to add more citations to gem5. Change-Id: Icd5c46fd9ee44adbeec1fea162657f5716f7e5ef Signed-off-by: Jason Lowe-Power --- src/gpu-compute/GPU.py | 33 ++++ src/mem/DRAMSim2.py | 21 ++ src/mem/DRAMSys.py | 29 +++ src/mem/DRAMsim3.py | 23 +++ src/mem/MemCtrl.py | 22 +++ src/mem/ruby/network/garnet/GarnetNetwork.py | 38 ++++ src/python/SConscript | 1 + src/python/m5/SimObject.py | 4 + src/python/m5/citations.py | 191 +++++++++++++++++++ src/python/m5/simulate.py | 3 + 10 files changed, 365 insertions(+) create mode 100644 src/python/m5/citations.py diff --git a/src/gpu-compute/GPU.py b/src/gpu-compute/GPU.py index c64a6b791d..d2b9e98362 100644 --- a/src/gpu-compute/GPU.py +++ b/src/gpu-compute/GPU.py @@ -27,6 +27,7 @@ # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE # POSSIBILITY OF SUCH DAMAGE. +from m5.citations import add_citation from m5.defines import buildEnv from m5.params import * from m5.proxy import * @@ -356,3 +357,35 @@ class StorageClassType(Enum): "SC_ARG", "SC_NONE", ] + + +add_citation( + ComputeUnit, + """@inproceedings{Gutierrez:2018:amdgpu, + author = {Anthony Gutierrez and + Bradford M. Beckmann and + Alexandru Dutu and + Joseph Gross and + Michael LeBeane and + John Kalamatianos and + Onur Kayiran and + Matthew Poremba and + Brandon Potter and + Sooraj Puthoor and + Matthew D. Sinclair and + Mark Wyse and + Jieming Yin and + Xianwei Zhang and + Akshay Jain and + Timothy G. Rogers}, + title = {Lost in Abstraction: Pitfalls of Analyzing GPUs at the Intermediate + Language Level}, + booktitle = {{IEEE} International Symposium on High Performance Computer Architecture, + {HPCA} 2018, Vienna, Austria, February 24-28, 2018}, + pages = {608--619}, + publisher = {{IEEE} Computer Society}, + year = {2018}, + url = {https://doi.org/10.1109/HPCA.2018.00058}, + doi = {10.1109/HPCA.2018.00058} +}""", +) diff --git a/src/mem/DRAMSim2.py b/src/mem/DRAMSim2.py index 364a0d794b..14c85312fe 100644 --- a/src/mem/DRAMSim2.py +++ b/src/mem/DRAMSim2.py @@ -33,6 +33,8 @@ # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +from citations import add_citation + from m5.params import * from m5.objects.AbstractMemory import * @@ -56,3 +58,22 @@ class DRAMSim2(AbstractMemory): ) traceFile = Param.String("", "Output file for trace generation") enableDebug = Param.Bool(False, "Enable DRAMSim2 debug output") + + +add_citation( + DRAMSim2, + """@article{Rosenfeld:2011:dramsim2, + author = {Paul Rosenfeld and + Elliott Cooper{-}Balis and + Bruce L. Jacob}, + title = {DRAMSim2: {A} Cycle Accurate Memory System Simulator}, + journal = {{IEEE} Compututer Architecture Letters}, + volume = {10}, + number = {1}, + pages = {16--19}, + year = {2011}, + url = {https://doi.org/10.1109/L-CA.2011.4}, + doi = {10.1109/L-CA.2011.4} +} +""", +) diff --git a/src/mem/DRAMSys.py b/src/mem/DRAMSys.py index c7d69a0ae4..9f84dbc1de 100644 --- a/src/mem/DRAMSys.py +++ b/src/mem/DRAMSys.py @@ -24,6 +24,8 @@ # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +from m5.citations import add_citation + from m5.SimObject import * from m5.params import * from m5.proxy import * @@ -41,3 +43,30 @@ class DRAMSys(AbstractMemory): configuration = Param.String("Path to the DRAMSys configuration") resource_directory = Param.String("Path to the DRAMSys resource directory") recordable = Param.Bool(True, "Whether DRAMSys should record a trace file") + + +add_citation( + DRAMSys, + """@inproceedings{Steiner:2020:dramsys4, + author = {Lukas Steiner and + Matthias Jung and + Felipe S. Prado and + Kirill Bykov and + Norbert Wehn}, + editor = {Alex Orailoglu and + Matthias Jung and + Marc Reichenbach}, + title = {DRAMSys4.0: {A} Fast and Cycle-Accurate SystemC/TLM-Based {DRAM} Simulator}, + booktitle = {Embedded Computer Systems: Architectures, Modeling, and Simulation + - 20th International Conference, {SAMOS} 2020, Samos, Greece, July + 5-9, 2020, Proceedings}, + series = {Lecture Notes in Computer Science}, + volume = {12471}, + pages = {110--126}, + publisher = {Springer}, + year = {2020}, + url = {https://doi.org/10.1007/978-3-030-60939-9\_8}, + doi = {10.1007/978-3-030-60939-9\_8} +} +""", +) diff --git a/src/mem/DRAMsim3.py b/src/mem/DRAMsim3.py index 40f61608d8..0ca0077a85 100644 --- a/src/mem/DRAMsim3.py +++ b/src/mem/DRAMsim3.py @@ -33,6 +33,8 @@ # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +from m5.citations import add_citation + from m5.params import * from m5.objects.AbstractMemory import * @@ -54,3 +56,24 @@ class DRAMsim3(AbstractMemory): filePath = Param.String( "ext/dramsim3/DRAMsim3/", "Directory to prepend to file names" ) + + +add_citation( + DRAMsim3, + """@article{Li:2020:dramsim3, + author = {Shang Li and + Zhiyuan Yang and + Dhiraj Reddy and + Ankur Srivastava and + Bruce L. Jacob}, + title = {DRAMsim3: {A} Cycle-Accurate, Thermal-Capable {DRAM} Simulator}, + journal = {{IEEE} Compututer Architecture Letters}, + volume = {19}, + number = {2}, + pages = {110--113}, + year = {2020}, + url = {https://doi.org/10.1109/LCA.2020.2973991}, + doi = {10.1109/LCA.2020.2973991} +} +""", +) diff --git a/src/mem/MemCtrl.py b/src/mem/MemCtrl.py index 549616ccba..62e4d97b26 100644 --- a/src/mem/MemCtrl.py +++ b/src/mem/MemCtrl.py @@ -41,6 +41,7 @@ from m5.params import * from m5.proxy import * from m5.objects.QoSMemCtrl import * +from m5.citations import add_citation # Enum for memory scheduling algorithms, currently First-Come # First-Served and a First-Row Hit then First-Come First-Served @@ -99,3 +100,24 @@ class MemCtrl(QoSMemCtrl): command_window = Param.Latency("10ns", "Static backend latency") disable_sanity_check = Param.Bool(False, "Disable port resp Q size check") + + +add_citation( + MemCtrl, + """@inproceedings{Hansson:2014:dram-controller, + author = {Andreas Hansson and + Neha Agarwal and + Aasheesh Kolli and + Thomas F. Wenisch and + Aniruddha N. Udipi}, + title = {Simulating {DRAM} controllers for future system architecture exploration}, + booktitle = {2014 {IEEE} International Symposium on Performance Analysis of Systems + and Software, {ISPASS} 2014, Monterey, CA, USA, March 23-25, 2014}, + pages = {201--210}, + publisher = {{IEEE} Computer Society}, + year = {2014}, + url = {https://doi.org/10.1109/ISPASS.2014.6844484}, + doi = {10.1109/ISPASS.2014.6844484} +} +""", +) diff --git a/src/mem/ruby/network/garnet/GarnetNetwork.py b/src/mem/ruby/network/garnet/GarnetNetwork.py index 128118309c..bf5a0bad33 100644 --- a/src/mem/ruby/network/garnet/GarnetNetwork.py +++ b/src/mem/ruby/network/garnet/GarnetNetwork.py @@ -28,6 +28,7 @@ # Author: Tushar Krishna # +from m5.citations import add_citation from m5.params import * from m5.proxy import * from m5.objects.Network import RubyNetwork @@ -83,3 +84,40 @@ class GarnetRouter(BasicRouter): width = Param.UInt32( Parent.ni_flit_size, "bit width supported by the router" ) + + +add_citation( + GarnetNetwork, + """@inproceedings{Bharadwaj:2020:kite, + author = {Srikant Bharadwaj and + Jieming Yin and + Bradford M. Beckmann and + Tushar Krishna}, + title = {Kite: {A} Family of Heterogeneous Interposer Topologies Enabled via + Accurate Interconnect Modeling}, + booktitle = {57th {ACM/IEEE} Design Automation Conference, {DAC} 2020, San Francisco, + CA, USA, July 20-24, 2020}, + pages = {1--6}, + publisher = {{IEEE}}, + year = {2020}, + url = {https://doi.org/10.1109/DAC18072.2020.9218539}, + doi = {10.1109/DAC18072.2020.9218539} +} +@inproceedings{Agarwal:2009:garnet, + author = {Niket Agarwal and + Tushar Krishna and + Li{-}Shiuan Peh and + Niraj K. Jha}, + title = {{GARNET:} {A} detailed on-chip network model inside a full-system + simulator}, + booktitle = {{IEEE} International Symposium on Performance Analysis of Systems + and Software, {ISPASS} 2009, April 26-28, 2009, Boston, Massachusetts, + USA, Proceedings}, + pages = {33--42}, + publisher = {{IEEE} Computer Society}, + year = {2009}, + url = {https://doi.org/10.1109/ISPASS.2009.4919636}, + doi = {10.1109/ISPASS.2009.4919636} +} +""", +) diff --git a/src/python/SConscript b/src/python/SConscript index ea9d3d4021..eaaea203f0 100644 --- a/src/python/SConscript +++ b/src/python/SConscript @@ -311,6 +311,7 @@ PySource('gem5.utils.multiprocessing', PySource('', 'importer.py') PySource('m5', 'm5/__init__.py') PySource('m5', 'm5/SimObject.py') +PySource('m5', 'm5/citations.py') PySource('m5', 'm5/core.py') PySource('m5', 'm5/debug.py') PySource('m5', 'm5/event.py') diff --git a/src/python/m5/SimObject.py b/src/python/m5/SimObject.py index 08105d8833..f2c1b30def 100644 --- a/src/python/m5/SimObject.py +++ b/src/python/m5/SimObject.py @@ -47,6 +47,8 @@ import m5 from m5.util import * from m5.util.pybind import * +from m5.citations import gem5_citations + # Use the pyfdt and not the helper class, because the fdthelper # relies on the SimObject definition from m5.ext.pyfdt import pyfdt @@ -215,6 +217,8 @@ class MetaSimObject(type): cls._instantiated = False # really instantiated, cloned, or subclassed cls._init_called = False # Used to check if __init__ overridden + cls._citations = gem5_citations # Default to gem5's citations + # We don't support multiple inheritance of sim objects. If you want # to, you must fix multidict to deal with it properly. Non sim-objects # are ok, though diff --git a/src/python/m5/citations.py b/src/python/m5/citations.py new file mode 100644 index 0000000000..1ac8e08145 --- /dev/null +++ b/src/python/m5/citations.py @@ -0,0 +1,191 @@ +# Copyright (c) 2023 The Regents of The University of California +# All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are +# met: redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer; +# redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution; +# neither the name of the copyright holders nor the names of its +# contributors may be used to endorse or promote products derived from +# this software without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +from pathlib import Path +from typing import Type + +import m5.options + + +def add_citation(sim_obj_cls: Type["SimObject"], citation: str): + """Add a citation to a SimObject class. + + :param sim_obj_cls: The SimObject class to add the citation to. + :param citation: The citation to add. Should be bibtex compatible + entry or entries + + This function will encode the citation into the SimObject class and it + will be included in the citations in the output directory when the + SimObject is used. If you have multiple citations, then you should include + one multiline string with all of the citations. + """ + + sim_obj_cls._citations += citation + + +def gather_citations(root: "SimObject"): + """Based on the root SimObject, walk the object hierarchy and gather all + of the citations together and then print them to citations.bib in the + output directory. + """ + + citations = {} + for obj in root.descendants(): + loc = 0 + while loc >= 0: + key, cite, loc = _get_next_key_entry(obj._citations, loc) + # If a key repeats, then just overwrite it + citations[key] = cite + + with open(Path(m5.options.outdir) / "citations.bib", "w") as output: + output.writelines(citations.values()) + + +def _get_next_key_entry(citations: str, loc: int = 0): + """Return the key, the citation, and the end of the citation location""" + + start = citations.find("@", loc) + key_start = citations.find("{", start) + key_end = citations.find(",", key_start) + end = citations.find("@", start + 1) + if end == -1: + end = len(citations) + next = -1 + else: + next = end + + return citations[key_start:key_end], citations[start:end], next + + +gem5_citations = """@article{Binkert:2011:gem5, + author = {Nathan L. Binkert and + Bradford M. Beckmann and + Gabriel Black and + Steven K. Reinhardt and + Ali G. Saidi and + Arkaprava Basu and + Joel Hestness and + Derek Hower and + Tushar Krishna and + Somayeh Sardashti and + Rathijit Sen and + Korey Sewell and + Muhammad Shoaib Bin Altaf and + Nilay Vaish and + Mark D. Hill and + David A. Wood}, + title = {The gem5 simulator}, + journal = {{SIGARCH} Comput. Archit. News}, + volume = {39}, + number = {2}, + pages = {1--7}, + year = {2011}, + url = {https://doi.org/10.1145/2024716.2024718}, + doi = {10.1145/2024716.2024718} +} +@article{Lowe-Power:2020:gem5-20, + author = {Jason Lowe{-}Power and + Abdul Mutaal Ahmad and + Ayaz Akram and + Mohammad Alian and + Rico Amslinger and + Matteo Andreozzi and + Adri{\`{a}} Armejach and + Nils Asmussen and + Srikant Bharadwaj and + Gabe Black and + Gedare Bloom and + Bobby R. Bruce and + Daniel Rodrigues Carvalho and + Jer{\'{o}}nimo Castrill{\'{o}}n and + Lizhong Chen and + Nicolas Derumigny and + Stephan Diestelhorst and + Wendy Elsasser and + Marjan Fariborz and + Amin Farmahini Farahani and + Pouya Fotouhi and + Ryan Gambord and + Jayneel Gandhi and + Dibakar Gope and + Thomas Grass and + Bagus Hanindhito and + Andreas Hansson and + Swapnil Haria and + Austin Harris and + Timothy Hayes and + Adrian Herrera and + Matthew Horsnell and + Syed Ali Raza Jafri and + Radhika Jagtap and + Hanhwi Jang and + Reiley Jeyapaul and + Timothy M. Jones and + Matthias Jung and + Subash Kannoth and + Hamidreza Khaleghzadeh and + Yuetsu Kodama and + Tushar Krishna and + Tommaso Marinelli and + Christian Menard and + Andrea Mondelli and + Tiago M{\"{u}}ck and + Omar Naji and + Krishnendra Nathella and + Hoa Nguyen and + Nikos Nikoleris and + Lena E. Olson and + Marc S. Orr and + Binh Pham and + Pablo Prieto and + Trivikram Reddy and + Alec Roelke and + Mahyar Samani and + Andreas Sandberg and + Javier Setoain and + Boris Shingarov and + Matthew D. Sinclair and + Tuan Ta and + Rahul Thakur and + Giacomo Travaglini and + Michael Upton and + Nilay Vaish and + Ilias Vougioukas and + Zhengrong Wang and + Norbert Wehn and + Christian Weis and + David A. Wood and + Hongil Yoon and + {\'{E}}der F. Zulian}, + title = {The gem5 Simulator: Version 20.0+}, + journal = {CoRR}, + volume = {abs/2007.03152}, + year = {2020}, + url = {https://arxiv.org/abs/2007.03152}, + eprinttype = {arXiv}, + eprint = {2007.03152} +} +""" diff --git a/src/python/m5/simulate.py b/src/python/m5/simulate.py index 587bfa0202..70ed11a9b6 100644 --- a/src/python/m5/simulate.py +++ b/src/python/m5/simulate.py @@ -51,6 +51,7 @@ from . import SimObject from . import ticks from . import objects from . import params +from .citations import gather_citations from m5.util.dot_writer import do_dot, do_dvfs_dot from m5.util.dot_writer_ruby import do_ruby_dot @@ -164,6 +165,8 @@ def instantiate(ckpt_dir=None): # a checkpoint, If so, this call will shift them to be at a valid time. updateStatEvents() + gather_citations(root) + need_startup = True