Add documentation for the configuration file mechanism
Bug: b/216019572
Change-Id: I8b7a1d5072fdeda877a55091839fbdc660ab19ed
Reviewed-on: https://swiftshader-review.googlesource.com/c/SwiftShader/+/64708
Reviewed-by: Nicolas Capens <nicolascapens@google.com>
Kokoro-Result: kokoro <noreply+kokoro@google.com>
Tested-by: Daniele Vettorel <dvet@google.com>
Commit-Queue: Daniele Vettorel <dvet@google.com>
diff --git a/docs/RuntimeConfiguration.md b/docs/RuntimeConfiguration.md
new file mode 100644
index 0000000..cbe5c19
--- /dev/null
+++ b/docs/RuntimeConfiguration.md
@@ -0,0 +1,34 @@
+Runtime Configuration
+=========================
+
+SwiftShader provides a simple configuration mechanism based on a configuration file to control a variety of runtime options without needing to re-compile from source.
+
+Configuration file
+------------
+
+SwiftShader looks for a file named `SwiftShader.ini` (case-sensitive) in the working directory. At startup, SwiftShader reads this file, if it exists, and sets the options specified in it.
+
+The configuration file syntax is a series of key-value pairs, divided into sections. The following example shows three key-value pairs in two sections (`ThreadCount` and `AffinityMask` in the `[Processor]` section, and `AsmEmitDir` in the `[Debug]` section):
+```
+[Processor]
+ThreadCount=4
+AffinityMask=0xf
+
+# Comment
+[Debug]
+AsmEmitDir=/home/user/asm_dumps
+```
+
+The syntax rules are as follows:
+* Sections are defined via a name in brackets, e.g. `[Processor]`.
+* Key-value pairs are in the format `Key=Value`.
+* Keys are always strings, while values can be strings, booleans or integers depending on the semantics of the option:
+ * For integer options, both decimal and hexademical values are supported.
+ * For boolean options, both decimal (`1` and `0`) and alphabetical (`true` and `false`) values are supported.
+* Comments are supported through the use of the `#` character at the beginning of a line.
+
+Options
+------------
+
+Refer to the [SwiftConfig.hpp](../src/System/SwiftConfig.hpp) header for an up-to-date overview of available options.
+
diff --git a/src/System/SwiftConfig.hpp b/src/System/SwiftConfig.hpp
index ebe5a35..73ec336 100644
--- a/src/System/SwiftConfig.hpp
+++ b/src/System/SwiftConfig.hpp
@@ -31,6 +31,7 @@
OneOf = 1,
};
+ // -------- [Processor] --------
// Number of threads used by the scheduler. A thread count of 0 is
// interpreted as min(cpu_cores_available, 16).
uint32_t threadCount = 0;
@@ -39,9 +40,11 @@
uint64_t affinityMask = 0xffffffffffffffff;
AffinityPolicy affinityPolicy = AffinityPolicy::AnyOf;
+ // -------- [Debug] --------
// Directory where ASM listings of JITted code will be emitted.
std::string asmEmitDir = "";
+ // -------- [Profiler] --------
// Whether SPIR-V profiling is enabled.
bool enableSpirvProfiling = false;
// Period controlling how often SPIR-V profiles are reported.
