Improve documentation and command line consistancy

mubes · mubes · commit 94bc1990957f · 2024-09-05T00:37:37.000+01:00
diff --git a/CHANGES.md b/CHANGES.md
@@ -18,6 +18,7 @@ In Progress (Version 2.2.0)
 * improved support for C++
 * Addition of ETM4 decode (experimental)
 * Timestamping for orbtop, in various formats
+* Colour support in orbcat for metadata (timestamps)
 * Exception reporting for orbtop
 * OSX CI Builder support
 * Orbuculum can now be used as a meson subproject
diff --git a/Inc/generics.h b/Inc/generics.h
@@ -86,7 +86,7 @@ extern "C" {
 /* Memory sizes */
 typedef uint32_t symbolMemaddr;
 typedef unsigned char *symbolMemptr;
-  
+
 // ====================================================================================================
 enum verbLevel {V_ERROR, V_WARN, V_INFO, V_DEBUG, V_MAX_VERBLEVEL};
 
diff --git a/README.md b/README.md
diff --git a/Src/orbdump.c b/Src/orbdump.c
@@ -104,7 +104,7 @@ void _printHelp( const char *const progName )
     genericsPrintf( "    -M, --no-colour:    Supress colour in output" EOL );
     genericsPrintf( "    -n, --itm-sync:     Enforce sync requirement for ITM (i.e. ITM needs to issue syncs)" EOL );
     genericsPrintf( "    -o, --output-file:  <filename> to be used for dump file (defaults to %s)" EOL, options.outfile );
-    genericsPrintf( "    -p, --protocol:     Protocol to communicate. Defaults to OFLOW if -s is not set, otherwise ITM unless" EOL );
+    genericsPrintf( "    -p, --protocol:     Protocol to communicate. Defaults to OFLOW if -s is not set, otherwise ITM" EOL );
     genericsPrintf( "    -s, --server:       <Server>:<Port> to use" EOL );
     genericsPrintf( "    -t, --tag:          <stream> Which Orbflow tag to use (normally 1)" EOL );
     genericsPrintf( "    -v, --verbose:      <level> Verbose mode 0(errors)..3(debug)" EOL );
diff --git a/Src/orbfifo.c b/Src/orbfifo.c
@@ -74,7 +74,7 @@ static void _printHelp( const char *const progName )
     genericsPrintf( "Usage: %s [options]" EOL, progName );
     genericsPrintf( "    -b, --basedir:      <basedir> for channels" EOL );
     genericsPrintf( "    -c, --channel:      <Number>,<Name>,<Format> of channel to populate (repeat per channel)" EOL );
-    genericsPrintf( "    -E, --eof:          When reading from file, terminate at end of file rather than waiting for further input" EOL );
+    genericsPrintf( "    -E, --eof:          When reading from file, terminate at end of file" EOL );
     genericsPrintf( "    -f, --input-file:   <filename> Take input from specified file" EOL );
     genericsPrintf( "    -h, --help:         This help" EOL );
     genericsPrintf( "    -M, --no-colour:    Supress colour in output" EOL );
diff --git a/Src/orblcd.c b/Src/orblcd.c
@@ -430,11 +430,11 @@ void _printHelp( const char *const progName )
     genericsPrintf( "    -p, --protocol:     Protocol to communicate. Defaults to OFLOW if -s is not set, otherwise ITM" EOL );
     genericsPrintf( "    -s, --server:       <Server>:<Port> to use" EOL );
     genericsPrintf( "    -S, --sbcolour:     <Colour> to be used for single bit renders, ignored for other bit depths" EOL );
-    genericsPrintf( "    -t, --tag:          <stream>: Which OFLOW tag to use (normally 1)" EOL );
+    genericsPrintf( "    -t, --tag:          <stream> Which OFLOW tag to use (normally 1)" EOL );
     genericsPrintf( "    -v, --verbose:      <level> Verbose mode 0(errors)..3(debug)" EOL );
     genericsPrintf( "    -V, --version:      Print version and exit" EOL );
     genericsPrintf( "    -w, --window:       <string> Set title for output window" EOL );
-    genericsPrintf( "    -z, --size:         <Scale(float)> Set relative size of output window (normally 1)" EOL );
+    genericsPrintf( "    -z, --size:         <Scale(float)> Set relative size of output window (normally 1.0)" EOL );
 }
 
 // ====================================================================================================
diff --git a/Src/orbmortem.c b/Src/orbmortem.c
@@ -174,7 +174,7 @@ static void _printHelp( const char *const progName )
     genericsPrintf( "    -D, --no-demangle:  Switch off C++ symbol demangling" EOL );
     genericsPrintf( "    -d, --del-prefix:   <String> Material to delete off the front of filenames" EOL );
     genericsPrintf( "    -e, --elf-file:     <ElfFile> to use for symbols and source" EOL );
