Cleaned up and commented code. I think we are ready to merge with head.

dev/baddev.hh:
dev/pcidev.hh:
dev/tsunami.hh:
dev/tsunami_cchip.hh:
dev/tsunami_io.hh:
dev/tsunami_pchip.hh:
    Added doxygen comments
dev/pciconfigall.hh:
    Added doxygen comments. Made the hlist of devices private and provided
    members to modify the data.
dev/pcidev.cc:
    updated for change in pciconfigall
dev/tsunami_pchip.cc:
    Deleted commented out code we don't need
kern/linux/linux_syscalls.cc:
    Simplified the number -> name conversion.
kern/linux/linux_syscalls.hh:
    Removed StandardNumber and replaced with Number.
kern/linux/linux_system.cc:
kern/linux/linux_system.hh:
    LinuxSkipIdeDelay50msEvent was simply the same as the SkipFunc event,
    so I removed it. Same with with LinuxSkipFuncEvent.

--HG--
extra : convert_revision : 1508c335f87d90373f5772f3a0407ea13e858d7e

9 files changed, 407 insertions, 27 deletions

diff --git a/dev/baddev.hh b/dev/baddev.hh
index ed896d792..e0304d5d5 100644
--- a/dev/baddev.hh
+++ b/dev/baddev.hh
@@ -51,14 +51,35 @@ class BadDevice : public FunctionalMemory
     std::string devname;
 
   public:
-    /**
-     * The default constructor.
-     */
+     /**
+      * Constructor for the Baddev Class.
+      * @param name name of the object
+      * @param a base address of the write
+      * @param mmu the memory controller
+      * @param devicename device that is not implemented
+      */
     BadDevice(const std::string &name, Addr a, MemoryController *mmu,
               const std::string &devicename);
 
+    /**
+      * On a read event we just panic aand hopefully print a
+      * meaningful error message.
+      * @param req Contains the address to read from.
+      * @param data A pointer to write the read data to.
+      * @return The fault condition of the access.
+      */
     virtual Fault read(MemReqPtr &req, uint8_t *data);
+
+    /**
+      * On a write event we just panic aand hopefully print a
+      * meaningful error message.
+      * @param req Contains the address to write to.
+      * @param data The data to write.
+      * @return The fault condition of the access.
+      */
     virtual Fault write(MemReqPtr &req, const uint8_t *data);
+
+    /** @todo add serialize/unserialize */
 };
 
 #endif // __BADDEV_HH__
diff --git a/dev/pciconfigall.hh b/dev/pciconfigall.hh
index 6df1e2fe7..6a31a9e73 100644
--- a/dev/pciconfigall.hh
+++ b/dev/pciconfigall.hh
@@ -37,8 +37,8 @@
 #include "mem/functional_mem/functional_memory.hh"
 #include "dev/pcireg.h"
 
-#define MAX_PCI_DEV     32
-#define MAX_PCI_FUNC    8
+static const uint32_t MAX_PCI_DEV = 32;
+static const uint32_t MAX_PCI_FUNC = 8;
 
 class PciDev;
 
@@ -55,22 +55,72 @@ class PciConfigAll : public FunctionalMemory
     Addr addr;
     static const Addr size = 0xffffff;
 
-  public:
     /**
       * Pointers to all the devices that are registered with this
       * particular config space.
       */
     PciDev* devices[MAX_PCI_DEV][MAX_PCI_FUNC];
 
+  public:
     /**
-      * The default constructor.
-      */
+     * Constructor for PCIConfigAll
+     * @param name name of the object
+     * @param a base address of the write
+     * @param mmu the memory controller
+     */
     PciConfigAll(const std::string &name, Addr a, MemoryController *mmu);
 
