Merge pull request #416 from perftool-incubator/runfile-doc

Update run file doc

.github/workflows/crucible-ci.yaml

@@ -6,6 +6,7 @@ on:
     paths-ignore:
     - LICENSE
     - '**.md'
+    - .github/workflows/faux-unittest.yaml
     - .github/workflows/faux-crucible-ci.yaml
     - 'docs/**'
     - engine/engine-script-library.py

.github/workflows/faux-unittest.yaml

@@ -2,7 +2,7 @@ name: faux-unittest
 
 on:
   pull_request:
-    branches: [ main ]
+    branches: [ master ]
     paths:
       - LICENSE
       - '**.md'

util/README.md

@@ -11,8 +11,47 @@ configuration by using a single JSON file. Users can specify multi-value
 parameters, tools, tags, endpoints, and run parameters, all using an unified
 JSON format, in one single place.
 
+For examples, refer to the [crucible-examples](https://github.com/perftool-incubator/crucible-examples/tree/main/runfile)
+repository.
+
+## Format
+The config runfile structure is the following:
+```
+{
+    "benchmarks": [
+        {
+            (...)
+            "mv-params": {
+                (...)
+            }
+        }
+    ]
+    "tool-params": [
+        (...)
+    ],
+    "tags": {
+        (...)
+    },
+    "endpoints": [
+        (...)
+    ],
+    "run-params": {
+        (...)
+    }
+}
+```
+where:
+ * `benchmarks`: benchmark definitions
+     * `mv-params`: benchmark specific params
+ * `tool-params`: performance tool params, e.g. perf, sysstat, procstat, etc.
+ * `tags`: tags to identify the test run in the form of "key":"value"
+ * `endpoints`: endpoint definitions and configuration settings
+ * `run-params`: addtional (optional) command line params, e.g. number of samples
+
 For more details on the supported format, refer to the JSON [schema](JSON/schema.json).
 
+## Usage
+
 To validate a run-file, run:
 ```
 python3 validate_run_file.py --json <run-file-json> 
@@ -23,7 +62,7 @@ To use a run-file JSON in Crucible, run:
 crucible run --from-file <run-file-json>
 ```
 
-## blockbreaker.py utility
+### blockbreaker.py utility
 
 The "blockbreaker.py" utility extracts a configuration block from the
 run-file JSON and transforms into a JSON block or stream output.
@@ -34,7 +73,7 @@ python3 blockbreaker.py --json <run-file-json> --config <config>
 ```
 Example:
 ```
-python3 blockbreaker.py --json run-file.json --config mv-params
+python3 blockbreaker.py --json run-file.json --config mv-params --benchmark iperf
 ```
 For more options and usage run:
 ```