aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorMark Farrugia <mark.farrugia@fiberdyne.com.au>2018-10-08 16:47:25 +1100
committerMark Farrugia <mark.farrugia@fiberdyne.com.au>2018-10-26 17:27:46 +1100
commit3b62055c816764ff02aeb3a548e9bba36df8aae4 (patch)
tree172a0cf6fab98068182730479389546501ceff1b /docs
parent07505fddec4f96f187ec79a55f4363a68f083a03 (diff)
Update documentation
Add 'map' to configfs test, remove old mentions of module parameters Signed-off-by: Mark Farrugia <mark.farrugia@fiberdyne.com.au>
Diffstat (limited to 'docs')
-rw-r--r--docs/1.Introduction.md17
-rw-r--r--docs/2.Building.md12
-rw-r--r--docs/3.Usage.md53
-rw-r--r--docs/4.4A-Integration.md4
4 files changed, 70 insertions, 16 deletions
diff --git a/docs/1.Introduction.md b/docs/1.Introduction.md
index 7bf3ebe..2ddaf57 100644
--- a/docs/1.Introduction.md
+++ b/docs/1.Introduction.md
@@ -2,15 +2,23 @@ Introduction
===================
## Problem
+
The existing solution contains the following drawbacks:
+
1. Non-generic interface for configurable hardware cases
- - Unable to configure streams mapped to outputs
+
+ - Unable to configure streams mapped to outputs
+
2. Not fully optimized for certain use cases (ie. Routing Audio to DSP vs. aloop)
- - Routing audio to hardware to reduce overhead
+
+ - Routing audio to hardware to reduce overhead
+
3. Inability to secure on all audio streams
- - Substreams cannot have SMACK labels applied, inherently leaving different audio streams insecure, or a single label applied to all.
+
+ - Substreams cannot have SMACK labels applied, inherently leaving different audio streams insecure, or a single label applied to all.
## AVIRTs 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.
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".
@@ -18,10 +26,11 @@ A top-level abstract dynamic audio driver is presented to the user-space via an
The top-level driver is configured (currently) using by utilising configfs.
AVIRT attempts to address the aforementioned problems by:
+
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.
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.
-Currently, the Fiberdyne DSP hardmixer is supported on the Renesas R-Car M3 AGL reference platform, and a default loopback softmixer is in development. \ No newline at end of file
+Currently, the Fiberdyne DSP hardmixer is supported on the Renesas R-Car M3 AGL reference platform, and a default loopback softmixer is in development.
diff --git a/docs/2.Building.md b/docs/2.Building.md
index 237d834..3e42746 100644
--- a/docs/2.Building.md
+++ b/docs/2.Building.md
@@ -2,21 +2,23 @@ Building AVIRT
===================================
## Table of Contents
+
1. [Introduction](#intro)
-2. [Out of Tree](#out-of-tree)
+2. [Out of Tree](#out-of-tree)
3. [In Tree](#in-tree)
<a name="intro"/>
## Introduction
-The AVIRT module and submodules can be built using a variety of methods. There are Visual Code build tasks for in and out of tree builds, make file support for CLI building (both in and out of tree), and xds build support.
+The AVIRT module and submodules can be built using a variety of methods. There are Visual Code build tasks for in and out of tree builds, make file support for CLI building (both in and out of tree), and xds build support.
<a name="out-of-tree"/>
## Out Of Tree
### Building with CLI
+
To build both AVIRT and the additional Audio Paths out-of-tree, use the following command:
```sh
@@ -24,12 +26,15 @@ $ make
```
or
+
```sh
$ CONFIG_AVIRT=m CONFIG_AVIRT_BUILDLOCAL=y CONFIG_AVIRT_DUMMYAP=m make -C /lib/modules/$(uname -r)/build/ M=$(pwd)
```
+
The latter is executed internally with the make file.
### Building with XDS SDK
+
To build both AVIRT and the dummy Audio Path out-of-tree for [AGL](http://docs.automotivelinux.org/) (`aarch64` currently supported), use the [XDS](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/xds/part-1/0_Abstract.html) build system together with the `make_agl.sh` script:
```sh
@@ -51,6 +56,7 @@ $ make menuconfig
```
Finally build the kernel with the configuration selected by making.
+
```
$ make
-``` \ No newline at end of file
+```
diff --git a/docs/3.Usage.md b/docs/3.Usage.md
index 7eb46d3..6d4d9f1 100644
--- a/docs/3.Usage.md
+++ b/docs/3.Usage.md
@@ -4,6 +4,7 @@ Using AVIRT
## Introduction
## Table of Contents
+
1. [Load/Unload AVIRT](#un-load-avirt)
2. [Configuring AVIRT](#configuring-avirt)
@@ -11,7 +12,9 @@ Using AVIRT
## Loading and Unloading AVIRT
-As root, load the required ```avirt_core.ko``` and subsequent audio path.
+### Load Out of Tree
+
+As root, load the required `avirt_core.ko` and subsequent audio path.
As an example, the Dummy Audiopath is being loaded here.
```sh
@@ -20,14 +23,38 @@ insmod dummy/dummy_audiopath.ko
```
### Note:
+
The loading and unloading of drivers can be performed using the helper scripts.
-To run, we must load the kernel modules using the `loadDrivers.sh` script, which contains sample module parameters to AVIRT:
+To run, we must load the kernel modules using the `scripts/load.sh` script:
+
```sh
-$ ./loadDrivers.sh
+$ ./scripts/load.sh
```
+
To unload the drivers use:
+
+```sh
+$ ./scripts/unload.sh
+```
+
+### Load In Tree
+
+#### Note:
+
+Either build the module in tree, or you can copy the modules manually and then run `depmod` to generate dependencies.
+For example, in AGL:
+
```sh
-$ ./unload.sh
+mkdir -p /lib/modules/$(uname -r)/extra
+cp avirt_core.ko avirt_dummyap.ko /lib/modules/$(uname -r)/extra
+depmod
+```
+
+Once the modules are in place, we can load the modules using:
+
+```sh
+modprobe avirt_core
+modprobe avirt_dummyap
```
<a name="configure-avirt" />
@@ -35,22 +62,27 @@ $ ./unload.sh
## Configuring AVIRT
AVIRT is configured using configfs.
-### Note:
-A sample script for the following is supplied inside the ```scripts``` folder.
+
+### Note:
+
+A sample script for the following is supplied inside the `scripts` folder.
First, verify the kernel supports the use of configfs.
+
```sh
fgrep configfs /proc/filesystems
```
the expected output is:
+
```
nodev configfs
```
Once confirmed, we can mount the configfs at the conventional point:
+
```sh
-#Check configfs is mounted on the system
+# Check configfs is mounted on the system
mkdir -p /config
mount -t configfs none /config
```
@@ -61,20 +93,27 @@ Finally, we can configure AVIRT:
# Set up each of the cards channels
mkdir /config/avirt/streams/playback_media
echo "2">/config/avirt/streams/playback_media/channels
+echo "ap_dummy">/config/avirt/streams/playback_media/map
mkdir /config/avirt/streams/playback_navigation
echo "1">/config/avirt/streams/playback_navigation/channels
+echo "ap_dummy">/config/avirt/streams/playback_navigation/map
mkdir /config/avirt/streams/playback_emergency
echo "1">/config/avirt/streams/playback_emergency/channels
+echo "ap_dummy">/config/avirt/streams/playback_emergency/map
mkdir /config/avirt/streams/capture_voice
echo "1">/config/avirt/streams/capture_voice/channels
+echo "ap_dummy">/config/avirt/streams/capture_voice/map
# Finally, seal the card, and initiate configuration
echo "1">/config/avirt/streams/sealed
```
+Alternatively, the test script at `scripts/test_configfs.sh` can be used.
+
### Note:
+
A simplified helper library, libavirt, is available [here](https://github.com/fiberdyne/libavirt).
Please refer to the readme in libavirt for further details.
diff --git a/docs/4.4A-Integration.md b/docs/4.4A-Integration.md
index 7c9b980..da4eeb7 100644
--- a/docs/4.4A-Integration.md
+++ b/docs/4.4A-Integration.md
@@ -13,5 +13,5 @@ The user-space library [libavirt](https://github.com/fiberdyne/libavirt) can be
A new 4A mixer binding has been developed to demonstrate the capabilities of the
Fiberdyne DSP mixer operating on the HiFi2 core on-board the Renesas R-Car M3 M3ULCB
-AGL reference platform. This is called the 'hardmixer', and is a faster, lower
-latency alternative to the softmixer. \ No newline at end of file
+AGL reference platform. This is called the '**hardmixer**', and is a faster, lower
+latency alternative to the softmixer.