+
+    /**
+     * Check if a device exists.
+     * @param pcidev PCI device to check
+     * @param pcifunc PCI function to check
+     * @return true if device exists, false otherwise
+     */
+    bool deviceExists(uint32_t pcidev, uint32_t pcifunc)
+                     { return devices[pcidev][pcifunc] != NULL ? true : false; }
+
+    /**
+     * Registers a device with the config space object.
+     * @param pcidev PCI device to register
+     * @param pcifunc PCI function to register
+     * @param device device to register
+     */
+    void registerDevice(uint8_t pcidev, uint8_t pcifunc, PciDev *device)
+                        { devices[pcidev][pcifunc] = device; }
+
+    /**
+     * Read something in PCI config space. If the device does not exist
+     * -1 is returned, if the device does exist its PciDev::ReadConfig (or the
+     * virtual function that overrides) it is called.
+     * @param req Contains the address of the field to read.
+     * @param data Return the field read.
+     * @return The fault condition of the access.
+     */
     virtual Fault read(MemReqPtr &req, uint8_t *data);
+
+    /**
+     * Write to PCI config spcae. If the device does not exit the simulator
+     * panics. If it does it is passed on the PciDev::WriteConfig (or the virtual
+     * function that overrides it).
+     * @param req Contains the address to write to.
+     * @param data The data to write.
+     * @return The fault condition of the access.
+     */
+
     virtual Fault write(MemReqPtr &req, const uint8_t *data);
 
+    /**
+     * Serialize this object to the given output stream.
+     * @param os The stream to serialize to.
+     */
     virtual void serialize(std::ostream &os);
+
+    /**
+     * Reconstruct the state of this object from a checkpoint.
+     * @param cp The checkpoint use.
+     * @param section The section name of this object
+     */
     virtual void unserialize(Checkpoint *cp, const std::string &section);
 
 };
diff --git a/dev/pcidev.cc b/dev/pcidev.cc
index 9d6208d6b..8d2828809 100644
--- a/dev/pcidev.cc
+++ b/dev/pcidev.cc
@@ -64,10 +64,10 @@ PciDev::PciDev(const string &name, MemoryController *mmu, PciConfigAll *cf,
         panic("NULL pointer to configuration data");
 
     // Setup pointer in config space to point to this entry
-    if (cf->devices[dev][func] != NULL)
+    if (cf->deviceExists(dev,func))
         panic("Two PCI devices occuping same dev: %#x func: %#x", dev, func);
     else
-        cf->devices[dev][func] = this;
+        cf->registerDevice(dev, func, this);
 }
 
 void
diff --git a/dev/pcidev.hh b/dev/pcidev.hh
index f8192db3c..1c4de18ad 100644
--- a/dev/pcidev.hh
+++ b/dev/pcidev.hh
@@ -39,9 +39,17 @@
 class PciConfigAll;
 class MemoryController;
 
+
+/**
+ * This class encapulates the first 64 bytes of a singles PCI
+ * devices config space that in configured by the configuration file.
+ */
 class PciConfigData : public SimObject
 {
   public:
+    /**
+     * Constructor to initialize the devices config space to 0.
+     */
     PciConfigData(const std::string &name)
         : SimObject(name)
     {
@@ -50,8 +58,13 @@ class PciConfigData : public SimObject
         memset(BARSize, 0, sizeof(BARSize));
     }
 
+    /** The first 64 bytes */
     PCIConfig config;
+
+    /** The size of the BARs */
     uint32_t BARSize[6];
+
+    /** The addresses of the BARs */
     Addr BARAddrs[6];
 };
 
