Add docs: Add architecture diagram for 4A

Tidy other docs

Signed-off-by: Mark Farrugia <mark.farrugia@fiberdyne.com.au>

4 files changed, 38 insertions, 18 deletions

diff --git a/README.md b/README.md
index 9c70cfb..a653f0e 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-## Alsa Virtual Sound Driver
+# Alsa Virtual Sound Driver
 
 1. [Introduction](docs/1.Introduction.md)
 2. [Building](docs/2.Building.md)
diff --git a/docs/1.Introduction.md b/docs/1.Introduction.md
index e189c7c..c36717c 100644
--- a/docs/1.Introduction.md
+++ b/docs/1.Introduction.md
@@ -3,7 +3,7 @@ Introduction
 
 ## Problem
 
-The existing solution contains the following drawbacks:
+The existing audio solution in [AGL](https://www.automotivelinux.org/) (Automotive Grade Linux) utilizes the ALSA loopback module together with [4a-softmixer](https://github.com/iotbzh/4a-softmixer). There are drawbacks to this solution:
 
 1. Non-generic interface for configurable hardware cases
 
@@ -17,20 +17,22 @@ The existing solution contains the following drawbacks:
 
    - Substreams cannot have SMACK labels applied, inherently leaving different audio streams insecure, or a single label applied to all.
 
-## AVIRTs Solution
+## The AVIRT Solution
 
-The ALSA Virtual Sound Driver (AVIRT) aims to provide a Linux kernel solution to the issue of audio routing in kernel-space, as well as security per-stream, and dynamic configuration of streams at the kernel level.
+The ALSA Virtual Sound Driver (AVIRT) aims to provide a Linux kernel solution to the issue of audio routing in kernel-space, as well as security per audio stream, and dynamic configuration of audio streams at the kernel level.
 
-A top-level abstract dynamic audio driver is presented to the user-space via an ALSA middle-layer card. From there, respective low-level "real" audio drivers can subscribe to it as an "Audio Path".
+AVIRT addresses the aforementioned problems by:
 
-The top-level driver is configured (currently) using by utilising configfs.
+1. Providing a standard user-space interface via `configfs` to configure a variable number of 'streams' which can be mapped to audio paths.
+2. Optimize the audio routing by connecting directly with the desired audio path. This can include routing audio through directly to hardware, to an implemented loopback interface, or to a DSP.
+3. Each 'stream' is separated to its own ALSA PCM device, therefore differing security attributes can be applied to each 'stream'. This means that each of the audio roles can have separate security contexts from one another.
 
-AVIRT attempts to address the aforementioned problems by:
+A top-level abstract dynamic audio driver is presented to the user-space via an ALSA middle-layer card. The card's PCM devices are configured using `configfs` via the accompanying userspace library [libavirt](https://github.com/fiberdyne/libavirt). The low-level "real" audio drivers can subscribe to the top-level as an "Audio Path". The Audio Path accepts routed audio streams from the abstracted top-level, and is then able to direct the audio streams accordingly.
 
-1. Providing a standard interface through configfs to configure a variable number of 'streams' which can be mapped to audio paths.
-2. Optimize the audio routing by connecting directly with the desired audio path. This can include routing audio through directly to hardware, or to an implemented loopback interface.
-3. Each 'stream' is separated to its own device, therefore security can be applied to each 'stream'. This means that each of the audio roles can be separately secured from each other.
+![alt text](images/arch-4a.png "AVIRT Architecture")
 
-A sample dummy Audio Path is provided as an example to show how a low-level audio driver would subscribe to AVIRT, and accept audio routing for playback.
+The following Audio Paths are currently implemented for AVIRT:
 
-Currently, the Fiberdyne DSP hardmixer is supported on the Renesas R-Car M3 AGL reference platform, and the default loopback softmixer can be used to emulate this in cases where the former is not available.
+- **ap_dummy** - This is provided as an example to show how a low-level audio driver would subscribe to AVIRT, and accept audio routing for playback.
+- **ap_fddsp** - This is the Fiberdyne DSP hardmixer. This is only supported on the Renesas R-Car M3 AGL reference platform, and utilizes the HiFi2 DSP core to provide advanced DSP and audio mixing. An accompanying UI can be used to control the DSP parameters.
+- **ap_loopback** - This is the default loopback for use with the softmixer. This is the stock AGL solution to be used to emulate the hardmixer when not available.
diff --git a/docs/3.Usage.md b/docs/3.Usage.md
index df56cf1..d65d50d 100644
--- a/docs/3.Usage.md
+++ b/docs/3.Usage.md
@@ -75,13 +75,13 @@ First, verify the kernel supports the use of configfs.
 fgrep configfs /proc/filesystems
 ```
 
-the expected output is:
+The expected output is:
 
 ```
 nodev	configfs
 ```
 
-Once confirmed, we can mount the configfs at the conventional point:
+Once confirmed, we can mount the `configfs` filesystem at the conventional point:
 
 ```sh
 # Check configfs is mounted on the system
@@ -89,7 +89,7 @@ mkdir -p /config
 mount -t configfs none /config
 ```
 
-Finally, we can configure AVIRT:
+Finally, we can configure AVIRT, for example:
 
 ```sh
 # Set up each of the cards channels
@@ -115,7 +115,25 @@ echo "1">/config/avirt/streams/sealed
 
 Alternatively, the test script at `scripts/test_configfs.sh` can be used.
 
-### Note:
+The user-space library, [libavirt](https://github.com/fiberdyne/libavirt) can be used to interact with the configfs interface. Please refer to the README in libavirt for further details.
+
+<a name="checking-avirt" />
+
+## 3. Checking AVIRT Loaded Correctly
 
-A simplified helper library, libavirt, is available [here](https://github.com/fiberdyne/libavirt).
-Please refer to the readme in libavirt for further details.
+We can see the newly created streams by using the `aplay` utility. For example, the device list might look a little like this:
+
+```sh
+aplay -l
+...
+card 2: avirt [avirt], device 0: multimedia [multimedia]
+  Subdevices: 1/1
+  Subdevice #0: subdevice #0
+card 2: avirt [avirt], device 1: navigation [navigation]
+  Subdevices: 1/1
+  Subdevice #0: subdevice #0
+card 2: avirt [avirt], device 2: emergency [emergency]
+  Subdevices: 1/1
+  Subdevice #0: subdevice #0
+...
+```
diff --git a/docs/images/arch-4a.png b/docs/images/arch-4a.png
new file mode 100644
index 0000000..6f085db
--- /dev/null
+++ b/docs/images/arch-4a.png