From 4dfc312d6df91129a4007e588678d076073d390d Mon Sep 17 00:00:00 2001
From: Yan Lee <yanlee@google.com>
Date: Thu, 16 Feb 2023 20:56:19 -0800
Subject: [PATCH] base: extensible: add example codes of extension

Change-Id: Iaab1f2998a3f621b86d63bed7274373ba433d71c
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/68017
Maintainer: Jason Lowe-Power <power.jg@gmail.com>
Reviewed-by: Jason Lowe-Power <power.jg@gmail.com>
Tested-by: kokoro <noreply+kokoro@google.com>
---
 src/base/extensible.hh | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/src/base/extensible.hh b/src/base/extensible.hh
index eb79c71be3..e80103c577 100644
--- a/src/base/extensible.hh
+++ b/src/base/extensible.hh
@@ -27,6 +27,10 @@
 
 /* @file
  * Extensible Object Base Class Declaration
+ *
+ * This class can be used to add an "extension" field to packet/request which
+ * will be passed along with the original packet/request pointer. This allows
+ * developers to extend packet/request without modifying the original class.
  */
 
 #ifndef __BASE_EXTENSIBLE_HH__
@@ -69,6 +73,33 @@ class ExtensionBase
  * This is the extension for carrying additional information.
  * Each type of extension will have a unique extensionID.
  * This extensionID will assign to base class for comparsion.
+ *
+ * Example usage:
+ *
+ *   class MyTarget : Extensible<MyTarget> {};
+ *
+ *   class MyExtension : public Extension<MyTarget, MyExtension>
+ *   {
+ *     public:
+ *       MyExtension();
+ *       std::unique_ptr<ExtensionBase> clone() const override;
+ *       uint32_t getData();
+ *
+ *     private:
+ *       uint32_t data_;;
+ *   };
+ *
+ *   std::unique_ptr<MyTarget> mytarget(new MyTarget);
+ *   std::shared_ptr<MyExtension> myext(new MyExtension);
+ *   mytarget->setExtension(myext);
+ *
+ *   std::shared_ptr<MyExtension> ext = mytarget->getExtension<MyExtension>();
+ *   uint32_t data = ext->getData();
+ *   mytarget->removeExtension<MyExtension>();
+ *
+ *   In the example above, MyTarget can carry an extension named MyExtension,
+ *   which contains an additional data field. This could be applicated to any
+ *   debug information or any data field in any protocol.
  */
 template <typename Target, typename T>
 class Extension : public ExtensionBase