@@ -66,17 +79,50 @@ class PciDev : public DmaDevice
 {
   protected:
     MemoryController *mmu;
+    /** A pointer to the configspace all object that calls
+     * us when a read comes to this particular device/function.
+     */
     PciConfigAll *configSpace;
+
+    /**
+     * A pointer to the object that contains the first 64 bytes of
+     * config space
+     */
     PciConfigData *configData;
+
+    /** The bus number we are on */
     uint32_t busNum;
+
+    /** The device number we have */
     uint32_t deviceNum;
+
+    /** The function number */
     uint32_t functionNum;
 
+    /** The current config space. Unlike the PciConfigData this is updated
+     * during simulation while continues to refelect what was in the config file.
+     */
     PCIConfig config;
+
+    /** The size of the BARs */
     uint32_t BARSize[6];
+
+    /** The current address mapping of the BARs */
     Addr BARAddrs[6];
 
   public:
+    /**
+     * Constructor for PCI Dev. This function copies data from the config file
+     * object PCIConfigData and registers the device with a PciConfigAll object.
+     * @param name name of the object
+     * @param mmu a pointer to the memory controller
+     * @param cf a pointer to the config space object that this device need to
+     *           register with
+     * @param cd A pointer to the config space values specified in the conig file
+     * @param bus the bus this device is on
+     * @param dev the device id of this device
+     * @param func the function number of this device
+     */
     PciDev(const std::string &name, MemoryController *mmu, PciConfigAll *cf,
            PciConfigData *cd, uint32_t bus, uint32_t dev, uint32_t func);
 
@@ -87,10 +133,38 @@ class PciDev : public DmaDevice
         return No_Fault;
     }
 
+    /**
+     * Write to the PCI config space data that is stored locally. This may be
+     * overridden by the device but at some point it will eventually call this
+     * for normal operations that it does not need to override.
+     * @param offset the offset into config space
+     * @param size the size of the write
+     * @param data the data to write
+     */
     virtual void WriteConfig(int offset, int size, uint32_t data);
+
+
+    /**
+     * Read from the PCI config space data that is stored locally. This may be
+     * overridden by the device but at some point it will eventually call this
+     * for normal operations that it does not need to override.
+     * @param offset the offset into config space
+     * @param size the size of the read
+     * @param data pointer to the location where the read value should be stored
+     */
     virtual void ReadConfig(int offset, int size, uint8_t *data);
 
+    /**
+     * Serialize this object to the given output stream.
+     * @param os The stream to serialize to.
+     */
     virtual void serialize(std::ostream &os);
+
+    /**
+     * Reconstruct the state of this object from a checkpoint.
+     * @param cp The checkpoint use.
+     * @param section The section name of this object
+     */
     virtual void unserialize(Checkpoint *cp, const std::string &section);
 };
 
diff --git a/dev/tsunami.hh b/dev/tsunami.hh
index 476d7e18e..c5dbe797b 100644
--- a/dev/tsunami.hh
+++ b/dev/tsunami.hh
@@ -95,10 +95,27 @@ class Tsunami : public Platform
     Tsunami(const std::string &name, System *s, IntrControl *intctrl,
             PciConfigAll *pci, int intrFreq);
 
+    /**
+     * Cause the cpu to post a serial interrupt to the CPU.
+     */
     virtual void postConsoleInt();
+
+    /**
+     * Clear a posted CPU interrupt (id=55)
+     */
     virtual void clearConsoleInt();
 
+    /**
+     * Serialize this object to the given output stream.
+     * @param os The stream to serialize to.
+     */
     virtual void serialize(std::ostream &os);
+
+    /**
+     * Reconstruct the state of this object from a checkpoint.
+     * @param cp The checkpoint use.
+     * @param section The section name of this object
+     */
     virtual void unserialize(Checkpoint *cp, const std::string &section);
 };
 
