More documentation, mostly to the PCI

diff --git a/Kernel/Doxyfile.api b/Kernel/Doxyfile.api
index 319804c..56b80d2 100644 (file)
--- a/Kernel/Doxyfile.api
+++ b/Kernel/Doxyfile.api
@@ -571,7 +571,8 @@ INPUT                  = include/apidoc_mainpage.h \
                          include/modules.h \
                          include/vfs.h include/vfs_ext.h \
                                                 include/fs_devfs.h \
-                         include/iocache.h include/
+                         include/iocache.h \
+                         include/apidoc/arch_x86.h
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 

diff --git a/Kernel/Makefile.BuildNum b/Kernel/Makefile.BuildNum
index a4aa121..c43737f 100644 (file)
--- a/Kernel/Makefile.BuildNum
+++ b/Kernel/Makefile.BuildNum
@@ -1 +1 @@
-BUILD_NUM = 1525
+BUILD_NUM = 1526

diff --git a/Kernel/drv/pci.c b/Kernel/drv/pci.c
index 9823208..9f1dd6e 100644 (file)
--- a/Kernel/drv/pci.c
+++ b/Kernel/drv/pci.c
@@ -12,18 +12,21 @@
 #define        LIST_DEVICES    1\r
 \r
 // === STRUCTURES ===\r
-typedef struct s_pciDevice {\r
+typedef struct sPCIDevice\r
+{\r
        Uint16  bus, slot, fcn;\r
        Uint16  vendor, device;\r
        union {\r
-               struct {Uint8 class, subclass;};\r
+               struct {\r
+                       Uint8 class, subclass;\r
+               };\r
                Uint16  oc;\r
        };\r
        Uint16  revision;\r
        Uint32  ConfigCache[256/4];\r
        char    Name[8];\r
        tVFS_Node       Node;\r
-} t_pciDevice;\r
+} tPCIDevice;\r
 \r
 // === CONSTANTS ===\r
 #define SPACE_STEP     5\r
@@ -46,7 +49,7 @@ Uint32        PCI_GetBAR4(int id);
 Uint32 PCI_GetBAR5(int id);\r
 Uint16 PCI_AssignPort(int id, int bar, int count);\r
 \r
- int   PCI_EnumDevice(Uint16 bus, Uint16 dev, Uint16 fcn, t_pciDevice *info);\r
+ int   PCI_EnumDevice(Uint16 bus, Uint16 dev, Uint16 fcn, tPCIDevice *info);\r
 Uint32 PCI_CfgReadDWord(Uint16 bus, Uint16 dev, Uint16 func, Uint16 offset);\r
 void   PCI_CfgWriteDWord(Uint16 bus, Uint16 dev, Uint16 func, Uint16 offset, Uint32 data);\r
 Uint16 PCI_CfgReadWord(Uint16 bus, Uint16 dev, Uint16 func, Uint16 offset);\r
@@ -57,7 +60,7 @@ Uint8 PCI_CfgReadByte(Uint16 bus, Uint16 dev, Uint16 func, Uint16 offset);
  int   giPCI_BusCount = 1;\r
  int   giPCI_InodeHandle = -1;\r
  int   giPCI_DeviceCount = 0;\r
