Difference between revisions of "Source Code"

From gem5
Jump to: navigation, search
(Style rules)
m
 
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
==Source Code==
+
==Source Browsing Tools==
  
===Tour of the tree===
+
The gem5 source code is browsable online via several methods.  You can browse the latest version or the developmen history in [http://repo.gem5.org/gem5 our Mercurial repository], search the code using [http://grok.gem5.org/ our OpenGrok installation], or look at the [http://www.gem5.org/docs/html/index.html Doxygen-generated documentation] (note that the [http://www.gem5.org/docs/html/annotated.html class list] is perhaps the most useful starting point).
  
These are the files and directories at the top of the tree:
+
Once you have your own local copy of the tree, you use other tools to index and search that copy.  Many gem5 developers use [http://cscope.sourceforge.net cscope], and have included a script in <code>util/cscope-index.py</code> to generate a cscope index.
AUTHORS  LICENSE  README  RELEASE_NOTES  SConstruct  build_opts  configs  ext  src  system  tests  util
 
  
<code>AUTHORS, LICENSE, README</code> are files with general information about the simulator. AUTHORS is a list of people who have historically contributed to M5. LICENSE has the license terms that applies to M5 as a whole, unless overridden by a more specific license. README has some very basic information introducing M5 and explaining how to get started.
+
==Tour of the tree==
  
The <code>SConstruct</code> file is part of the build system, as is the build_opts directory. build_opts holds files that define default settings for build different build configurations. These include X86_FS and MIPS_SE, for instance.
+
* <b>AUTHORS</b> - A list of people who have historically contributed to gem5.
 +
* <b>LICENSE</b> - The license terms that apply to gem5 as a whole, unless overridden by a more specific license.
 +
* <b>README</b> - Some very basic information introducing gem5 and explaining how to get started.
 +
* <b>SConstruct</b> - A part of the build system, as is the build_opts directory.
 +
* <b>build_opts</b> - holds files that define default settings for build different build configurations. These include X86_FS and MIPS_SE, for instance.
 +
* <b>configs</b> - Simulation configuration scripts which are written in python, described in more detail later. The files in this directory help make writing configurations easier by providing some basic prepackaged functionality, and include a few examples which can be used directly or as a starting point for your own scripts.
 +
* <b>ext</b> - Things gem5 depends on but which aren’t actually part of gem5. Specifically, dependencies that are harder to find, not likely to be available, or where a particular version is needed.
 +
* <b>src</b> - gem5 source code.
 +
** <b>arch</b> - ISA implementations.
 +
*** <b>generic</b> - Common files for use in other ISAs.
 +
*** <b>isa_parser.py</b> - Parser that interprets ISA descriptions.
 +
*** <b>ISA directories</b> - The files associated with the given ISA.
 +
**** <b>OS directories</b> - Code for supporting an ISA/OS combination, generally in SE mode.
 +
**** <b>isa</b> - ISA description files.
 +
** <b>base</b> - General data structures and facilities that could be useful for another project.
 +
*** <b>loader</b> - Code for loading binaries and reading symbol tables.
 +
*** <b>stats</b> - Code for keeping statistics and writing the data to a file or a database.
 +
*** <b>vnc</b> - VNC support.
 +
** <b>cpu</b> - CPU models.
 +
** <b>dev</b> - Device models.
 +
*** <b>ISA directories</b> - Device models specific to the given ISA
 +
** <b>doxygen</b> - Doxygen templates & output
 +
** <b>kern</b> - Operating system specific but architecture independent code (e.g. types of data structures).
 +
*** <b>OS directories</b> - Code specific to the given simulated operating system.
 +
** <b>mem</b> - Memory system models and infrastructure.
 +
*** <b>cache</b> - Code that implements a cache model in the classic memory system.
 +
*** <b>ruby</b> - Code that implements the ruby memory model.
 +
*** <b>protocol</b> - Ruby protocol definitions.
 +
*** <b>slicc</b> - The slicc compiler.
 +
** <b>python</b> - Python code for configuration and higher level functions.
 +
** <b>sim</b> - Code that implements basic, fundamental simulator functionality.
 +
* <b>system</b> - Low level software like firmware or bootloaders for use in simulated systems.
 +
** <b>alpha</b> - Alpha console and palcode.
 +
** <b>arm</b> - A simple ARM bootloader.
 +
* <b>tests</b> - Files related to gem5’s regression tests.
 +
** <b>configs</b> - General configurations used for the tests.
 +
** <b>test-progs</b> - "Hello world" binaries for each ISA, other binaries are downloaded separately.
 +
** <b>quick, long</b> - Quick and long regression inputs, reference outputs, and test specific configuration files, arranged per test.
  
The <code>configs</code> directory is for simulation configuration scripts which are written in python. These are described in more detail later. The files in this directory help make writing configurations easier by providing some basic prepackaged functionality, and include a few examples which can be used directly or as a starting point for your own scripts.
+
* <b>util</b> - Utility scripts, programs and useful files which are not part of the gem5 binary but are generally useful when working on gem5.
  
The <code>ext</code> directory is for things M5 depends on but which aren’t actually part of M5. Specifically these are for dependencies that are harder to find, not likely to be available, or where a particular version is needed.
+
==Style rules==
 +
All of the code in gem5 is expected to follow a set rules described in our [[Coding Style | style guide]]. These rules make the code more consistent which make it easier to read, maintain, and extend the code. Specific coding style has been defined for things such as [[Coding Style#Indentation and Line Breaks | Indentation and Line Breaks ]], [[Coding Style#Spacing | Spacing]], [[Coding Style#Naming | Naming of Variables & Classes]], and [[Coding Style#M5_Status_Messages | M5 Status Messages]]. There are also [[Documentation Guidelines]] which you should follow which allow documentation to be generated automatically using the Doxygen system.  
  
The <code>src</code> directory is where most of M5 is located. This is where all of the C++ and python source that contributes to the M5 binary is kept, excluding components in the ext directory.
+
==Generated files - where do they end up==
 
 
The <code>system</code> directory is for the source for low level software like firmware or bootloaders for use in simulated systems. Currently this includes Alpha’s PAL and console code, and a simple bootloader for ARM.
 
 
 
The <code>tests</code> directory stores files related to M5’s regression tests. These include the scripts that build up the configurations used in the tests and reference outputs. Simple hello world binaries are also stored here, but other binaries need to be downloaded separately.
 
 
 
Finally, in the <code>util</code> directory are utility scripts, programs and useful files which are not part of the M5 binary but are generally useful when working on M5.
 
 
 
===Style rules===
 
As you go through the M5 source code, you'll notice that there are a number of coding conventions that M5 developers use throughout out. Consistent [[Coding Style]] makes it easier for M5 users to read, maintain, and eventually update the code. Specific coding style has been defined for things such as [[Coding Style#Indentation and Line Breaks | Indentation and Line Breaks ]], [[Coding Style#Spacing | Spacing]], [[Coding Style#Naming | Naming of Variables & Classes]], and [[Coding Style#M5_Status_Messages | M5 Status Messages]]. Finally, Following the [[Documentation Guidelines]] provides an easy way for M5 to automatically generate Doxygen, gem5 documentation.
 
 
 
Please see the [[Coding Style]] page for details and examples of the gem5 style rules.
 
 
 
===Generated files - where do they end up===
 
  
 
   
 
   
  
===.m5 config files===
+
==.m5 config files==
+
If you would like to set some gem5 parameters to a value by default you can create a <code>.m5</code> directory within your home directory and inside place a file called <code>options.py</code>. Within this file you may set any gem5 command line option to a new default. For example placing <code>options.stdout_file=simout</code> in <code>options.py</code> will result in the simulators stdout always being re-directed to a file named simout.
  
===jobfile to run multiple jobs===
+
==jobfile to run multiple jobs==

Latest revision as of 15:30, 15 May 2014

Source Browsing Tools

The gem5 source code is browsable online via several methods. You can browse the latest version or the developmen history in our Mercurial repository, search the code using our OpenGrok installation, or look at the Doxygen-generated documentation (note that the class list is perhaps the most useful starting point).

Once you have your own local copy of the tree, you use other tools to index and search that copy. Many gem5 developers use cscope, and have included a script in util/cscope-index.py to generate a cscope index.

Tour of the tree

  • AUTHORS - A list of people who have historically contributed to gem5.
  • LICENSE - The license terms that apply to gem5 as a whole, unless overridden by a more specific license.
  • README - Some very basic information introducing gem5 and explaining how to get started.
  • SConstruct - A part of the build system, as is the build_opts directory.
  • build_opts - holds files that define default settings for build different build configurations. These include X86_FS and MIPS_SE, for instance.
  • configs - Simulation configuration scripts which are written in python, described in more detail later. The files in this directory help make writing configurations easier by providing some basic prepackaged functionality, and include a few examples which can be used directly or as a starting point for your own scripts.
  • ext - Things gem5 depends on but which aren’t actually part of gem5. Specifically, dependencies that are harder to find, not likely to be available, or where a particular version is needed.
  • src - gem5 source code.
    • arch - ISA implementations.
      • generic - Common files for use in other ISAs.
      • isa_parser.py - Parser that interprets ISA descriptions.
      • ISA directories - The files associated with the given ISA.
        • OS directories - Code for supporting an ISA/OS combination, generally in SE mode.
        • isa - ISA description files.
    • base - General data structures and facilities that could be useful for another project.
      • loader - Code for loading binaries and reading symbol tables.
      • stats - Code for keeping statistics and writing the data to a file or a database.
      • vnc - VNC support.
    • cpu - CPU models.
    • dev - Device models.
      • ISA directories - Device models specific to the given ISA
    • doxygen - Doxygen templates & output
    • kern - Operating system specific but architecture independent code (e.g. types of data structures).
      • OS directories - Code specific to the given simulated operating system.
    • mem - Memory system models and infrastructure.
      • cache - Code that implements a cache model in the classic memory system.
      • ruby - Code that implements the ruby memory model.
      • protocol - Ruby protocol definitions.
      • slicc - The slicc compiler.
    • python - Python code for configuration and higher level functions.
    • sim - Code that implements basic, fundamental simulator functionality.
  • system - Low level software like firmware or bootloaders for use in simulated systems.
    • alpha - Alpha console and palcode.
    • arm - A simple ARM bootloader.
  • tests - Files related to gem5’s regression tests.
    • configs - General configurations used for the tests.
    • test-progs - "Hello world" binaries for each ISA, other binaries are downloaded separately.
    • quick, long - Quick and long regression inputs, reference outputs, and test specific configuration files, arranged per test.
  • util - Utility scripts, programs and useful files which are not part of the gem5 binary but are generally useful when working on gem5.

Style rules

All of the code in gem5 is expected to follow a set rules described in our style guide. These rules make the code more consistent which make it easier to read, maintain, and extend the code. Specific coding style has been defined for things such as Indentation and Line Breaks , Spacing, Naming of Variables & Classes, and M5 Status Messages. There are also Documentation Guidelines which you should follow which allow documentation to be generated automatically using the Doxygen system.

Generated files - where do they end up

.m5 config files

If you would like to set some gem5 parameters to a value by default you can create a .m5 directory within your home directory and inside place a file called options.py. Within this file you may set any gem5 command line option to a new default. For example placing options.stdout_file=simout in options.py will result in the simulators stdout always being re-directed to a file named simout.

jobfile to run multiple jobs