diff --git a/dev/tsunami_cchip.hh b/dev/tsunami_cchip.hh
index adb05a572..381fb58f1 100644
--- a/dev/tsunami_cchip.hh
+++ b/dev/tsunami_cchip.hh
@@ -42,7 +42,10 @@
 class TsunamiCChip : public FunctionalMemory
 {
   private:
+    /** The base address of this device */
     Addr addr;
+
+    /** The size of mappad from the above address */
     static const Addr size = 0xfff;
 
   protected:
@@ -72,23 +75,75 @@ class TsunamiCChip : public FunctionalMemory
      */
     uint64_t drir;
 
+    /**
+     * The MISC register contains the CPU we are currently on
+     * as well as bits to ack RTC and IPI interrupts.
+     */
     uint64_t misc;
 
+    /** Count of the number of pending IPIs on a CPU */
     uint64_t ipiInterrupting[Tsunami::Max_CPUs];
+
+    /** Indicator of which CPUs have had an RTC interrupt */
     bool RTCInterrupting[Tsunami::Max_CPUs];
 
   public:
+    /**
+     * Initialize the Tsunami CChip by setting all of the
+     * device register to 0.
+     * @param name name of this device.
+     * @param t pointer back to the Tsunami object that we belong to.
+     * @param a address we are mapped at.
+     * @param mmu pointer to the memory controller that sends us events.
+     */
     TsunamiCChip(const std::string &name, Tsunami *t, Addr a,
                  MemoryController *mmu);
 
+    /**
+      * Process a read to the CChip.
+      * @param req Contains the address to read from.
+      * @param data A pointer to write the read data to.
+      * @return The fault condition of the access.
+      */
     virtual Fault read(MemReqPtr &req, uint8_t *data);
+
+
+    /**
+      * Process a write to the CChip.
+      * @param req Contains the address to write to.
+      * @param data The data to write.
+      * @return The fault condition of the access.
+      */
     virtual Fault write(MemReqPtr &req, const uint8_t *data);
 
+    /**
+     * post an RTC interrupt to the CPU
+     */
     void postRTC();
+
+    /**
+     * post an interrupt to the CPU.
+     * @param interrupt the interrupt number to post (0-64)
+     */
     void postDRIR(uint32_t interrupt);
+
+    /**
+     * clear an interrupt previously posted to the CPU.
+     * @param interrupt the interrupt number to post (0-64)
+     */
     void clearDRIR(uint32_t interrupt);
 
+    /**
+     * Serialize this object to the given output stream.
+     * @param os The stream to serialize to.
+     */
     virtual void serialize(std::ostream &os);
+
+    /**
+     * Reconstruct the state of this object from a checkpoint.
+     * @param cp The checkpoint use.
+     * @param section The section name of this object
+     */
     virtual void unserialize(Checkpoint *cp, const std::string &section);
 };
 
diff --git a/dev/tsunami_io.hh b/dev/tsunami_io.hh
index 90bef2b86..1dd7762e3 100644
--- a/dev/tsunami_io.hh
+++ b/dev/tsunami_io.hh
@@ -33,78 +33,145 @@
 #ifndef __TSUNAMI_DMA_HH__
 #define __TSUNAMI_DMA_HH__
 
-#define RTC_RATE 1024
-
 #include "mem/functional_mem/functional_memory.hh"
 #include "dev/tsunami.hh"
 
