Formatting & doxygen docs for new syscall emulation code.

arch/alpha/alpha_linux_process.cc:
arch/alpha/alpha_linux_process.hh:
arch/alpha/alpha_tru64_process.cc:
arch/alpha/alpha_tru64_process.hh:
sim/syscall_emul.cc:
sim/syscall_emul.hh:
    Formatting & doxygen.

--HG--
extra : convert_revision : 4f07dd37e254120800dd0d5c0eb47acc9c00cb3f

arch/alpha/alpha_linux_process.cc

@@ -52,82 +52,86 @@
 
 using namespace std;
 
+///
+/// This class encapsulates the types, structures, constants,
+/// functions, and syscall-number mappings specific to the Alpha Linux
+/// syscall interface.
+///
 class Linux {
 
   public:
 
-//
+    //@{
-// basic Linux types
+    /// Basic Linux types.
-//
-
     typedef uint64_t size_t;
     typedef uint64_t off_t;
     typedef int64_t time_t;
     typedef uint32_t uid_t;
     typedef uint32_t gid_t;
+    //@}
 
-// open(2) flags
+    //@{
-static const int TGT_O_RDONLY	 = 00000000;
+    /// open(2) flag values.
-static const int TGT_O_WRONLY	 = 00000001;
+    static const int TGT_O_RDONLY	= 00000000;	//!< O_RDONLY
-static const int TGT_O_RDWR	 = 00000002;
+    static const int TGT_O_WRONLY	= 00000001;	//!< O_WRONLY
-static const int TGT_O_NONBLOCK  = 00000004;
+    static const int TGT_O_RDWR	 	= 00000002;	//!< O_RDWR
-static const int TGT_O_APPEND	 = 00000010;
+    static const int TGT_O_NONBLOCK  	= 00000004;	//!< O_NONBLOCK
-static const int TGT_O_CREAT	 = 00001000;
+    static const int TGT_O_APPEND	= 00000010;	//!< O_APPEND
-static const int TGT_O_TRUNC	 = 00002000;
+    static const int TGT_O_CREAT	= 00001000;	//!< O_CREAT
-static const int TGT_O_EXCL	 = 00004000;
+    static const int TGT_O_TRUNC	= 00002000;	//!< O_TRUNC
-static const int TGT_O_NOCTTY	 = 00010000;
+    static const int TGT_O_EXCL	 	= 00004000;	//!< O_EXCL
-static const int TGT_O_SYNC	 = 00040000;
+    static const int TGT_O_NOCTTY	= 00010000;	//!< O_NOCTTY
-static const int TGT_O_DRD	 = 00100000;
+    static const int TGT_O_SYNC	 	= 00040000;	//!< O_SYNC
-static const int TGT_O_DIRECTIO  = 00200000;
+    static const int TGT_O_DRD	 	= 00100000;	//!< O_DRD
-static const int TGT_O_CACHE	 = 00400000;
+    static const int TGT_O_DIRECTIO  	= 00200000;	//!< O_DIRECTIO
-static const int TGT_O_DSYNC	 = 02000000;
+    static const int TGT_O_CACHE	= 00400000;	//!< O_CACHE
-static const int TGT_O_RSYNC	 = 04000000;
+    static const int TGT_O_DSYNC	= 02000000;	//!< O_DSYNC
+    static const int TGT_O_RSYNC	= 04000000;	//!< O_RSYNC
+    //@}
 
+    /// This table maps the target open() flags to the corresponding
+    /// host open() flags.
     static OpenFlagTransTable openFlagTable[];
+
+    /// Number of entries in openFlagTable[].
     static const int NUM_OPEN_FLAGS;
 
-//
+    /// Stat buffer.  Note that we can't call it 'stat' since that
-// Stat buffer.
+    /// gets #defined to something else on some systems.
-//
-
     struct tgt_stat {
-    uint32_t	st_dev;
+        uint32_t	st_dev;		//!< device
-    uint32_t	st_ino;
+        uint32_t	st_ino;		//!< inode
-    uint32_t	st_mode;
+        uint32_t	st_mode;	//!< mode
-    uint32_t	st_nlink;
+        uint32_t	st_nlink;	//!< link count
-    uint32_t	st_uid;
+        uint32_t	st_uid;		//!< owner's user ID
-    uint32_t	st_gid;
+        uint32_t	st_gid;		//!< owner's group ID
-    uint32_t	st_rdev;
+        uint32_t	st_rdev;	//!< device number
-    int64_t	st_size;
+        int64_t		st_size;	//!< file size in bytes
-    uint64_t	st_atimeX;
+        uint64_t	st_atimeX;	//!< time of last access
-    uint64_t	st_mtimeX;
+        uint64_t	st_mtimeX;	//!< time of last modification
-    uint64_t	st_ctimeX;
+        uint64_t	st_ctimeX;	//!< time of last status change
-    uint32_t	st_blksize;
+        uint32_t	st_blksize;	//!< optimal I/O block size
-    int32_t	st_blocks;
+        int32_t		st_blocks;	//!< number of blocks allocated
-    uint32_t	st_flags;
+        uint32_t	st_flags;	//!< flags
-    uint32_t	st_gen;
+        uint32_t	st_gen;		//!< unknown
     };
 
 
-//
+    /// Length of strings in struct utsname (plus 1 for null char).
-// for uname()
-//
-
     static const int _SYS_NMLN = 65;
 
+    /// Interface struct for uname().
     struct utsname {
-    char sysname[_SYS_NMLN];
+        char sysname[_SYS_NMLN];	//!< System name.
-    char nodename[_SYS_NMLN];
+        char nodename[_SYS_NMLN];	//!< Node name.
-    char release[_SYS_NMLN];
+        char release[_SYS_NMLN];	//!< OS release.
-    char version[_SYS_NMLN];
+        char version[_SYS_NMLN];	//!< OS version.
-    char machine[_SYS_NMLN];
+        char machine[_SYS_NMLN];	//!< Machine type.
     };
 
 
-//
+    //@{
-// for ioctl()
+    /// ioctl() command codes.
-//
-
     static const unsigned TIOCGETP   = 0x40067408;
     static const unsigned TIOCSETP   = 0x80067409;
     static const unsigned TIOCSETN   = 0x8006740a;
@@ -135,11 +139,9 @@ static const unsigned TIOCSETC   = 0x80067411;
     static const unsigned TIOCGETC   = 0x40067412;
     static const unsigned FIONREAD   = 0x4004667f;
     static const unsigned TIOCISATTY = 0x2000745e;
+    //@}
 
-//
+    /// Resource enumeration for getrlimit().
-// for getrlimit()
-//
-
     enum rlimit_resources {
         RLIMIT_CPU = 0,
         RLIMIT_FSIZE = 1,
@@ -155,56 +157,53 @@ enum rlimit_resources {
         RLIMIT_LOCKS = 10
     };
 
+    /// Limit struct for getrlimit/setrlimit.
     struct rlimit {
-    uint64_t  rlim_cur;	// soft limit
+        uint64_t  rlim_cur;	//!< soft limit
-    uint64_t  rlim_max;	// hard limit
+        uint64_t  rlim_max;	//!< hard limit
     };
 
 
-//
+    /// For mmap().
-// for mmap()
-//
     static const unsigned TGT_MAP_ANONYMOUS = 0x10;
 
-//
+    /// For gettimeofday().
-// for gettimeofday
-//
-
     struct timeval {
-    int64_t tv_sec;
+        int64_t tv_sec;		//!< seconds
-    int64_t tv_usec;
+        int64_t tv_usec;	//!< microseconds
     };
 
-//
+    //@{
-// for getrusage
+    /// For getrusage().
-//
-
-
     static const int RUSAGE_SELF = 0;
     static const int RUSAGE_CHILDREN = -1;
     static const int RUSAGE_BOTH = -2;
+    //@}
 
+    /// For getrusage().
     struct rusage {
-     struct timeval ru_utime;	// user time used
+        struct timeval ru_utime;	//!< user time used
-     struct timeval ru_stime;	// system time used
+        struct timeval ru_stime;	//!< system time used
-     int64_t ru_maxrss;
+        int64_t ru_maxrss;		//!< max rss
-     int64_t ru_ixrss;		// integral shared memory size
+        int64_t ru_ixrss;		//!< integral shared memory size
-     int64_t ru_idrss;		// integral unshared data "
+        int64_t ru_idrss;		//!< integral unshared data "
-     int64_t ru_isrss;		// integral unshared stack "
+        int64_t ru_isrss;		//!< integral unshared stack "
-     int64_t ru_minflt;		// page reclaims - total vmfaults
+        int64_t ru_minflt;		//!< page reclaims - total vmfaults
-     int64_t ru_majflt;		// page faults
+        int64_t ru_majflt;		//!< page faults
-     int64_t ru_nswap;		// swaps
+        int64_t ru_nswap;		//!< swaps
-     int64_t ru_inblock;	// block input operations
+        int64_t ru_inblock;		//!< block input operations
-     int64_t ru_oublock;	// block output operations
+        int64_t ru_oublock;		//!< block output operations
-     int64_t ru_msgsnd;		// messages sent
+        int64_t ru_msgsnd;		//!< messages sent
-     int64_t ru_msgrcv;		// messages received
+        int64_t ru_msgrcv;		//!< messages received
-     int64_t ru_nsignals;	// signals received
+        int64_t ru_nsignals;		//!< signals received
-     int64_t ru_nvcsw;		// voluntary context switches
+        int64_t ru_nvcsw;		//!< voluntary context switches
-     int64_t ru_nivcsw;		// involuntary "
+        int64_t ru_nivcsw;		//!< involuntary "
     };
 
-static
+    /// Helper function to convert a host stat buffer to a target stat
-void
+    /// buffer.  Also copies the target buffer out to the simulated
+    /// memorty space.  Used by stat(), fstat(), and lstat().
+    static void
     copyOutStatBuf(FunctionalMemory *mem, Addr addr, struct stat *host)
     {
         TypedBufferArg<Linux::tgt_stat> tgt(addr);
@@ -226,11 +225,11 @@ copyOutStatBuf(FunctionalMemory *mem, Addr addr, struct stat *host)
         tgt.copyOut(mem);
     }
 
-
+    /// The target system's hostname.
     static const char *hostname;
 
-static
+    /// Target uname() handler.
-int
+    static int
     unameFunc(SyscallDesc *desc, int callnum, Process *process,
               ExecContext *xc)
     {
@@ -246,9 +245,10 @@ unameFunc(SyscallDesc *desc, int callnum, Process *process,
         return 0;
     }
 
-
+    /// Target osf_getsysyinfo() handler.  Even though this call is
-static
+    /// borrowed from Tru64, the subcases that get used appear to be
-int
+    /// different in practice from those used by Tru64 processes.
+    static int
     osf_getsysinfoFunc(SyscallDesc *desc, int callnum, Process *process,
                        ExecContext *xc)
     {
@@ -274,9 +274,8 @@ osf_getsysinfoFunc(SyscallDesc *desc, int callnum, Process *process,
         return 0;
     }
 
-
+    /// Target osf_setsysinfo() handler.
-static
+    static int
-int
     osf_setsysinfoFunc(SyscallDesc *desc, int callnum, Process *process,
                        ExecContext *xc)
     {
@@ -303,9 +302,8 @@ osf_setsysinfoFunc(SyscallDesc *desc, int callnum, Process *process,
         return 0;
     }
 
-
+    /// Target fnctl() handler.
-static
+    static int
-int
     fcntlFunc(SyscallDesc *desc, int callnum, Process *process,
               ExecContext *xc)
     {
@@ -347,14 +345,18 @@ fcntlFunc(SyscallDesc *desc, int callnum, Process *process,
         }
     }
 
+    /// Array of syscall descriptors, indexed by call number.
     static SyscallDesc syscallDescs[];
 
+    /// Number of syscalls in syscallDescs[].
     static const int Num_Syscall_Descs;
 
+    /// Max supported syscall number.
     static const int Max_Syscall_Desc;
 
-static
+    /// Do the specified syscall.  Just looks the call number up in
-void
+    /// the table and invokes the appropriate handler.
+    static void
     doSyscall(int callnum, Process *process, ExecContext *xc)
     {
         if (callnum < 0 || callnum > Max_Syscall_Desc) {
@@ -365,14 +367,11 @@ doSyscall(int callnum, Process *process, ExecContext *xc)
 
         desc->doSyscall(callnum, process, xc);
     }
-
-
 };  // class Linux
 
 
 // open(2) flags translation table
 OpenFlagTransTable Linux::openFlagTable[] = {
-  /* target flag */	/* host flag */
 #ifdef _MSC_VER
   { Linux::TGT_O_RDONLY,	_O_RDONLY },
   { Linux::TGT_O_WRONLY,	_O_WRONLY },
@@ -406,7 +405,8 @@ OpenFlagTransTable Linux::openFlagTable[] = {
 #endif /* _MSC_VER */
 };
 
-const int Linux::NUM_OPEN_FLAGS = (sizeof(Linux::openFlagTable)/sizeof(Linux::openFlagTable[0]));
+const int Linux::NUM_OPEN_FLAGS =
+        (sizeof(Linux::openFlagTable)/sizeof(Linux::openFlagTable[0]));
 
 const char *Linux::hostname = "m5.eecs.umich.edu";
 

arch/alpha/alpha_linux_process.hh

@@ -31,15 +31,19 @@
 
 #include "sim/process.hh"
 
+
+/// A process with emulated Alpha/Linux syscalls.
 class AlphaLinuxProcess : public LiveProcess
 {
   public:
+    /// Constructor.
     AlphaLinuxProcess(const std::string &name,
                       ObjectFile *objFile,
                       int stdin_fd, int stdout_fd, int stderr_fd,
                       std::vector<std::string> &argv,
                       std::vector<std::string> &envp);
 
+    /// Syscall emulation function.
     virtual void syscall(ExecContext *xc);
 };
 

arch/alpha/alpha_tru64_process.hh

@@ -31,15 +31,18 @@
 
 #include "sim/process.hh"
 
+/// A process with emulated Alpha Tru64 syscalls.
 class AlphaTru64Process : public LiveProcess
 {
   public:
+    /// Constructor.
     AlphaTru64Process(const std::string &name,
                       ObjectFile *objFile,
                       int stdin_fd, int stdout_fd, int stderr_fd,
                       std::vector<std::string> &argv,
                       std::vector<std::string> &envp);
 
+    /// Syscall emulation function.
     virtual void syscall(ExecContext *xc);
 };
 

sim/syscall_emul.cc

@@ -57,9 +57,6 @@ SyscallDesc::doSyscall(int callnum, Process *process, ExecContext *xc)
 }
 
 
-//
-// Handler for unimplemented syscalls that we haven't thought about.
-//
 int
 unimplementedFunc(SyscallDesc *desc, int callnum, Process *process,
                   ExecContext *xc)
@@ -73,12 +70,6 @@ unimplementedFunc(SyscallDesc *desc, int callnum, Process *process,
 }
 
 
-//
-// Handler for unimplemented syscalls that we never intend to
-// implement (signal handling, etc.) and should not affect the correct
-// behavior of the program.  Print a warning only if the appropriate
-// trace flag is enabled.  Return success to the target program.
-//
 int
 ignoreFunc(SyscallDesc *desc, int callnum, Process *process,
            ExecContext *xc)

sim/syscall_emul.hh

@@ -51,6 +51,7 @@ class SyscallDesc {
 
   public:
 
+    /// Typedef for target syscall handler functions.
     typedef int (*FuncPtr)(SyscallDesc *, int num,
                            Process *, ExecContext *);
 
@@ -58,7 +59,6 @@ class SyscallDesc {
     FuncPtr funcPtr;	//!< Pointer to emulation function.
     int flags;		//!< Flags (see Flags enum).
 
-
     /// Flag values for controlling syscall behavior.
     enum Flags {
         /// Don't set return regs according to funcPtr return value.
@@ -155,17 +155,40 @@ class TypedBufferArg : public BaseBufferArg
 //////////////////////////////////////////////////////////////////////
 
 
+/// Handler for unimplemented syscalls that we haven't thought about.
 int unimplementedFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
+
+/// Handler for unimplemented syscalls that we never intend to
+/// implement (signal handling, etc.) and should not affect the correct
+/// behavior of the program.  Print a warning only if the appropriate
+/// trace flag is enabled.  Return success to the target program.
 int ignoreFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
 
+/// Target exit() handler: terminate simulation.
 int exitFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
+
+/// Target getpagesize() handler.
 int getpagesizeFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
+
+/// Target obreak() handler: set brk address.
 int obreakFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
+
+/// Target close() handler.
 int closeFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
+
+/// Target read() handler.
 int readFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
+
+/// Target write() handler.
 int writeFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
+
+/// Target lseek() handler.
 int lseekFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
+
+/// Target munmap() handler.
 int munmapFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
+
+/// Target gethostname() handler.
 int gethostnameFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
 
 //////////////////////////////////////////////////////////////////////
@@ -175,6 +198,9 @@ int gethostnameFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc);
 //
 //////////////////////////////////////////////////////////////////////
 
+/// Target ioctl() handler.  For the most part, programs call ioctl()
+/// only to find out if their stdout is a tty, to determine whether to
+/// do line or block buffering.
 template <class OS>
 int
 ioctlFunc(SyscallDesc *desc, int callnum, Process *process,
@@ -204,12 +230,15 @@ ioctlFunc(SyscallDesc *desc, int callnum, Process *process,
     }
 }
 
+/// This struct is used to build an target-OS-dependent table that
+/// maps the target's open() flags to the host open() flags.
 struct OpenFlagTransTable {
-    int tgtFlag;
+    int tgtFlag;	//!< Target system flag value.
-    int hostFlag;
+    int hostFlag;	//!< Corresponding host system flag value.
 };
 
 
+/// Target open() handler.
 template <class OS>
 int
 openFunc(SyscallDesc *desc, int callnum, Process *process,
@@ -254,6 +283,7 @@ openFunc(SyscallDesc *desc, int callnum, Process *process,
 }
 
 
+/// Target stat() handler.
 template <class OS>
 int
 statFunc(SyscallDesc *desc, int callnum, Process *process,
@@ -276,6 +306,7 @@ statFunc(SyscallDesc *desc, int callnum, Process *process,
 }
 
 
+/// Target lstat() handler.
 template <class OS>
 int
 lstatFunc(SyscallDesc *desc, int callnum, Process *process,
@@ -297,6 +328,7 @@ lstatFunc(SyscallDesc *desc, int callnum, Process *process,
     return 0;
 }
 
+/// Target fstat() handler.
 template <class OS>
 int
 fstatFunc(SyscallDesc *desc, int callnum, Process *process,
@@ -321,18 +353,18 @@ fstatFunc(SyscallDesc *desc, int callnum, Process *process,
 }
 
 
+/// Target mmap() handler.
+///
+/// We don't really handle mmap().  If the target is mmaping an
+/// anonymous region or /dev/zero, we can get away with doing basically
+/// nothing (since memory is initialized to zero and the simulator
+/// doesn't really check addresses anyway).  Always print a warning,
+/// since this could be seriously broken if we're not mapping
+/// /dev/zero.
 //
-// We don't really handle mmap().  If the target is mmaping an
+/// Someday we should explicitly check for /dev/zero in open, flag the
-// anonymous region or /dev/zero, we can get away with doing basically
+/// file descriptor, and fail (or implement!) a non-anonymous mmap to
-// nothing (since memory is initialized to zero and the simulator
+/// anything else.
-// doesn't really check addresses anyway).  Always print a warning,
-// since this could be seriously broken if we're not mapping
-// /dev/zero.
-//
-// Someday we should explicitly check for /dev/zero in open, flag the
-// file descriptor, and fail (or implement!) a non-anonymous mmap to
-// anything else.
-//
 template <class OS>
 int
 mmapFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc)
@@ -341,7 +373,7 @@ mmapFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc)
     uint64_t length = xc->getSyscallArg(1);
     // int prot = xc->getSyscallArg(2);
     int flags = xc->getSyscallArg(3);
-    int fd = p->sim_fd(xc->getSyscallArg(4));
+    // int fd = p->sim_fd(xc->getSyscallArg(4));
     // int offset = xc->getSyscallArg(5);
 
     if (start == 0) {
@@ -352,13 +384,13 @@ mmapFunc(SyscallDesc *desc, int num, Process *p, ExecContext *xc)
 
     if (!(flags & OS::TGT_MAP_ANONYMOUS)) {
         DPRINTF(SyscallWarnings, "Warning: allowing mmap of file @ fd %d.  "
-                "This will break if not /dev/zero.", fd);
+                "This will break if not /dev/zero.", xc->getSyscallArg(4));
     }
 
     return start;
 }
 
-
+/// Target getrlimit() handler.
 template <class OS>
 int
 getrlimitFunc(SyscallDesc *desc, int callnum, Process *process,
@@ -383,16 +415,16 @@ getrlimitFunc(SyscallDesc *desc, int callnum, Process *process,
     return 0;
 }
 
-// 1M usecs in 1 sec, for readability
+/// A readable name for 1,000,000, for converting microseconds to seconds.
 const int one_million = 1000000;
 
-// seconds since the epoch (1/1/1970)... about a billion, by my reckoning
+/// Approximate seconds since the epoch (1/1/1970).  About a billion,
+/// by my reckoning.  We want to keep this a constant (not use the
+/// real-world time) to keep simulations repeatable.
 const unsigned seconds_since_epoch = 1000000000;
 
-//
+/// Helper function to convert current elapsed time to seconds and
-// helper function: populate struct timeval with approximation of
+/// microseconds.
-// current elapsed time
-//
 template <class T1, class T2>
 void
 getElapsedTime(T1 &sec, T2 &usec)
@@ -405,6 +437,7 @@ getElapsedTime(T1 &sec, T2 &usec)
 }
 
 
+/// Target gettimeofday() handler.
 template <class OS>
 int
 gettimeofdayFunc(SyscallDesc *desc, int callnum, Process *process,
@@ -421,6 +454,7 @@ gettimeofdayFunc(SyscallDesc *desc, int callnum, Process *process,
 }
 
 
+/// Target getrusage() function.
 template <class OS>
 int
 getrusageFunc(SyscallDesc *desc, int callnum, Process *process,