Commit 0a10e791 authored by Christian Fibich's avatar Christian Fibich Committed by Stefan Tauner
Browse files

Added README for FIC emulator + some refactoring

parent c4bd05ac
......@@ -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}
......
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
......
# 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
/*
* 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);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment