Updated documentation

.gitignore

@@ -32,6 +32,10 @@ information.xml
 debug.txt
 *.dot
 
+ForeC Analyser/ForeC Analyser.xcodeproj/project.xcworkspace/xcuserdata/kinchee.xcuserdatad/
+ForeC Analyser/ForeC Analyser.xcodeproj/xcuserdata/kinchee.xcuserdatad/
+
+ForeC Compiler/ForeC Compiler.xcodeproj/xcuserdata/kinchee.xcuserdatad/
 ForeC Compiler/test/**/*.pdf
 
 ForeC Benchmarks/ptarm/Pipelining/Pipelining.c

ForeC Analyser/ForeC Analyser.xcodeproj/project.pbxproj

@@ -3,7 +3,7 @@
 	archiveVersion = 1;
 	classes = {
 	};
-	objectVersion = 46;
+	objectVersion = 54;
 	objects = {
 
 /* Begin PBXFileReference section */
@@ -64,7 +64,7 @@
 		47CF50B8143C0AC3008DF081 /* Makefile */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.make; path = Makefile; sourceTree = "<group>"; };
 		47CF50B9143C0AC3008DF081 /* Main.cpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; path = Main.cpp; sourceTree = "<group>"; };
 		47CF50BB143C0AC3008DF081 /* ScannerMicroBlaze.hpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.h; path = ScannerMicroBlaze.hpp; sourceTree = "<group>"; };
-		47CF50BD143C0B3F008DF081 /* Readme.txt */ = {isa = PBXFileReference; lastKnownFileType = text; path = Readme.txt; sourceTree = "<group>"; };
+		47CF50BD143C0B3F008DF081 /* Readme.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = Readme.md; sourceTree = "<group>"; };
 		47D36DBB144053C500447F55 /* OperandList.hpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.h; path = OperandList.hpp; sourceTree = "<group>"; };
 		47D36DBC1440587C00447F55 /* AssemblyInstruction.cpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; path = AssemblyInstruction.cpp; sourceTree = "<group>"; };
 		47D36DBD1440587C00447F55 /* AssemblyInstruction.hpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.h; path = AssemblyInstruction.hpp; sourceTree = "<group>"; };
@@ -109,7 +109,7 @@
 		47CF508E143C01C1008DF081 = {
 			isa = PBXGroup;
 			children = (
-				47CF50BD143C0B3F008DF081 /* Readme.txt */,
+				47CF50BD143C0B3F008DF081 /* Readme.md */,
 				47CF50B8143C0AC3008DF081 /* Makefile */,
 				47CF50B9143C0AC3008DF081 /* Main.cpp */,
 				47C5B02B16DF385A00D00F05 /* File.hpp */,
