Added README for FIC emulator + some refactoring

docs/technical_reference_manual/content/03-software.tex

@@ -150,8 +150,70 @@ only HTML output is created as specified in the configuration file Doxyfile.
 \subsection{\ac{FIC} Emulator}
 \label{sec:fic_emulator}
 
-\todo{Document}
+The \ac{FIC} emulator is intended for testing/debugging the FIJI EE scripts.
+It emulates the FIJI \ac{FIC} (Fault Injection Controller) by sending appropriate
+\texttt{CONF\_DONE} and \texttt{READY} messages. It can also be instructed to send
+\texttt{UNDERRUN} messages. Moreover, the UART, ID, and CRC error bits as well as 
+fault detect bits can be set at run-time. The \ac{FIC} emulator is written in C.
+
+To use the \ac{FIC} emulator, the following preqrequisites are necessary:
+
+\begin{itemize}
+    \item A program to create a pair of connected terminals, e.g. socat\footnote{\url{http://www.dest-unreach.org/socat/}}
+    \item A terminal supporting the POSIX termios interface (\texttt{tcgetattr()} and \texttt{tcsetattr()}) and ANSI escape sequences
+\end{itemize}
+
+A matching FIC Emulator executable needs to be generated for each FIJI
+configuration. The following parameters in the FIJI configuration file (*.cfg)
+influence the configuration message length and thus the behavior of this program:
+
+\begin{itemize}
+    \item \texttt{FIU\_CFG\_BITS}: Bits per FIU fault pattern
+    \item \texttt{FIU\_NUM}: Number of FIUs
+    \item \texttt{CFGS\_PER\_MSG}: Number of fault patterns for each FIU per message
+    \item \texttt{TIMER\_WIDTH}: Width of the timer values
+\end{itemize}
+
+The configuration file can be passed to the Makefile via the variable
+\texttt{FIJI\_CFG\_FILE}. The Makefile then parses the constants described above
+out of the configuration file.
+
+For example, build the FIC emulator using:
+
+    \texttt{\$ make FIJI\_CFG\_FILE=\textasciitilde/fiji/test\_1/fiji.cfg}
+
+It is also possible to pass the constants directly to the compiler using:
+
+    \texttt{\$ gcc fic-emulator.c -DFIU\_CFG\_BITS=... -DFIU\_NUM=... -DCFGS\_PER\_MSG=... -DTIMER\_WIDTH=...}
+
+Once compiled, the FIC emulator may be used as follows:
+
+\texttt{\$ fic-emulator [-d DEVICE] [-c PERIOD] [-h]}
+
+The command-line options have the following meanings:
+
+\begin{itemize}
+    \item \texttt{-d DEVICE} The terminal device to be used, e.g., \texttt{/dev/pts/2}
+    \item \texttt{-c PERIOD} The FIC emulator can be instructed to actually
+                        wait during the T1/T2 durations. It multiplies the
+                        durations with the clock period in microsecond
+                        passed with this parameter.
+    \item \texttt{-h}   Display a short usage information including the
+                        compile-time configuration
+\end{itemize}
+
+To run the FIC emulator, first a pair of pseudo terminals need to be set up.
+This may be done using \texttt{socat} as follows:
+
+    \texttt{\$ socat -d -d pty,raw,echo=0 pty,raw,echo=0}
+
+Then the \ac{FIC} emulator may be launched on one of the terminals.
 
+When the \ac{FIC} emulator is running, in the status line at the bottom
+the current configuration of the FD lines, UNDERRUN, UART, ID, and
+CRC flags can be seen. The configuration can be changed by pressing
+any of the keys shown above the status line. The terminal to which the
+emulator is connected is shown at the top.
 
 \subsection{Instrumentation Tests}
 \label{sec:instrumentation_tests}

test/fic_emulator/Makefile

-FIJI_CFG_FILE=../../bin/fiji.cfg
+FIJI_CFG_FILE?=../../docs/demos/tmr_vga/fiji/de0_test_1/fiji/fiji.cfg
 FIU_NUM=$(shell sed -nr 's/^FIU_NUM=([0-9]+)$$/\1/p' $(FIJI_CFG_FILE))
-FIU_BITS=$(shell sed -nr 's/^FIU_CFG_BITS=([0-9]+)$$/\1/p' $(FIJI_CFG_FILE))
-NUM_CFGS=$(shell sed -nr 's/^CFGS_PER_MSG=([0-9]+)$$/\1/p' $(FIJI_CFG_FILE))
+FIU_CFG_BITS=$(shell sed -nr 's/^FIU_CFG_BITS=([0-9]+)$$/\1/p' $(FIJI_CFG_FILE))
+CFGS_PER_MSG=$(shell sed -nr 's/^CFGS_PER_MSG=([0-9]+)$$/\1/p' $(FIJI_CFG_FILE))
 TIMER_BYTES=$(shell sed -nr 's/^TIMER_WIDTH=([0-9]+)$$/\1/p' $(FIJI_CFG_FILE))
 
 .PHONY: clean
 
-dummy: $(FIJI_CFG_FILE) dummy.c
-	gcc -std=c11 dummy.c \
+fic-emulator: fic-emulator.c $(FIJI_CFG_FILE)
+	gcc -Wall -Wextra -pedantic -std=c11 $< \
+                 -DCFG_FILE='"$(FIJI_CFG_FILE)"' \
                  -DFIU_NUM=$(FIU_NUM) \
-                 -DFIU_BITS=$(FIU_BITS) \
-                 -DNUM_CFGS=$(NUM_CFGS) \
+                 -DFIU_CFG_BITS=$(FIU_CFG_BITS) \
+                 -DCFGS_PER_MSG=$(CFGS_PER_MSG) \
                  -DTIMER_BYTES=$(TIMER_BYTES) \
-                 -o dummy
+                 -o $@
 
-debug-dummy: $(FIJI_CFG_FILE) dummy.c
-	gcc -std=c11 dummy.c \
+fic-emulator-debug: fic-emulator.c $(FIJI_CFG_FILE)
+	gcc -Wall -Wextra -pedantic -std=c11 $< \
+                 -DCFG_FILE='"$(FIJI_CFG_FILE)"' \
                  -DFIU_NUM=$(FIU_NUM) \
-                 -DFIU_BITS=$(FIU_BITS) \
-                 -DNUM_CFGS=$(NUM_CFGS) \
+                 -DFIU_CFG_BITS=$(FIU_CFG_BITS) \
+                 -DCFGS_PER_MSG=$(CFGS_PER_MSG) \
                  -DTIMER_BYTES=$(TIMER_BYTES) \
-                 -o debug-dummy \
+                 -o $@ \
                  -g \
                  -DDEBUG
 

test/fic_emulator/README.md

+# FIC Emulator
+
+This program is intended for testing/debugging the FIJI EE scripts.
+It emulates the FIJI FIC (Fault Injection Controller) by sending 
+appropriate `CONF_DONE` and `READY` messages. It can also be instructed
+to send `UNDERRUN` messages.
+
+## Building
+
+A matching FIC Emulator needs to be compiled for a FIJI configuration.
+The following parameters in the FIJI configuration file (*.cfg) influence
+the configuration message length and thus the behavior of this program:
+
+* `FIU_BITS`: Bits per FIU fault pattern
+* `FIU_NUM`: Number of FIUs
+* `CFGS_PER_MSG`: Number of fault patterns for each FIU per message
+* `TIMER_WIDTH`: Width of the timer values
+
+The configuration file can be passed to the Makefile via the variable
+`FIJI_CFG_FILE`.
+
+For example, build the FIC emulator using:
+
+    make FIJI_CFG_FILE=~/fiji/test_1/fiji.cfg
+
+## Usage
+
+The FIC emulator may be used as follows:
+
+    $ fic-emulator [-d DEVICE] [-c PERIOD] [-h]
+    
+        -d DEVICE       The terminal device to be used, e.g., /dev/pts/2
+        -c PERIOD       The FIC emulator can be instructed to actually
+                        wait during the T1/T2 durations. It multiplies the
+                        durations with the clock period in microsecond
+                        passed with this parameter.
+        -h              Display a short usage information including the
+                        compile-time configuration
+
+## Step-by-step Example
+
+To run the FIC emulator, you first need to set up a pair of pseudo terminals.
+
+You may do so using socat as follows:
+
+    socat -d -d pty,raw,echo=0 pty,raw,echo=0
+
+Then you need to launch the FIC emulator on one of the terminals.
+
+![FIC Emulator Screenshot](fic-emulator.png)
+
+When the FIC emulator is running, in the status line at the bottom
+the current configuration of the FD lines, UNDERRUN, UART, ID, and
+CRC flags can be seen. The configuration can be changed by pressing
+any of the keys shown above the status line. The terminal to which the
+emulator is connected is shown at the top.
+
+## Prerequisities
+
+* A program to create a pair of connected terminals, e.g. [http://www.dest-unreach.org/socat/](`socat`)
+* A terminal supporting the POSIX termios interface (`tcgetattr()` and `tcsetattr()`) and ANSI escape sequences
+
+## License
+
+FIXME

test/fic_emulator/dummy.c → test/fic_emulator/fic-emulator.c

-/*
- * FIC emulator
- * 1. use e.g. socat -d -d pty,raw,echo=0 pty,raw,echo=0 to emulate a pair
- *          of terminals
- * 2. let fiji_ee.pl or fiji_ee_gui.pl run on the one terminal
- * 3. start dummy -d /path/to/other/term
+/***********************************************************************
+ *  University of Applied Sciences Technikum Wien
  *
- * optionally, set a clock period using -c <period in us>
+ *  Department of Embedded Systems
+ *  http://embsys.technikum*wien.at
  *
- * During testing, the Error/status bits of the return message can be
- * modified.
+ *  Josef Ressel Center for Verification of Embedded Computing Systems
+ *  http://vecs.technikum*wien.at
+ *
+ ***********************************************************************
+ *  File:              fic-emulator.c
+ *  Author:            Christian Fibich
+ *  Created on:        2015-12-15
+ *
+ *  Description: FIC emulator
+ *
+ *  1. use e.g.
+ *          $ socat -d -d pty,raw,echo=0 pty,raw,echo=0
+ *     to emulate a pair of terminals
+ *
+ *  2. start fic-emulator on one terminal (-d /path/to/terminal)
+ *
+ *  3. let fiji_ee.pl or fiji_ee_gui.pl run on the other terminal
+ *
+ *  optionally, set a clock period using -c <period in us>
+ *
+ *  During testing, the Error/status bits of the return message can be
+ *  modified, and UNDERRUN messages instructed to be sent.
  */
 
 
@@ -30,9 +47,13 @@
 #define PATH "/dev/pts/2"
 #define CEILING(x,y) (((x) + (y) - 1) / (y))
 
+#ifndef CFG_FILE
+#define CFG_FILE "Ad-hoc config"
+#endif
+
 #define FIU_OFFSET    (0)
-#define TIMER_OFFSET  (FIU_OFFSET+CEILING(FIU_NUM*FIU_BITS*NUM_CFGS,8))
-#define CONFIG_OFFSET (TIMER_OFFSET+(NUM_CFGS*TIMER_BYTES))
+#define TIMER_OFFSET  (FIU_OFFSET+CEILING(FIU_NUM*FIU_CFG_BITS*CFGS_PER_MSG,8))
+#define CONFIG_OFFSET (TIMER_OFFSET+(CFGS_PER_MSG*TIMER_BYTES))
 #define ID_OFFSET     (CONFIG_OFFSET+1)
 #define CRC_OFFSET    (ID_OFFSET+2)
 #define NUM_BYTES     (CRC_OFFSET+1)
@@ -105,7 +126,7 @@ void putstatus(uint8_t msg, uint8_t err, uint8_t underrun, uint8_t *rmsg, unsign
     int wr1=0,wr2=0,wt;
     char *str;
 
-    if ((wr1 = asprintf(&str,"\rFD0: %d FD1: %d UART: %d ID: %d CRC: %d UNDERRUN: %d%n", 
+    if ((wr1 = asprintf(&str,"\rFD0: %d FD1: %d UART: %d ID: %d CRC: %d UNDERRUN: %d%n",
             (msg & FD0) > 0,
             (msg & FD1) > 0,
             (err & U)   > 0,
@@ -118,7 +139,6 @@ void putstatus(uint8_t msg, uint8_t err, uint8_t underrun, uint8_t *rmsg, unsign
     free(str);
 
     if (rmsg != NULL) {
-        nmsg;
         if((wr2 =asprintf(&str,"%15d total received. Latest message (CRC8): 0x%02x%n", nmsg, *rmsg, &wr2)) < 0) {
             return;
         }
@@ -158,9 +178,11 @@ int main (int argc, char *argv[]) {
     fd_set rfds;
     struct timeval tv;
     int retval;
+    int exit_code = EXIT_FAILURE;
+    FILE *usage_stream = stderr;
     char dat;
 
-    while ((opt = getopt(argc, argv, "d:c:")) != -1) {
+    while ((opt = getopt(argc, argv, "d:c:h")) != -1) {
         switch (opt) {
             case 'd':
                 path = optarg;
@@ -168,10 +190,18 @@ int main (int argc, char *argv[]) {
             case 'c':
                 period = atof(optarg);
             break;
+            case 'h':
+                exit_code    = EXIT_SUCCESS;
+                usage_stream = stdout;
             default: /* '?' */
-                fprintf(stderr, "Usage: %s [-d device] [-c period_in_us]\n",
-                       argv[0]);
-                exit(EXIT_FAILURE);
+                fprintf(usage_stream, "Usage: %s [-d DEVICE] [-c PERIOD] [-h]\n\n" \
+                                "Built for %s\n"\
+                                "   FIU_NUM=%d\n" \
+                                "   FIU_CFG_BITS=%d\n"\
+                                "   CFGS_PER_MSG=%d\n"\
+                                "   TIMER_BYTES=%d\n",
+                                argv[0],CFG_FILE,FIU_NUM,FIU_CFG_BITS,CFGS_PER_MSG,TIMER_BYTES);
+                exit(exit_code);
         }
     }
 
@@ -272,7 +302,7 @@ int main (int argc, char *argv[]) {
             RESTORE_TERM();
             exit(EXIT_FAILURE);
         }
-    
+
 #ifdef DEBUG
         for (int i = 0; i < NUM_BYTES; i++) {
             fprintf(stderr,"%02d: 0x%02x\n",i, in[i]);
@@ -280,7 +310,7 @@ int main (int argc, char *argv[]) {
 #endif
         putstatus(msg,err,underrun,(in + CRC_OFFSET),++nmsg);
 
-        
+
         ret = MSG_TYPE_CONF_DONE;
         ret |= msg;
         ret |= err;
@@ -291,15 +321,15 @@ int main (int argc, char *argv[]) {
             RESTORE_TERM();
             exit(EXIT_FAILURE);
         }
-        
+
         if(*(in+CONFIG_OFFSET) & UPDATE_FLAG) {
 #ifdef DEBUG
             fprintf(stderr,"Update only.\n");
 #endif
             continue;
         }
-        
-        
+
+
         if (period != 0) {
 #ifdef DEBUG
             fprintf(stderr,"Sleeping T1: %lf us\n",gettime(in+TIMER_OFFSET) * period);