From: Brian Demsky <bdemsky@uci.edu>
Date: Wed, 6 Jun 2012 07:45:15 +0000 (-0700)
Subject: more documentation
X-Git-Url: http://plrg.eecs.uci.edu/git/?p=c11tester.git;a=commitdiff_plain;h=7bec9f8bcc8c63a0be2b31f8aa01a61a50afe4f9

more documentation
---

diff --git a/mymemory.cc b/mymemory.cc
index 1dada053..2b9c44d5 100644
--- a/mymemory.cc
+++ b/mymemory.cc
@@ -7,6 +7,8 @@
 static mspace sStaticSpace = NULL;
 #endif
 
+/** Non-snapshotting malloc for our use. */
+
 void *MYMALLOC(size_t size) {
 #if USE_MPROTECT_SNAPSHOT
 	static void *(*mallocp)(size_t size);
@@ -64,6 +66,8 @@ void system_free( void * ptr ){
 	}
 	freep(ptr);
 }
+
+/** Non-snapshotting free for our use. */
 void MYFREE(void *ptr) {
 #if USE_MPROTECT_SNAPSHOT
 	static void (*freep)(void *);
@@ -82,33 +86,54 @@ void MYFREE(void *ptr) {
 	mspace_free( sStaticSpace, ptr );
 #endif
 }
+
+
+/** This global references the mspace for the snapshotting heap */
 mspace mySpace = NULL;
+
+/** This global references the unaligned memory address that was malloced for the snapshotting heap */
 void * basemySpace = NULL;
 
+//Subramanian --- please make these work for the fork based approach
+
+/** Snapshotting malloc implementation for user programs. */
+
 void *malloc( size_t size ) {
 	return mspace_malloc( mySpace, size );
 }
 
+/** Snapshotting free implementation for user programs. */
+
 void free( void * ptr ){
 	mspace_free( mySpace, ptr );
 }
 
+/** Snapshotting realloc implementation for user programs. */
+
 void *realloc( void *ptr, size_t size ){
 	return mspace_realloc( mySpace, ptr, size );
 }
 
+/** Snapshotting new operator for user programs. */
+
 void * operator new(size_t size) throw(std::bad_alloc) {
 	return malloc(size);
 }
 
+/** Snapshotting delete operator for user programs. */
+
 void operator delete(void *p) throw() {
 	free(p);
 }
 
+/** Snapshotting new[] operator for user programs. */
+
 void * operator new[](size_t size) throw(std::bad_alloc) {
 	return malloc(size);
 }
 
+/** Snapshotting delete[] operator for user programs. */
+
 void operator delete[](void *p, size_t size) {
 	free(p);
 }
diff --git a/mymemory.h b/mymemory.h
index f928797b..c159e532 100644
--- a/mymemory.h
+++ b/mymemory.h
@@ -1,3 +1,7 @@
+/** @file mymemory.h
+ *  @brief Memory allocation functions.
+ */
+
 #ifndef _MY_MEMORY_H
 #define _MY_MEMORY_H
 #include <stdlib.h>
diff --git a/snapshot-interface.cc b/snapshot-interface.cc
index 58e1dd2f..c88e65ae 100644
--- a/snapshot-interface.cc
+++ b/snapshot-interface.cc
@@ -21,6 +21,11 @@
 SnapshotStack * snapshotObject;
 
 #ifdef MAC
+/** The SnapshotGlobalSegments function computes the memory regions
+ *	that may contain globals and then configures the snapshotting
+ *	library to snapshot them.
+ */
+
 void SnapshotGlobalSegments(){
 	int pid = getpid();
 	char buf[9000], execname[100];
@@ -66,6 +71,10 @@ void SnapshotGlobalSegments(){
 	pclose(map);
 }
 #else
+/** The SnapshotGlobalSegments function computes the memory regions
+ *	that may contain globals and then configures the snapshotting
+ *	library to snapshot them.
+ */
 void SnapshotGlobalSegments(){
 	int pid = getpid();
 	char buf[9000], filename[100];
@@ -94,8 +103,6 @@ void SnapshotGlobalSegments(){
 }
 #endif
 
-//class definition of SnapshotStack.....
-//declaration of constructor....
 SnapshotStack::SnapshotStack(){
 	SnapshotGlobalSegments();
 	stack=NULL;
@@ -104,6 +111,14 @@ SnapshotStack::SnapshotStack(){
 SnapshotStack::~SnapshotStack(){
 }
 
+
+/** This method returns to the last snapshot before the inputted
+ * sequence number.  This function must be called from the model
+ * checking thread and not from a snapshotted stack.  
+ * @param seqindex is the sequence number to rollback before.  
+ * @return is the sequence number we actually rolled back to.
+ */
+		
 int SnapshotStack::backTrackBeforeStep(int seqindex) {
 	while(true) {
 		if (stack->index<=seqindex) {
@@ -117,6 +132,9 @@ int SnapshotStack::backTrackBeforeStep(int seqindex) {
 	}
 }
 
+/** This method takes a snapshot at the given sequence number.
+ */
+
 void SnapshotStack::snapshotStep(int seqindex) {
 	struct stackEntry *tmp=(struct stackEntry *)MYMALLOC(sizeof(struct stackEntry));
 	tmp->next=stack;
diff --git a/snapshot-interface.h b/snapshot-interface.h
index 7e501fea..1c4c32b0 100644
--- a/snapshot-interface.h
+++ b/snapshot-interface.h
@@ -1,3 +1,8 @@
+/** @file snapshot-interface.h
+ *  @brief C++ layer on top of snapshotting system.
+ */
+
+
 #ifndef __SNAPINTERFACE_H
 #define __SNAPINTERFACE_H
 #include "mymemory.h"
diff --git a/snapshot.cc b/snapshot.cc
index ac4f7123..a5792e56 100644
--- a/snapshot.cc
+++ b/snapshot.cc
@@ -61,6 +61,10 @@ void initSnapShotRecord(unsigned int numbackingpages, unsigned int numsnapshots,
 }
 #endif //nothing to initialize for the fork based snapshotting.
 
+/** HandlePF is the page fault handler for mprotect based snapshotting
+ * algorithm.
+ */
+
 void HandlePF( int sig, siginfo_t *si, void * unused){
 #if USE_MPROTECT_SNAPSHOT
 	if( si->si_code == SEGV_MAPERR ){
@@ -87,14 +91,18 @@ void HandlePF( int sig, siginfo_t *si, void * unused){
 #endif //nothing to handle for non snapshotting case.
 }
 
-//Return a page aligned address for the address being added
-//as a side effect the numBytes are also changed.
+/** ReturnPageAlignedAddress returns a page aligned address for the
+ * address being added as a side effect the numBytes are also changed.
+ */
+
 void * ReturnPageAlignedAddress(void * addr) {
 	return (void *)(((uintptr_t)addr)&~(PAGESIZE-1));
 }
 
-//Return a page aligned address for the address being added
-//as a side effect the numBytes are also changed.
+/** PageAlignedAdressUpdate return a page aligned address for the
+ * address being added as a side effect the numBytes are also changed.
+ */
+
 void * PageAlignAddressUpward(void * addr) {
 	return (void *)((((uintptr_t)addr)+PAGESIZE-1)&~(PAGESIZE-1));
 }
@@ -122,6 +130,10 @@ extern "C" {
 #ifdef __cplusplus
 }
 #endif
+
+/** The initSnapShotLibrary function initializes the Snapshot library.
+ *  @param entryPoint the function that should run the program.
+ */
 void initSnapShotLibrary(unsigned int numbackingpages,
 		unsigned int numsnapshots, unsigned int nummemoryregions,
 		unsigned int numheappages, VoidFuncPtr entryPoint) {
@@ -228,7 +240,9 @@ void initSnapShotLibrary(unsigned int numbackingpages,
 
 #endif
 }
-/* This function assumes that addr is page aligned */
+
+/** The addMemoryRegionToSnapShot function assumes that addr is page aligned. 
+ */
 void addMemoryRegionToSnapShot( void * addr, unsigned int numPages) {
 #if USE_MPROTECT_SNAPSHOT
 	unsigned int memoryregion=snapshotrecord->lastRegion++;
@@ -241,7 +255,11 @@ void addMemoryRegionToSnapShot( void * addr, unsigned int numPages) {
 	snapshotrecord->regionsToSnapShot[ memoryregion ].sizeInPages=numPages;
 #endif //NOT REQUIRED IN THE CASE OF FORK BASED SNAPSHOTS.
 }
-//take snapshot
+
+/** The takeSnapshot function takes a snapshot.
+ * @return The snapshot identifier.
+ */
+
 snapshot_id takeSnapshot( ){
 #if USE_MPROTECT_SNAPSHOT
 	for(unsigned int region=0; region<snapshotrecord->lastRegion;region++) {
@@ -264,6 +282,11 @@ snapshot_id takeSnapshot( ){
 	return snapshotid;
 #endif
 }
+
+/** The rollBack function rollback to the given snapshot identifier.
+ *  @param theID is the snapshot identifier to rollback to.
+ */
+
 void rollBack( snapshot_id theID ){
 #if USE_MPROTECT_SNAPSHOT
 	std::map< void *, bool, std::less< void * >, MyAlloc< std::pair< const void *, bool > > > duplicateMap;
@@ -303,6 +326,8 @@ void rollBack( snapshot_id theID ){
 #endif
 }
 
+/** The finalize method shuts down the snapshotting system.  */
+
 void finalize(){
 #if !USE_MPROTECT_SNAPSHOT
 	sTheRecord->mbFinalize = true;
diff --git a/snapshot.h b/snapshot.h
index cc5e7e53..03e020e8 100644
--- a/snapshot.h
+++ b/snapshot.h
@@ -1,3 +1,7 @@
+/** @file snapshot.h
+ *	@brief Snapshotting interface header file.
+ */
+
 #ifndef _SNAPSHOT_H
 #define _SNAPSHOT_H
 
diff --git a/snapshotimp.h b/snapshotimp.h
index 8d935f23..b918b844 100644
--- a/snapshotimp.h
+++ b/snapshotimp.h
@@ -1,3 +1,7 @@
+/** @file snapshotimp.h
+ *	@brief Snapshotting implementation header file..
+ */
+
 #ifndef _SNAPSHOTIMP_H
 #define _SNAPSHOTIMP_H
 #include "snapshot.h"