@@ -237,15 +237,17 @@
 		47CF5090143C01C1008DF081 /* Project object */ = {
 			isa = PBXProject;
 			attributes = {
-				LastUpgradeCheck = 0700;
+				BuildIndependentTargetsInParallel = YES;
+				LastUpgradeCheck = 1530;
 				ORGANIZATIONNAME = "Potential Publishers";
 			};
 			buildConfigurationList = 47CF5093143C01C1008DF081 /* Build configuration list for PBXProject "ForeC Analyser" */;
 			compatibilityVersion = "Xcode 3.2";
-			developmentRegion = English;
+			developmentRegion = en;
 			hasScannedForEncodings = 0;
 			knownRegions = (
 				en,
+				Base,
 			);
 			mainGroup = 47CF508E143C01C1008DF081;
 			projectDirPath = "";
@@ -260,26 +262,88 @@
 		4716CCAA19E3CBC700968A1A /* Debug */ = {
 			isa = XCBuildConfiguration;
 			buildSettings = {
+				CLANG_ENABLE_OBJC_WEAK = YES;
+				DEAD_CODE_STRIPPING = YES;
 			};
 			name = Debug;
 		};
 		4716CCAB19E3CBC700968A1A /* Release */ = {
 			isa = XCBuildConfiguration;
 			buildSettings = {
+				CLANG_ENABLE_OBJC_WEAK = YES;
+				DEAD_CODE_STRIPPING = YES;
 			};
 			name = Release;
 		};
 		47CF5095143C01C2008DF081 /* Debug */ = {
 			isa = XCBuildConfiguration;
 			buildSettings = {
+				CLANG_ANALYZER_LOCALIZABILITY_NONLOCALIZED = YES;
+				CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
+				CLANG_WARN_BOOL_CONVERSION = YES;
+				CLANG_WARN_COMMA = YES;
+				CLANG_WARN_CONSTANT_CONVERSION = YES;
+				CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
+				CLANG_WARN_EMPTY_BODY = YES;
+				CLANG_WARN_ENUM_CONVERSION = YES;
+				CLANG_WARN_INFINITE_RECURSION = YES;
+				CLANG_WARN_INT_CONVERSION = YES;
+				CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
+				CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
+				CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
+				CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES;
+				CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
+				CLANG_WARN_STRICT_PROTOTYPES = YES;
+				CLANG_WARN_SUSPICIOUS_MOVE = YES;
+				CLANG_WARN_UNREACHABLE_CODE = YES;
+				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
+				DEAD_CODE_STRIPPING = YES;
+				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				ENABLE_TESTABILITY = YES;
+				ENABLE_USER_SCRIPT_SANDBOXING = YES;
+				GCC_NO_COMMON_BLOCKS = YES;
+				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_RETURN_TYPE = YES;
+				GCC_WARN_UNDECLARED_SELECTOR = YES;
+				GCC_WARN_UNINITIALIZED_AUTOS = YES;
+				GCC_WARN_UNUSED_FUNCTION = YES;
+				GCC_WARN_UNUSED_VARIABLE = YES;
 				ONLY_ACTIVE_ARCH = YES;
 			};
 			name = Debug;
 		};
 		47CF5096143C01C2008DF081 /* Release */ = {
 			isa = XCBuildConfiguration;
 			buildSettings = {
+				CLANG_ANALYZER_LOCALIZABILITY_NONLOCALIZED = YES;
+				CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
+				CLANG_WARN_BOOL_CONVERSION = YES;
+				CLANG_WARN_COMMA = YES;
+				CLANG_WARN_CONSTANT_CONVERSION = YES;
+				CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
+				CLANG_WARN_EMPTY_BODY = YES;
+				CLANG_WARN_ENUM_CONVERSION = YES;
+				CLANG_WARN_INFINITE_RECURSION = YES;
+				CLANG_WARN_INT_CONVERSION = YES;
+				CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
+				CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
+				CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
+				CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES;
+				CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
+				CLANG_WARN_STRICT_PROTOTYPES = YES;
+				CLANG_WARN_SUSPICIOUS_MOVE = YES;
+				CLANG_WARN_UNREACHABLE_CODE = YES;
+				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
+				DEAD_CODE_STRIPPING = YES;
+				ENABLE_STRICT_OBJC_MSGSEND = YES;
+				ENABLE_USER_SCRIPT_SANDBOXING = YES;
+				GCC_NO_COMMON_BLOCKS = YES;
+				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_RETURN_TYPE = YES;
+				GCC_WARN_UNDECLARED_SELECTOR = YES;
+				GCC_WARN_UNINITIALIZED_AUTOS = YES;
+				GCC_WARN_UNUSED_FUNCTION = YES;
+				GCC_WARN_UNUSED_VARIABLE = YES;
 			};
 			name = Release;
 		};

ForeC Analyser/Readme.txt → ForeC Analyser/Readme.md

@@ -1,5 +1,5 @@
-ForeC Analyser (multicore distribution)
----------------------------------------
+# ForeC Analyser (multicore distribution)
+
 Analyses ForeC programs compiled for execution on a 
 multicore MicroBlaze or PTARM single-core multi-threaded 
 processor.
@@ -8,24 +8,22 @@ Author: Eugene Kin Chee Yip
 Date: 5 October 2014
 
 
-Pre-requisites:
----------------
+## Pre-requisites:
 * Unix compatible system
 * Flex version 2.5.37 or later
 * Bison version 3.0 or later
 * C++ compiler
 * mb-gcc v4.1.2 (MicroBlaze compiler and objdump v2.16)
-    Download from http://www.xilinx.com/guest_resources/gnu/
-    Select "GNU Tools for MicroBlaze (gcc 4.1.2, gdb 6.5, binutils 2.16, newlib 1.14)".
+  * Download from http://www.xilinx.com/guest_resources/gnu/
+  * Select "GNU Tools for MicroBlaze (gcc 4.1.2, gdb 6.5, binutils 2.16, newlib 1.14)".
 * arm-linux-gnueabi-gcc or arm-none-eabi-gcc v4.7.1 (ARM compiler and objdump)
-    For Windows and Mac: Download from http://sourceforge.net/projects/yagarto/files
-    Note: objdump.c in binutils has to be amended to properly intermix the source code
+  * For Windows and Mac: Download from http://sourceforge.net/projects/yagarto/files
+  * Note: objdump.c in binutils has to be amended to properly intermix the source code
           with assembly instructions.
 * GNU make and relevant dependencies
 
 
-Installing on Linux:
---------------------
+## Installing on Linux:
 To create the "foreca" executable, the following commands need to be executed:
  $ make clean
  $ make
@@ -56,8 +54,7 @@ can be added to the PATH environment variable:
 Be careful of spaces in the path.
 
 
-Usage:
-------
+## Usage:
 $ foreca [-merge, -ccfg, uppaal] <-approach> [-debug] <source filename> <information filename>
 
 * -merge option:
@@ -88,47 +85,44 @@ $ foreca [-merge, -ccfg, uppaal] <-approach> [-debug] <source filename> <informa
 * <source filename>
   The source file can be the C code generated by the ForeC compiler. 
   In this case, the analyser will automatically compile the C code 
-  into binary and create an object dump file. The source can be the 
-  object dump file generated by a previous analysis. This will allow 
+  into binary and create an object dump file. The source can also be the
+  object dump file generated by a previous analysis. This will allow
   the generation of the dump file to be skipped.
   * Expected source code file extension: *.c
   * Expected object dump file extension: *.dump
 
 * <information filename>
-  The information file that is generated automatically by the ForeC compiler.
+  The information file that was generated automatically by the ForeC compiler.
   * Expected information file extension: *.xml
 
 * $ foreca -v 
   Returns the version information.
 
 
-Outputs:
---------
+## Outputs:
 * trace.xml
   * Optional trace information in XML format.
 * analysis.txt
   * Debugging information for each stage of analysis.
 
 
-Object File:
-------------
-Debugging information is expected to be included into the object file. For GCC, 
+## Object File:
+Debugging information is expected to be in the object file. For GCC,
 this would require compilation with the following commands:
  $ gcc -E -CC <source filename>.c -o <source filename>_preprocessed.c
  $ gcc -O0 -g <source filename>_preprocessed.c -o <source filename>.elf
 
-An example for Xilinx MicroBlaze specific programs:
+An example compilation for Xilinx MicroBlaze:
  $ mb-gcc -E -CC prog.c -o prog_expanded.c -I../microblaze_0/include/ -I../drivers/counter_dfsl_v1_00_a/src/ -I../drivers/forec_mutex_v1_00_a/src/
  $ mb-gcc -O0 -g prog_expanded.c -o prog.elf -mno-xl-soft-mul -mhard-float -mxl-float-convert -mxl-float-sqrt -mno-xl-soft-div -mcpu=v8.00.b -T forec_linker_script.ld -L../microblaze_0/lib/
 
 
-Object Dump File:
------------------
+## Object Dump File:
 The object dump file is expected to be produced from the compiled ForeC program
 (objectFile.elf) with the following command:
  $ objdump -dCrS -j .text <object name>.elf > <object name>.dump
 
-An example for Xilinx MicroBlaze specific programs:
+An example decompilation for Xilinx MicroBlaze:
  $ mb-objdump -dCrS -j .text prog.elf > prog.dump
 
 Important!: Over the years, objdump used different algorithms for intermixing the source code 
@@ -146,8 +140,7 @@ This prevents the use of earlier objdump with later GCC compilers.
 http://gcc.gnu.org/gcc-4.5/changes.html
 
 
-Information File:
------------------
+## Information File:
 Expected to contain the following information in xml format:
 * Thread-to-core allocation
 * Allocated cores per par(...) statement (Cores allocated to execute the child threads of a par(...)).
@@ -156,8 +149,7 @@ Expected to contain the following information in xml format:
 * Use/define of shared variables.
 
 
-Notes and Limitations:
-----------------------
+## Notes and Limitations:
 * Only worst-case estimations are used for instructions.
 * For TDMA arbitration, the worst-case delay is (slot size) * (number of cores - 1) + (memory access delay - 1)
 * Access to global data is assumed when:
@@ -190,17 +182,17 @@ Notes and Limitations:
     explored for each interleaving.
   - Conditional updating of copies of shared variables (policy "mod") when a par(...) terminates.
 * Instantaneous loops may not be detected by the analysis algorithm.
-  - The ForeC compiler will alert the programmer about a broad range of loops that may be instantaneous.
+  - The ForeC compiler will pessimistically alert the programmer to loops that may be instantaneous.
   - As an additional line of defence, the analyser will also try and detect instantaneous loops.
   - The analyser does not check for instantaneous loops if the merge option is not invoked.
   - The merging algorithm can only detect instantaneous loops via a direct edge (i.e., without intermediate nodes).
   - Otherwise, an instantaneous loop will cause the analyser to run forever.
   - Loop bounds take precedence even when the loop is non-instantaneous.
 * Sources of imprecision:
-  - Over-estimation of memory accesses that as global accesses.
+  - Over-estimation of local memory accesses as global accesses.
   - Combining of shared variables:
     If no copies satisify the combine policy, then the analyser should not add the cost of combining.
-	This cost appears when a par(...) pauses or terminates.
+	This cost is incurred when a par(...) pauses or terminates.
   - Inter-core synchronisation:
     Timing over-estimation in the receiving of thread/core statuses. Always assume that the statuses are 
 	available just after they have been checked.
@@ -220,6 +212,5 @@ MicroBlaze Global Memory Access Times (clock cycles):
 
 PTARM Global Memory Access Times (thread cycles):
 -------------------------------------------------
-* Scratch Pad: Load = 1, Store = 1.
 * DDR SDRAM: Load = 2, Store = 2.
-
+* Scratch Pad: Load = 1, Store = 1.

ForeC Compiler/Main.cpp

@@ -269,7 +269,7 @@ void updateSymbolTable(forec::ast::Root &astRoot) {
 	} 
 
 	std::set<forec::ast::PrimaryExpression *> combineUnneeded;
-	// uneeded = specified - needed
+	// unneeded = specified - needed
 	std::set_difference(combineSpecified.begin(), combineSpecified.end(), combineNeeded.begin(), combineNeeded.end(), std::inserter(combineUnneeded, combineUnneeded.end()));
 	if (!combineUnneeded.empty()) {
 		std::cout << std::endl << "* These variables do not need a combine function:" << std::endl;