Difference between revisions of "Adding Functionality"

From gem5
Jump to: navigation, search
(s/M5/gem5/)
Line 1: Line 1:
This page describes the methods available to extend M5 while preserving the ability to update to new versions. If you intend to make any changes to M5 we '''strongly''' advise you to follow one of the following methods. It will save you a great deal of time in the future and allow you to take advantage of new M5 versions without the error prone process of manually diffing and patching versions.
+
This page describes the methods available to extend gem5 while preserving the ability to update to new versions. If you intend to make any changes to gem5 we '''strongly''' advise you to follow one of the following methods. It will save you a great deal of time in the future and allow you to take advantage of new gem5 versions without the error prone process of manually diffing and patching versions.
  
There are two recommend ways to add your own functionality to M5 and retain the ability to revision control your own code. The first suggested method relies on the queues feature of Mercurial (the revision control tool used for M5 development). The second relies on your own source control scheme (you could use mercurial or something else), and instead uses the [[Extras]] functionality in the build process to link extra objects into M5. In some situations a hybrid approach may be the best one, where the features you're attempting to evaluate are handled via the extras functionality, and minor changes to interfaces are done with Mercurial queues.
+
There are two recommend ways to add your own functionality to gem5 and retain the ability to revision control your own code. The first suggested method relies on the queues feature of Mercurial (the revision control tool used for gem5 development). The second relies on your own source control scheme (you could use mercurial or something else), and instead uses the [[Extras]] functionality in the build process to link extra objects into gem5. In some situations a hybrid approach may be the best one, where the features you're attempting to evaluate are handled via the extras functionality, and minor changes to interfaces are done with Mercurial queues.
  
If you are extending M5 in a way that could be useful to the community, please consider pushing it back upstream. See [[Submitting Contributions]].
+
If you are extending gem5 in a way that could be useful to the community, please consider pushing it back upstream. See [[Submitting Contributions]].
  
 
== Using Mercurial Queues ==
 
== Using Mercurial Queues ==
  