-    genericsPrintf( "    -E, --eof:          When reading from file, terminate at end of file rather than waiting for further input" EOL );
+    genericsPrintf( "    -E, --eof:          When reading from file, terminate at end of file" EOL );
     genericsPrintf( "    -f, --input-file:   <filename>: Take input from specified file" EOL );
     genericsPrintf( "    -h, --help:         This help" EOL );
     genericsPrintf( "    -M, --no-colour:    Supress colour in output" EOL );
@@ -192,8 +192,8 @@ static void _printHelp( const char *const progName )
     genericsPrintf( "    -t, --tag:          <stream>: Which OFLOW tag to use (normally 2)" EOL );
     genericsPrintf( "    -v, --verbose:      <level> Verbose mode 0(errors)..3(debug)" EOL );
     genericsPrintf( "    -V, --version:      Print version and exit" EOL );
-    genericsPrintf( EOL "(Will connect one port higher than that set in -s for legacy protocol)" EOL );
-    genericsPrintf(     "(this will automatically select the second output stream from orbuculum.)" EOL );
+    genericsPrintf( EOL "(Legacy protocol will connect one port higher than that set in -s)" EOL );
+    genericsPrintf(     "(This will automatically select the second output stream from orbuculum.)" EOL );
     genericsPrintf( EOL "Environment Variables;" EOL );
     genericsPrintf( "  OBJDUMP: to use non-standard objdump binary" EOL );
 }
diff --git a/Src/orbprofile.c b/Src/orbprofile.c
@@ -462,7 +462,7 @@ static void _printHelp( const char *const progName )
     genericsPrintf( "    -D, --no-demangle:  Switch off C++ symbol demangling" EOL );
     genericsPrintf( "    -d, --del-prefix:   <String> Material to delete off front of filenames" EOL );
     genericsPrintf( "    -e, --elf-file:     <ElfFile> to use for symbols" EOL );
-    genericsPrintf( "    -E, --eof:          When reading from file, terminate at end of file rather than waiting for further input" EOL );
+    genericsPrintf( "    -E, --eof:          When reading from file, terminate at EOF" EOL );
     genericsPrintf( "    -f, --input-file:   Take input from specified file" EOL );
     genericsPrintf( "    -h, --help:         This help" EOL );
     genericsPrintf( "    -I, --interval:     <Interval> Time between samples (in ms)" EOL );
diff --git a/Src/orbstat.c b/Src/orbstat.c
@@ -408,9 +408,9 @@ static void _printHelp( struct RunTime *r )
     genericsPrintf( "    -D, --no-demangle:  Switch off C++ symbol demangling" EOL );
     genericsPrintf( "    -d, --del-prefix:   <String> Material to delete off front of filenames" EOL );
     genericsPrintf( "    -e, --elf-file:     <ElfFile> to use for symbols" EOL );
-    genericsPrintf( "    -E, --eof:          When reading from file, terminate at end of file rather than waiting for further input" EOL );
+    genericsPrintf( "    -E, --eof:          When reading from file, terminate at end of file" EOL );
     genericsPrintf( "    -f, --input-file:   <filename>: Take input from specified file" EOL );
-    genericsPrintf( "    -g, --trace-chn:    <TraceChannel> for trace output (default %d)" EOL, r->options->traceChannel );
+    genericsPrintf( "    -g, --trace-chn:    <TraceChannel> ITM channel for trace (default %d)" EOL, r->options->traceChannel );
     genericsPrintf( "    -h, --help:         This help" EOL );
     genericsPrintf( "    -I, --interval:     <Interval>: Time to sample (in mS)" EOL );
     genericsPrintf( "    -n, --itm-sync:     Enforce sync requirement for ITM (i.e. ITM needs to issue syncs)" EOL );
@@ -424,8 +424,6 @@ static void _printHelp( struct RunTime *r )
     genericsPrintf( "    -V, --version:      Print version and exit" EOL );
     genericsPrintf( "    -y, --graph-file:   <Filename> dotty filename for structured callgraph output" EOL );
     genericsPrintf( "    -z, --cache-file:   <Filename> profile filename for kcachegrind output" EOL );
-    genericsPrintf( EOL "(Will connect one port higher than that set in -s when Orbflow is not used)" EOL );
-
 }
 // ====================================================================================================
 void _printVersion( void )
diff --git a/Src/orbtrace.c b/Src/orbtrace.c
@@ -142,9 +142,10 @@ static void _printHelp( const char *const progName )
     genericsPrintf( "       -e, --power:         <Ch>,<On> Enable or Disable power. Ch is vtref, vtpwr or all" EOL );
     genericsPrintf( "       -h, --help::         This help" EOL );
     genericsPrintf( "       -l, --list:          Show all OrbTrace devices attached to system" EOL );