+/** How often the RTC interrupts */
+static const int RTC_RATE  = 1024;
+
 /*
- * Tsunami I/O device
+ * Tsunami I/O device is a catch all for all the south bridge stuff we care
+ * to implement.
  */
 class TsunamiIO : public FunctionalMemory
 {
   private:
+    /** The base address of this device */
     Addr addr;
+
+    /** The size of mappad from the above address */
     static const Addr size = 0xff;
 
     struct tm tm;
 
-    // In Tsunami RTC only has two i/o ports
-    // one  for data and one for address, so you
-    // write the address and then read/write the data
+    /** In Tsunami RTC only has two i/o ports one for data and one for address,
+     * so you write the address and then read/write the data. This store the
+     * address you are going to be reading from on a read.
+     */
     uint8_t RTCAddress;
 
   protected:
 
+    /**
+     * The ClockEvent is handles the PIT interrupts
+     */
     class ClockEvent : public Event
     {
       protected:
+        /** how often the PIT fires */
         Tick interval;
+        /** The mode of the PIT */
         uint8_t mode;
+        /** The status of the PIT */
         uint8_t status;
 
       public:
+        /**
+         * Just set the mode to 0
+         */
         ClockEvent();
 
+        /**
+         * processs the timer event
+         */
         virtual void process();
+
+        /**
+         * Returns a description of this event
+         * @return the description
+         */
         virtual const char *description();
+
+        /**
+         * Schedule a timer interrupt to occur sometime in the future.
+         */
         void Program(int count);
+
+        /**
+         * Write the mode bits of the PIT.
+         * @param mode the new mode
+         */
         void ChangeMode(uint8_t mode);
+
+        /**
+         * The current PIT status.
+         * @return the status of the PIT
+         */
         uint8_t Status();
 
     };
 
+    /**
+     * Process RTC timer events and generate interrupts appropriately.
+     */
     class RTCEvent : public Event
     {
       protected:
-        Tsunami* tsunami;
+          /** A pointer back to tsunami to create interrupt the processor. */
+          Tsunami* tsunami;
       public:
-        RTCEvent(Tsunami* t);
+          /** RTC Event initializes the RTC event by scheduling an event
+           * RTC_RATE times pre second. */
+          RTCEvent(Tsunami* t);
 
-        virtual void process();
-        virtual const char *description();
+          /**
+           * Interrupth the processor and reschedule the event.
+           * */
+          virtual void process();
+
+          /**
+           * Return a description of this event.
+           * @return a description
+           */
+          virtual const char *description();
     };
 
+    /** uip UpdateInProgess says that the rtc is updating, but we just fake it
+     * by alternating it on every read of the bit since we are going to
+     * override the loop_per_jiffy time that it is trying to use the UIP to
+     * calculate.
+     */
     uint8_t uip;
 
+    /** Mask of the PIC1 */
     uint8_t mask1;
+
+    /** Mask of the PIC2 */
     uint8_t mask2;
+
+    /** Mode of PIC1. Not used for anything */
     uint8_t mode1;
+
+    /** Mode of PIC2. Not used for anything */
     uint8_t mode2;
 
-    uint8_t picr; //Raw PIC interrput register, before masking
+    /** Raw PIC interrupt register before masking */
+    uint8_t picr; //Raw PIC interrput register
+
+    /** Is the pic interrupting right now or not. */
     bool picInterrupting;
 
+    /** A pointer to the Tsunami device which be belong to */
     Tsunami *tsunami;
 
-    /*
+    /**
      * This timer is initilized, but after I wrote the code
      * it doesn't seem to be used again, and best I can tell
      * it too is not connected to any interrupt port
      */
     ClockEvent timer0;
 
-    /*
+    /**
      * This timer is used to control the speaker, which
      * we normally could care less about, however it is
      * also used to calculated the clockspeed and hense
@@ -114,26 +181,77 @@ class TsunamiIO : public FunctionalMemory
      */
     ClockEvent timer2;
 
+    /** This is the event used to interrupt the cpu like an RTC.  */
     RTCEvent rtc;
 
+    /** The interval is set via two writes to the PIT.
+     * This variable contains a flag as to how many writes have happened, and
+     * the time so far.
+     */
     uint32_t timerData;
 
 
   public:
+    /** Return the freqency of the RTC */
     uint32_t  frequency() const { return RTC_RATE; }
 
+
+    /**
+     * Initialize all the data for devices supported by Tsunami I/O.
+     * @param name name of this device.
+     * @param t pointer back to the Tsunami object that we belong to.
+     * @param init_time Time (as in seconds since 1970) to set RTC to.
+     * @param a address we are mapped at.
+     * @param mmu pointer to the memory controller that sends us events.
+     */
     TsunamiIO(const std::string &name, Tsunami *t, time_t init_time,
               Addr a, MemoryController *mmu);
 
+    /**
+     * Create the tm struct from seconds since 1970
+     */
     void set_time(time_t t);
 
+    /**
+      * Process a read to one of the devices we are emulating.
+      * @param req Contains the address to read from.
+      * @param data A pointer to write the read data to.
+      * @return The fault condition of the access.
+      */
     virtual Fault read(MemReqPtr &req, uint8_t *data);
+
+    /**
+      * Process a write to one of the devices we emulate.
+      * @param req Contains the address to write to.
+      * @param data The data to write.
+      * @return The fault condition of the access.
+      */
     virtual Fault write(MemReqPtr &req, const uint8_t *data);
 
+    /**
+     * Post an PIC interrupt to the CPU via the CChip
+     * @param bitvector interrupt to post.
+     */
     void postPIC(uint8_t bitvector);
+
+    /**
+     * Clear a posted interrupt
+     * @param bitvector interrupt to clear
+     */
     void clearPIC(uint8_t bitvector);
 
+    /**
+     * Serialize this object to the given output stream.
+     * @param os The stream to serialize to.
+     */
     virtual void serialize(std::ostream &os);
+
+
+    /**
+     * Reconstruct the state of this object from a checkpoint.
+     * @param cp The checkpoint use.
+     * @param section The section name of this object
+     */
     virtual void unserialize(Checkpoint *cp, const std::string &section);
 };
 