-t_pciDevice    *gPCI_Devices = NULL;\r
+tPCIDevice     *gPCI_Devices = NULL;\r
 tDevFS_Driver  gPCI_DriverStruct = {\r
        NULL, "pci",\r
        {\r
@@ -80,7 +83,7 @@ int PCI_Install(char **Arguments)
 {\r
         int    bus, dev, fcn, i;\r
         int    space = 0;\r
-       t_pciDevice     devInfo;\r
+       tPCIDevice      devInfo;\r
        void    *tmpPtr = NULL;\r
        \r
        // Build Portmap\r
@@ -107,7 +110,7 @@ int PCI_Install(char **Arguments)
                                if(giPCI_DeviceCount == space)\r
                                {\r
                                        space += SPACE_STEP;\r
-                                       tmpPtr = realloc(gPCI_Devices, space*sizeof(t_pciDevice));\r
+                                       tmpPtr = realloc(gPCI_Devices, space*sizeof(tPCIDevice));\r
                                        if(tmpPtr == NULL)\r
                                                break;\r
                                        gPCI_Devices = tmpPtr;\r
@@ -121,7 +124,7 @@ int PCI_Install(char **Arguments)
                                        giPCI_BusCount++;\r
                                }\r
                                devInfo.Node.Inode = giPCI_DeviceCount;\r
-                               memcpy(&gPCI_Devices[giPCI_DeviceCount], &devInfo, sizeof(t_pciDevice));\r
+                               memcpy(&gPCI_Devices[giPCI_DeviceCount], &devInfo, sizeof(tPCIDevice));\r
                                giPCI_DeviceCount ++;\r
                                #if LIST_DEVICES\r
                                Log("[PCI ] Device %i,%i:%i => 0x%x:0x%x",\r
@@ -144,7 +147,7 @@ int PCI_Install(char **Arguments)
        if(giPCI_DeviceCount == 0)\r
                return MODULE_ERR_NOTNEEDED;\r
        \r
-       tmpPtr = realloc(gPCI_Devices, giPCI_DeviceCount*sizeof(t_pciDevice));\r
+       tmpPtr = realloc(gPCI_Devices, giPCI_DeviceCount*sizeof(tPCIDevice));\r
        if(tmpPtr == NULL)\r
                return MODULE_ERR_MALLOC;\r
        gPCI_Devices = tmpPtr;\r
@@ -369,7 +372,7 @@ Uint16 PCI_AssignPort(int id, int bar, int count)
        Uint16  portVals;\r
         int    gran=0;\r
         int    i, j;\r
-       t_pciDevice     *dev;\r
+       tPCIDevice      *dev;\r
        \r
        //LogF("PCI_AssignPort: (id=%i,bar=%i,count=%i)\n", id, bar, count);\r
        \r
@@ -426,9 +429,9 @@ Uint16 PCI_AssignPort(int id, int bar, int count)
 }\r
 \r
 /**\r
- * \fn int     PCI_EnumDevice(Uint16 bus, Uint16 slot, Uint16 fcn, t_pciDevice *info)\r
+ * \fn int     PCI_EnumDevice(Uint16 bus, Uint16 slot, Uint16 fcn, tPCIDevice *info)\r
  */\r
-int    PCI_EnumDevice(Uint16 bus, Uint16 slot, Uint16 fcn, t_pciDevice *info)\r
+int    PCI_EnumDevice(Uint16 bus, Uint16 slot, Uint16 fcn, tPCIDevice *info)\r
 {\r
        Uint16  vendor;\r
         int    i;\r

diff --git a/Kernel/include/drv_pci.h b/Kernel/include/drv_pci.h
index b539430..d3eb8a2 100644 (file)
--- a/Kernel/include/drv_pci.h
+++ b/Kernel/include/drv_pci.h
@@ -1,12 +1,16 @@
-/*\r
- * Acess 2\r
- * PCI Bus Driver\r
- * drv_pci.h\r
+/**\r
+ * \file drv_pci.h\r
+ * \brief PCI Bus Driver\r
+ * \author John Hodge (thePowersGang)\r
  */\r
 #ifndef _DRV_PCI_H\r
 #define _DRV_PCI_H\r
 \r
-enum e_PciClasses {\r
+/**\r
+ * \brief PCI Class Codes\r
+ */\r
+enum ePCIClasses\r
+{\r
        PCI_CLASS_PRE20 = 0x00,\r
        PCI_CLASS_STORAGE,\r
        PCI_CLASS_NETWORK,\r
@@ -22,13 +26,20 @@ enum e_PciClasses {
        PCI_CLASS_SERIALBUS,\r
        PCI_CLASS_MISC = 0xFF\r
 };\r
-enum e_PciOverClasses {\r
+\r
+enum ePCIOverClasses\r
+{\r
        PCI_OC_PCIBRIDGE = 0x0604,\r
        PCI_OC_SCSI = 0x0100\r
 };\r
 \r
-\r
+/**\r
+ * \brief Count PCI Devices\r
+ * \r
+ * Counts the number of devices with specified Vendor and Device IDs\r
+ */\r
 extern int     PCI_CountDevices(Uint16 vendor, Uint16 device, Uint16 fcn);\r
+\r
 extern int     PCI_GetDevice(Uint16 vendor, Uint16 device, Uint16 fcn, int idx);\r
 extern int     PCI_GetDeviceByClass(Uint16 class, Uint16 mask, int prev);\r
 extern Uint8   PCI_GetIRQ(int id);\r

diff --git a/Kernel/include/vfs.h b/Kernel/include/vfs.h
index 337d8e7..47cbe19 100644 (file)
--- a/Kernel/include/vfs.h
+++ b/Kernel/include/vfs.h
@@ -5,6 +5,16 @@
 /**
  * \file vfs.h
  * \brief Acess VFS Layer
+ * 
+ * The Acess Virtual File System (VFS) provides abstraction of multiple
+ * physical filesystems, network storage and devices (both hardware and
+ * virtual) to the user.
+ * 
+ * The core of the VFS is the concept of a \ref tVFS_Node "VFS Node".
+ * A VFS Node represents a "file" in the VFS tree, this can be any sort
+ * of file (an ordinary file, a directory, a symbolic link or a device)
+ * depending on the bits set in the \ref tVFS_Node.Flags Flags field.
+ * - For more information see "VFS Node Flags"
  */
 #ifndef _VFS_H
 #define _VFS_H
@@ -12,24 +22,51 @@
 #include <acess.h>
 
 /**
- * \name VFS Node Flags
+ * \name tVFS_Node Flags
+ * \brief Flag values for tVFS_Node.Flags
  * \{
  */
-#define VFS_FFLAG_READONLY     0x01    //!< Read-only file
-#define VFS_FFLAG_DIRECTORY    0x02    //!< Directory
-#define VFS_FFLAG_SYMLINK      0x04    //!< Symbolic Link
+//! \todo Is this still needed
+#define VFS_FFLAG_READONLY     0x01    //!< Readonly File
+/**
+ * \brief Directory Flag
+ * 
+ * This flag marks the tVFS_Node as describing a directory, and says
+ * that the tVFS_Node.FindDir, tVFS_Node.ReadDir, tVFS_Node.MkNod and
+ * tVFS_Node.Relink function pointers are valid.
+ * For a directory the tVFS_Node.Size field contains the number of files
+ * within the directory, or -1 for undetermined.
+ */
+#define VFS_FFLAG_DIRECTORY    0x02
+/**
+ * \brief Symbolic Link Flag
+ * 
+ * Marks a file as a symbolic link
+ */
+#define VFS_FFLAG_SYMLINK      0x04
 /**
  * \}
  */
 
 /**
  * \brief VFS Node
- * \todo Complete / Finalise
+ * 
+ * This structure provides the VFS with the functions required to read/write
+ * the file (or directory) that it represents.
  */
-typedef struct sVFS_Node {     
-       Uint64  Inode;  //!< Inode ID
+typedef struct sVFS_Node {
+       /**
+        * \name Identifiers
+        * \brief Fields used by the driver to identify what data this node
+        *        corresponds to.
+        * \{
+        */
+       Uint64  Inode;  //!< Inode ID (Essentially another ImplInt)
        Uint    ImplInt;        //!< Implementation Usable Integer
        void    *ImplPtr;       //!< Implementation Usable Pointer
+       /**
+        * \}
+        */
        
         int    ReferenceCount; //!< Number of times the node is used
        
@@ -37,16 +74,35 @@ typedef struct sVFS_Node {
        
        Uint32  Flags;  //!< File Flags
        
+       /**
+        * \name Times
+        * \{
+        */
        Sint64  ATime;  //!< Last Accessed Time
        Sint64  MTime;  //!< Last Modified Time
        Sint64  CTime;  //!< Creation Time
+       /**
+        * \}
+        */
        
-       Uint    UID;    //!< Owning User
-       Uint    GID;    //!< Owning Group
+       /**
+        * \name Access controll
+        * \{
+        */
+       tUID    UID;    //!< ID of Owning User
+       tGID    GID;    //!< ID of Owning Group
        
         int    NumACLs;        //!< Number of ACL entries
-       tVFS_ACL        *ACLs;  //!< ACL Entries
+       tVFS_ACL        *ACLs;  //!< Access Controll List pointer
+       /**
+        * \}
+        */
        
+       /**
+        * \name Common Functions
+        * \brief Functions that are used no matter the value of .Flags
+        * \{
+        */
        /**
         * \brief Reference the node
         * \param Node Pointer to this node
@@ -70,6 +126,17 @@ typedef struct sVFS_Node {
         */
         int    (*IOCtl)(struct sVFS_Node *Node, int Id, void *Data);
        
+       /**
+        * }
+        */
+       
+       /**
+        * \name Buffer Functions
+        * \brief Functions for accessing a buffer-type file (normal file or
+        *        symbolic link)
+        * \{
+        */
+       
        /**
         * \brief Read from the file
         * \param Node  Pointer to this node
@@ -89,6 +156,14 @@ typedef struct sVFS_Node {
         */
        Uint64  (*Write)(struct sVFS_Node *Node, Uint64 Offset, Uint64 Length, void *Buffer);
        
+       /**
+        * }
+        */
+       
+       /**
+        * \name Directory Functions
+        * \{
+        */
        /**
         * \brief Find an directory entry by name
         * \param Node  Pointer to this node
@@ -128,6 +203,10 @@ typedef struct sVFS_Node {
         * \return Boolean Success
         */
         int    (*Relink)(struct sVFS_Node *Node, char *OldName, char *NewName);
+        
+        /**
+         * }
+         */
 } tVFS_Node;
 
 /**
@@ -158,7 +237,8 @@ typedef struct sVFS_Driver
 
 extern tVFS_Node       NULLNode;       //!< NULL VFS Node (Ignored/Skipped)
 /**
- * \name Simple ACLs to aid writing drivers
+ * \name Static ACLs
+ * \brief Simple ACLs to aid writing drivers
  * \{
  */
 extern tVFS_ACL        gVFS_ACL_EveryoneRWX;   //!< Everyone Read/Write/Execute
@@ -193,8 +273,15 @@ extern tVFS_Driver *VFS_GetFSByName(char *Name);
 extern tVFS_ACL        *VFS_UnixToAcessACL(Uint Mode, Uint Owner, Uint Group);
 
 // --- Node Cache --
-//! \name Node Cache
-//! \{
+/**
+ * \name Node Cache
+ * \brief Functions to allow a node to be cached in memory by the VFS
+ * 
+ * These functions store a node for the driver, to prevent it from having
+ * to re-generate the node on each call to FindDir. It also allows for
+ * fast cleanup when a filesystem is unmounted.
+ * \{
+ */
 /**
  * \fn int Inode_GetHandle()
  * \brief Gets a unique handle to the Node Cache
@@ -231,6 +318,8 @@ extern void Inode_UncacheNode(int Handle, Uint64 Inode);
  */
 extern void    Inode_ClearCache(int Handle);
 
-//! \}
+/**
+ * \}
+ */
 
 #endif