-    genericsPrintf( "       -M, --no-colour:    Supress colour in output" EOL );
-    genericsPrintf( "       -T, --trace-format:  <x> Trace format; 1,2 or 4 bit parallel, m for Manchester SWO, u=UART SWO," EOL );
-    genericsPrintf( "                                              M for Manchester SWO with TPIU decode, U=UART SWO with TPIU decode" EOL );
+    genericsPrintf( "       -M, --no-colour:     Supress colour in output" EOL );
+    genericsPrintf( "       -T, --trace-format:  <x> Trace format; 1,2 or 4 bit parallel with TPIU decode," EOL \
+                    "                                              m for Manchester SWO, u=UART SWO," EOL \
+                    "                                              M for Manchester SWO+TPIU, U=UART SWO+TPIU" EOL );
     genericsPrintf( "       -n, --serial-number: <Serial> any part of serial number to differentiate specific OrbTrace device" EOL );
     genericsPrintf( "       -p, --voltage:       <Ch>,<Voltage> Set voltage in V, Ch is vtref or vtpwr" EOL );
     genericsPrintf( "       -v, --verbose:       <level> Verbose mode 0(errors)..3(debug)" EOL );
diff --git a/Src/orbuculum.c b/Src/orbuculum.c
@@ -104,7 +104,7 @@ struct Options
     bool mono;                                           /* Supress colour in output */
     int paceDelay;                                       /* Delay between blocks of data transmission in file readout */
     char *channelList;                                   /* List of channels to be exported over legacy connection */
-    bool hiresTime;                                      /* Use hiresolution time (shorter timeouts...more accurate but higher load */
+    bool hiresTime;                                      /* Use hiresolution time (shorter timeouts...obsolete) */
     char *sn;                                            /* Any part serial number for identifying a specific device */
     int listenPort;                                      /* Listening port for network */
 };
@@ -356,7 +356,6 @@ void _printHelp( const char *const progName, struct RunTime *r )
     genericsPrintf( "    -E, --eof:           When reading from file, terminate at end of file" EOL );
     genericsPrintf( "    -f, --input-file:    <filename> Take input from specified file" EOL );
     genericsPrintf( "    -h, --help:          This help" EOL );
-    genericsPrintf( "    -H, --hires:         High resolution time (much higher CPU load though!)" EOL );
     genericsPrintf( "    -l, --listen-port:   <port> Listen port for incoming ORBFLOW connections (defaults to %d)" EOL, r->options->listenPort );
     genericsPrintf( "    -m, --monitor:       <interval> Output monitor information about the link at <interval>ms, min 500ms" EOL );
     genericsPrintf( "    -M, --no-colour:     Supress colour in output" EOL );
@@ -367,7 +366,7 @@ void _printHelp( const char *const progName, struct RunTime *r )
     genericsPrintf( "    -P, --pace:          <microseconds> delay in block of data transmission to clients" EOL );
     genericsPrintf( "    -s, --server:        <Server>:<Port> to use" EOL );
     genericsPrintf( "    -T, --tpiu:          Strip TPIU framing from input flows (mostly not relevant)" EOL );
-    genericsPrintf( "    -t, --tag:           <stream,stream....> TPIU streams to decode and onward route (Default %s)" EOL, r->options->channelList );
+    genericsPrintf( "    -t, --tag:           <stream,stream....> Legacy TPIU streams to decode and route (Default %s)" EOL, r->options->channelList );
     genericsPrintf( "    -v, --verbose:       <level> Verbose mode 0(errors)..3(debug)" EOL );
     genericsPrintf( "    -V, --version:       Print version, connected usb devices, and exit" EOL );
 }
@@ -400,7 +399,6 @@ static struct option _longOptions[] =
     {"eof", no_argument, NULL, 'E'},
     {"input-file", required_argument, NULL, 'f'},
     {"help", no_argument, NULL, 'h'},
-    {"hires", no_argument, NULL, 'H'},
     {"listen-port", required_argument, NULL, 'l'},
     {"monitor", required_argument, NULL, 'm'},
     {"no-colour", no_argument, NULL, 'M'},
@@ -424,7 +422,7 @@ bool _processOptions( int argc, char *argv[], struct RunTime *r )
     int c, optionIndex = 0;
 #define DELIMITER ','
 
-    while ( ( c = getopt_long ( argc, argv, "a:Ef:hHVl:m:Mn:o:O:p:P:s:Tt:v:", _longOptions, &optionIndex ) ) != -1 )
+    while ( ( c = getopt_long ( argc, argv, "a:Ef:hVl:m:Mn:o:O:p:P:s:Tt:v:", _longOptions, &optionIndex ) ) != -1 )
         switch ( c )
         {
             // ------------------------------------
@@ -456,11 +454,6 @@ bool _processOptions( int argc, char *argv[], struct RunTime *r )
                 _printHelp( argv[0], r );
                 return false;
 
-            // ------------------------------------
-            case 'H':
-                r->options->hiresTime = true;
-                break;
-
             // ------------------------------------
 
             case 'V':