diff --git a/dev/tsunami_pchip.cc b/dev/tsunami_pchip.cc
index dabf6bf40..2ac3cae86 100644
--- a/dev/tsunami_pchip.cc
+++ b/dev/tsunami_pchip.cc
@@ -47,8 +47,6 @@ TsunamiPChip::read(MemReqPtr &req, uint8_t *data)
             req->vaddr, req->size);
 
     Addr daddr = (req->paddr - (addr & PA_IMPL_MASK)) >> 6;
-//    ExecContext *xc = req->xc;
-//    int cpuid = xc->cpu_id;
 
     switch (req->size) {
 
diff --git a/dev/tsunami_pchip.hh b/dev/tsunami_pchip.hh
index 3ed66c54c..44f145a60 100644
--- a/dev/tsunami_pchip.hh
+++ b/dev/tsunami_pchip.hh
@@ -42,28 +42,75 @@
 class TsunamiPChip : public FunctionalMemory
 {
   private:
+    /** The base address of this device */
     Addr addr;
+
+    /** The size of mappad from the above address */
     static const Addr size = 0xfff;
 
   protected:
+    /**
+     * pointer to the tsunami object.
+     * This is our access to all the other tsunami
+     * devices.
+     */
     Tsunami *tsunami;
 
+    /** Window Base addresses */
     uint64_t wsba[4];
+
+    /** Window masks */
     uint64_t wsm[4];
+
+    /** Translated Base Addresses */
     uint64_t tba[4];
 
   public:
+    /**
+     * Register the PChip with the mmu and init all wsba, wsm, and tba to 0
+     * @param name the name of thes device
+     * @param t a pointer to the tsunami device
+     * @param a the address which we respond to
+     * @param mmu the mmu we are to register with
+     */
     TsunamiPChip(const std::string &name, Tsunami *t, Addr a,
                  MemoryController *mmu);
 
-    // @todo This hack does a quick and dirty translation of the PCI bus address to
-    //  a valid DMA address.  This is described in 10-10 of the Tsunami book, should be fixed
+    /**
+     * Translate a PCI bus address to a memory address for DMA.
+     * @todo Andrew says this needs to be fixed. What's wrong with it?
+     * @param busAddr PCI address to translate.
+     * @return memory system address
+     */
     Addr translatePciToDma(Addr busAddr);
 
+     /**
+      * Process a read to the PChip.
+      * @param req Contains the address to read from.
+      * @param data A pointer to write the read data to.
+      * @return The fault condition of the access.
+      */
     virtual Fault read(MemReqPtr &req, uint8_t *data);
+
+    /**
+      * Process a write to the PChip.
+      * @param req Contains the address to write to.
+      * @param data The data to write.
+      * @return The fault condition of the access.
+      */
     virtual Fault write(MemReqPtr &req, const uint8_t *data);
 
+    /**
+     * Serialize this object to the given output stream.
+     * @param os The stream to serialize to.
+     */
     virtual void serialize(std::ostream &os);
+
+    /**
+     * Reconstruct the state of this object from a checkpoint.
+     * @param cp The checkpoint use.
+     * @param section The section name of this object
+     */
     virtual void unserialize(Checkpoint *cp, const std::string &section);
 };