From cf4418f1fcdd441e639d6b95afda42dd74db5f7c Mon Sep 17 00:00:00 2001 From: John Hodge Date: Mon, 15 Mar 2010 18:49:28 +0800 Subject: [PATCH] More documentation, mostly to the PCI --- Kernel/Doxyfile.api | 3 +- Kernel/Makefile.BuildNum | 2 +- Kernel/drv/pci.c | 27 +++++---- Kernel/include/drv_pci.h | 25 ++++++--- Kernel/include/vfs.h | 117 ++++++++++++++++++++++++++++++++++----- 5 files changed, 139 insertions(+), 35 deletions(-) diff --git a/Kernel/Doxyfile.api b/Kernel/Doxyfile.api index 319804c2..56b80d2c 100644 --- 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 a4aa1218..c43737f4 100644 --- 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 98232080..9f1dd6ea 100644 --- a/Kernel/drv/pci.c +++ b/Kernel/drv/pci.c @@ -12,18 +12,21 @@ #define LIST_DEVICES 1 // === STRUCTURES === -typedef struct s_pciDevice { +typedef struct sPCIDevice +{ Uint16 bus, slot, fcn; Uint16 vendor, device; union { - struct {Uint8 class, subclass;}; + struct { + Uint8 class, subclass; + }; Uint16 oc; }; Uint16 revision; Uint32 ConfigCache[256/4]; char Name[8]; tVFS_Node Node; -} t_pciDevice; +} tPCIDevice; // === CONSTANTS === #define SPACE_STEP 5 @@ -46,7 +49,7 @@ Uint32 PCI_GetBAR4(int id); Uint32 PCI_GetBAR5(int id); Uint16 PCI_AssignPort(int id, int bar, int count); - int PCI_EnumDevice(Uint16 bus, Uint16 dev, Uint16 fcn, t_pciDevice *info); + int PCI_EnumDevice(Uint16 bus, Uint16 dev, Uint16 fcn, tPCIDevice *info); Uint32 PCI_CfgReadDWord(Uint16 bus, Uint16 dev, Uint16 func, Uint16 offset); void PCI_CfgWriteDWord(Uint16 bus, Uint16 dev, Uint16 func, Uint16 offset, Uint32 data); Uint16 PCI_CfgReadWord(Uint16 bus, Uint16 dev, Uint16 func, Uint16 offset); @@ -57,7 +60,7 @@ Uint8 PCI_CfgReadByte(Uint16 bus, Uint16 dev, Uint16 func, Uint16 offset); int giPCI_BusCount = 1; int giPCI_InodeHandle = -1; int giPCI_DeviceCount = 0; -t_pciDevice *gPCI_Devices = NULL; +tPCIDevice *gPCI_Devices = NULL; tDevFS_Driver gPCI_DriverStruct = { NULL, "pci", { @@ -80,7 +83,7 @@ int PCI_Install(char **Arguments) { int bus, dev, fcn, i; int space = 0; - t_pciDevice devInfo; + tPCIDevice devInfo; void *tmpPtr = NULL; // Build Portmap @@ -107,7 +110,7 @@ int PCI_Install(char **Arguments) if(giPCI_DeviceCount == space) { space += SPACE_STEP; - tmpPtr = realloc(gPCI_Devices, space*sizeof(t_pciDevice)); + tmpPtr = realloc(gPCI_Devices, space*sizeof(tPCIDevice)); if(tmpPtr == NULL) break; gPCI_Devices = tmpPtr; @@ -121,7 +124,7 @@ int PCI_Install(char **Arguments) giPCI_BusCount++; } devInfo.Node.Inode = giPCI_DeviceCount; - memcpy(&gPCI_Devices[giPCI_DeviceCount], &devInfo, sizeof(t_pciDevice)); + memcpy(&gPCI_Devices[giPCI_DeviceCount], &devInfo, sizeof(tPCIDevice)); giPCI_DeviceCount ++; #if LIST_DEVICES Log("[PCI ] Device %i,%i:%i => 0x%x:0x%x", @@ -144,7 +147,7 @@ int PCI_Install(char **Arguments) if(giPCI_DeviceCount == 0) return MODULE_ERR_NOTNEEDED; - tmpPtr = realloc(gPCI_Devices, giPCI_DeviceCount*sizeof(t_pciDevice)); + tmpPtr = realloc(gPCI_Devices, giPCI_DeviceCount*sizeof(tPCIDevice)); if(tmpPtr == NULL) return MODULE_ERR_MALLOC; gPCI_Devices = tmpPtr; @@ -369,7 +372,7 @@ Uint16 PCI_AssignPort(int id, int bar, int count) Uint16 portVals; int gran=0; int i, j; - t_pciDevice *dev; + tPCIDevice *dev; //LogF("PCI_AssignPort: (id=%i,bar=%i,count=%i)\n", id, bar, count); @@ -426,9 +429,9 @@ Uint16 PCI_AssignPort(int id, int bar, int count) } /** - * \fn int PCI_EnumDevice(Uint16 bus, Uint16 slot, Uint16 fcn, t_pciDevice *info) + * \fn int PCI_EnumDevice(Uint16 bus, Uint16 slot, Uint16 fcn, tPCIDevice *info) */ -int PCI_EnumDevice(Uint16 bus, Uint16 slot, Uint16 fcn, t_pciDevice *info) +int PCI_EnumDevice(Uint16 bus, Uint16 slot, Uint16 fcn, tPCIDevice *info) { Uint16 vendor; int i; diff --git a/Kernel/include/drv_pci.h b/Kernel/include/drv_pci.h index b5394301..d3eb8a27 100644 --- a/Kernel/include/drv_pci.h +++ b/Kernel/include/drv_pci.h @@ -1,12 +1,16 @@ -/* - * Acess 2 - * PCI Bus Driver - * drv_pci.h +/** + * \file drv_pci.h + * \brief PCI Bus Driver + * \author John Hodge (thePowersGang) */ #ifndef _DRV_PCI_H #define _DRV_PCI_H -enum e_PciClasses { +/** + * \brief PCI Class Codes + */ +enum ePCIClasses +{ PCI_CLASS_PRE20 = 0x00, PCI_CLASS_STORAGE, PCI_CLASS_NETWORK, @@ -22,13 +26,20 @@ enum e_PciClasses { PCI_CLASS_SERIALBUS, PCI_CLASS_MISC = 0xFF }; -enum e_PciOverClasses { + +enum ePCIOverClasses +{ PCI_OC_PCIBRIDGE = 0x0604, PCI_OC_SCSI = 0x0100 }; - +/** + * \brief Count PCI Devices + * + * Counts the number of devices with specified Vendor and Device IDs + */ extern int PCI_CountDevices(Uint16 vendor, Uint16 device, Uint16 fcn); + extern int PCI_GetDevice(Uint16 vendor, Uint16 device, Uint16 fcn, int idx); extern int PCI_GetDeviceByClass(Uint16 class, Uint16 mask, int prev); extern Uint8 PCI_GetIRQ(int id); diff --git a/Kernel/include/vfs.h b/Kernel/include/vfs.h index 337d8e77..47cbe190 100644 --- 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 /** - * \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 -- 2.20.1