The first method is using [http://hgbook.red-bean.com/hgbookch12.html Mercurial Queues] (MQ).  MQ provides management commands inis to provide management commands to create and apply patches to an upstream source tree. When the underlying source tree is updated (see above), you can remove your patches, get the new changes and reapply your patches very quickly. The patches themselves can be an complete mercurial repository that is revision controlled. It's essential to read the above chapter in the Mercurial manual to understand this process, but briefly you would begin by creating a mercurial queues repository. You can then add patches to the mercurial queues repository and automatically update them based on the changes you've made. With this method it is good to segment changes into logical blocks rather than have one large patch for all your changes. When it comes time to update to a new version of M5 you remove all your patches from the repository, update to the latest version and add re-apply all of your patches. Normally this requires minimal effort. For example:
+
The first method is using [http://hgbook.red-bean.com/hgbookch12.html Mercurial Queues] (MQ).  MQ provides management commands inis to provide management commands to create and apply patches to an upstream source tree. When the underlying source tree is updated (see above), you can remove your patches, get the new changes and reapply your patches very quickly. The patches themselves can be an complete mercurial repository that is revision controlled. It's essential to read the above chapter in the Mercurial manual to understand this process, but briefly you would begin by creating a mercurial queues repository. You can then add patches to the mercurial queues repository and automatically update them based on the changes you've made. With this method it is good to segment changes into logical blocks rather than have one large patch for all your changes. When it comes time to update to a new version of gem5 you remove all your patches from the repository, update to the latest version and add re-apply all of your patches. Normally this requires minimal effort. For example:
 
<pre>
 
<pre>
 
  hg qinit -c
 
  hg qinit -c
Line 21: Line 21:
 
  hg qcommit
 
  hg qcommit
  
  #To update to the latest version of M5
+
  #To update to the latest version of gem5
 
  hg qpop -a
 
  hg qpop -a
 
  hg fetch
 
  hg fetch
Line 31: Line 31:
 
== Using EXTRAS ==
 
== Using EXTRAS ==
  
The other method relies on the [[Extras]] functionality in the build process. This feature allows you to keep new M5 models in a directory of your choosing and have them compile and link code in with the M5 binary from arbitrary directories.  Because the location of this directory is completely independent of the M5 mercurial repository, you can use any revision control system you like, and you can include code that you don't want to release (or that was released under a different license) without worrying about contaminating the M5 repository.
+
The other method relies on the [[Extras]] functionality in the build process. This feature allows you to keep new gem5 models in a directory of your choosing and have them compile and link code in with the gem5 binary from arbitrary directories.  Because the location of this directory is completely independent of the gem5 mercurial repository, you can use any revision control system you like, and you can include code that you don't want to release (or that was released under a different license) without worrying about contaminating the gem5 repository.
  
The drawback of the Extras technique is that it only allows the addition of new source code to M5, not the replacement or modification of any existing source code.
+
The drawback of the Extras technique is that it only allows the addition of new source code to gem5, not the replacement or modification of any existing source code.
  
 
See the [[Extras]] page for details on how to use this feature.
 
See the [[Extras]] page for details on how to use this feature.
  
 
__NOTOC__
 
__NOTOC__

Revision as of 21:43, 22 May 2015

This page describes the methods available to extend gem5 while preserving the ability to update to new versions. If you intend to make any changes to gem5 we strongly advise you to follow one of the following methods. It will save you a great deal of time in the future and allow you to take advantage of new gem5 versions without the error prone process of manually diffing and patching versions.

There are two recommend ways to add your own functionality to gem5 and retain the ability to revision control your own code. The first suggested method relies on the queues feature of Mercurial (the revision control tool used for gem5 development). The second relies on your own source control scheme (you could use mercurial or something else), and instead uses the Extras functionality in the build process to link extra objects into gem5. In some situations a hybrid approach may be the best one, where the features you're attempting to evaluate are handled via the extras functionality, and minor changes to interfaces are done with Mercurial queues.

If you are extending gem5 in a way that could be useful to the community, please consider pushing it back upstream. See Submitting Contributions.

Using Mercurial Queues

The first method is using Mercurial Queues (MQ). MQ provides management commands inis to provide management commands to create and apply patches to an upstream source tree. When the underlying source tree is updated (see above), you can remove your patches, get the new changes and reapply your patches very quickly. The patches themselves can be an complete mercurial repository that is revision controlled. It's essential to read the above chapter in the Mercurial manual to understand this process, but briefly you would begin by creating a mercurial queues repository. You can then add patches to the mercurial queues repository and automatically update them based on the changes you've made. With this method it is good to segment changes into logical blocks rather than have one large patch for all your changes. When it comes time to update to a new version of gem5 you remove all your patches from the repository, update to the latest version and add re-apply all of your patches. Normally this requires minimal effort. For example:

 hg qinit -c
 hg qnew my_new_feature.diff
 echo "// Not so much a new feature as an additional line in the source tree" >> src/sim/main.cc
 hg qrefresh # my_new_feature.diff now contains the the extra line in the source tree

 # Remove the patch by executing
 hg qpop
 # Reapply the patch by executing
 hg qpush
 # Commit the changes to the path
 hg qcommit

 #To update to the latest version of gem5
 hg qpop -a
 hg fetch
 hg qpush -a

 # Again PLEASE read the manual

Using EXTRAS

The other method relies on the Extras functionality in the build process. This feature allows you to keep new gem5 models in a directory of your choosing and have them compile and link code in with the gem5 binary from arbitrary directories. Because the location of this directory is completely independent of the gem5 mercurial repository, you can use any revision control system you like, and you can include code that you don't want to release (or that was released under a different license) without worrying about contaminating the gem5 repository.

The drawback of the Extras technique is that it only allows the addition of new source code to gem5, not the replacement or modification of any existing source code.

See the Extras page for details on how to use this feature.