Update mdbook documentation

mdbook/src/README.md

@@ -39,11 +39,11 @@ insanely high. If your active logic requires a high clock speed and
 
 # Table of contents
 
-- [Register files](registerfile.md)
-  - [Metadata](metadata.md)
-  - [Register file features](registerfilefeatures.md)
-  - [VHDL interface options](interfaceoptions.md)
-  - [Field descriptors](fielddescriptor.md)
+- [Register files](registerfileconfig.md)
+  - [Metadata](metadataconfig.md)
+  - [Register file options](featureconfig.md)
+  - [VHDL interface configuration](interfaceconfig.md)
+  - [Field descriptors](fieldconfig.md)
     - [`primitive` behavior](primitive.md)
     - [`constant` behavior](constant.md)
     - [`config` behavior](config.md)
@@ -76,5 +76,7 @@ insanely high. If your active logic requires a high clock speed and
     - [`interrupt-status` behavior](interruptstatus.md)
     - [`interrupt-raw` behavior](interruptraw.md)
     - [`custom` behavior](custom.md)
-    - [Access privileges](accessprivileges.md)
-  - [Interrupt descriptors](interruptdescriptor.md)
+    - [Additional address match conditions](conditionconfig.md)
+    - [Subaddress components](subaddressconfig.md)
+    - [Permissions](permissionconfig.md)
+  - [Interrupt descriptors](interruptconfig.md)

mdbook/src/SUMMARY.md

@@ -1,11 +1,11 @@
 # Summary
 
 - [Index](README.md)
-- [Register files](registerfile.md)
-  - [Metadata](metadata.md)
-  - [Register file features](registerfilefeatures.md)
-  - [VHDL interface options](interfaceoptions.md)
-  - [Field descriptors](fielddescriptor.md)
+- [Register files](registerfileconfig.md)
+  - [Metadata](metadataconfig.md)
+  - [Register file options](featureconfig.md)
+  - [VHDL interface configuration](interfaceconfig.md)
+  - [Field descriptors](fieldconfig.md)
     - [`primitive` behavior](primitive.md)
     - [`constant` behavior](constant.md)
     - [`config` behavior](config.md)
@@ -38,5 +38,7 @@
     - [`interrupt-status` behavior](interruptstatus.md)
     - [`interrupt-raw` behavior](interruptraw.md)
     - [`custom` behavior](custom.md)
-    - [Access privileges](accessprivileges.md)
-  - [Interrupt descriptors](interruptdescriptor.md)
+    - [Additional address match conditions](conditionconfig.md)
+    - [Subaddress components](subaddressconfig.md)
+    - [Permissions](permissionconfig.md)
+  - [Interrupt descriptors](interruptconfig.md)

mdbook/src/conditionconfig.md

@@ -0,0 +1,70 @@
+# Additional address match conditions
+
+To support disabling registers at runtime and paged/indirect register
+files, `vhdmmio` allows you to specify additional conditions for the
+address matching logic of each register. This may be useful when not
+enough address space is allocated to the register file to fit all the
+registers, or when you want to emulate legacy register files such as a
+16550 UART.
+
+This structure supports the following configuration keys.
+
+## `internal`
+
+This key specifies the internal signal to use for the match
+condition, if applicable. Either this key or `input` must be
+specified.
+
+The following values are supported:
+
+ - `null` (default): no internal is specified, `input` must be specified instead.
+
+ - a string matching `[a-zA-Za-z][a-zA-Z0-9_]*`: a scalar internal with the given name is used for the match condition.
+
+ - a string matching `[a-zA-Za-z][a-zA-Z0-9_]*:[0-9]+`: a vector internal with the given name and width is used for the match condition.
+
+This key is optional unless required by context. If not specified, the default value (`null`) is used.
+
+## `input`
+
+This key specifies the external input signal to use for the match
+condition, if applicable. Either this key or `internal` must be
+specified.
+
+The following values are supported:
+
+ - `null` (default): no external input is specified, `internal` must be specified instead.
+
+ - a string matching `[a-zA-Za-z][a-zA-Z0-9_]*`: a scalar input signal with the given name is used for the match condition.
+
+ - a string matching `[a-zA-Za-z][a-zA-Z0-9_]*:[0-9]+`: a vector input signal with the given name and width is used for the match condition.
+
+This key is optional unless required by context. If not specified, the default value (`null`) is used.
+
+## `value`
+
+This key specifies the value that the signal must have for the
+logical register to be addressed.
+
+The following values are supported:
+
+ - `no` (default): the signal value needs to be 0.
+
+ - `yes`: the signal value needs to be 1.
+
+ - an integer: the signal value needs to match the specified value.
+
+This key is optional unless required by context. If not specified, the default value (`no`) is used.
+
+## `ignore`
+
+This key specifies the value that the signal must have for the
+logical register to be addressed.
+
+The following values are supported:
+
+ - `0` (default): all bits must match.
+
+ - a different integer: the bits set in this value are ignored when matching against `value`.
+
+This key is optional unless required by context. If not specified, the default value (`0`) is used.

mdbook/src/registerfilefeatures.md → mdbook/src/featureconfig.md

@@ -1,4 +1,4 @@
-# Register file features
+# Register file options
 
 This configuration structure specifies some miscellaneous options that
 affect the functionality and generation of the register file as a whole.
@@ -43,7 +43,7 @@ This key allows you to disable the multi-word register protection
 features normally inferred by `vhdmmio` when any of the fields in the
 register file are sensitive to `aw_prot` or `ar_prot`. This may save
 some area. More information about `vhdmmio`'s security features is
-available [here](accessprivileges.md).
+available [here](permissionconfig.md).
 
 The value must be a boolean (default `no`).