diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/1.Introduction.md | 38 | ||||
| -rw-r--r-- | docs/2.Building.md | 62 | ||||
| -rw-r--r-- | docs/3.Usage.md | 140 | ||||
| -rw-r--r-- | docs/4.4A-Integration.md | 22 | ||||
| -rw-r--r-- | docs/images/arch-4a.png | bin | 0 -> 282311 bytes |
5 files changed, 262 insertions, 0 deletions
diff --git a/docs/1.Introduction.md b/docs/1.Introduction.md new file mode 100644 index 0000000..c36717c --- /dev/null +++ b/docs/1.Introduction.md @@ -0,0 +1,38 @@ +Introduction +=================== + +## Problem + +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 + + - 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 + +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. + +## 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 audio stream, and dynamic configuration of audio streams at the kernel level. + +AVIRT addresses the aforementioned problems by: + +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. + +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. + + + +The following Audio Paths are currently implemented for AVIRT: + +- **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/2.Building.md b/docs/2.Building.md new file mode 100644 index 0000000..5fd9d23 --- /dev/null +++ b/docs/2.Building.md @@ -0,0 +1,62 @@ +Building AVIRT +=================================== + +## Table of Contents + +1. [Introduction](#intro) +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. + +<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 +$ make +``` + +or + +```sh +$ CONFIG_AVIRT=m CONFIG_AVIRT_BUILDLOCAL=y CONFIG_AVIRT_AP_DUMMY=m CONFIG_AVIRT_AP_LOOPBACK=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 +$ ./make_agl.sh ${XDS_SDK_ID} +``` + +<a name="in-tree"/> + +## In tree + +The kernal modules can be built in tree, dependent on the avirt repository being located in drivers/staging - If using your own fork of the linux kernel, you will need to update the staging Makefiles and Kconfigs accordingly. + +To build in tree, use the [Fiberdyne Linux fork](https://github.com/fiberdyne/linux), which will automatically clone the AVIRT Driver and required AudioPath modules to the `drivers/staging` directory. You can then turn AVIRT Support on by setting to `<M>`. The drivers can be found here: + +``` +$ make menuconfig + +# Navigate to: Device Drivers--->Staging Drivers--->AVIRT Support +``` + +Finally build the kernel with the configuration selected by making. + +``` +$ make +``` diff --git a/docs/3.Usage.md b/docs/3.Usage.md new file mode 100644 index 0000000..ba5c3e6 --- /dev/null +++ b/docs/3.Usage.md @@ -0,0 +1,140 @@ +Using AVIRT +=================================== + +## Introduction + +## Table of Contents + +1. [Load/Unload AVIRT](#un-load-avirt) +2. [Configuring AVIRT](#configuring-avirt) +3. [Checking AVIRT](#checking-avirt) + +<a name="un-load-avirt"/> + +## 1. Loading and Unloading AVIRT + +### 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 +insmod snd-avirt-core.ko +insmod dummy/snd-avirt-ap-dummy.ko +insmod loopback/snd-avirt-ap-loopback.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 `scripts/load.sh` script: + +```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 +mkdir -p /lib/modules/$(uname -r)/extra +cp snd-avirt-core.ko snd-avirt-ap-dummy.ko snd-avirt-ap-loopback.ko /lib/modules/$(uname -r)/extra +depmod +``` + +Once the modules are in place, we can load the modules using: + +```sh +modprobe snd-avirt-core +modprobe snd-avirt-ap-dummy +modprobe snd-avirt-ap-loopback +``` + +<a name="configure-avirt" /> + +## 2. Configuring AVIRT + +AVIRT is configured using configfs. + +### 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` filesystem at the conventional point: + +```sh +# Check configfs is mounted on the system +mkdir -p /config +mount -t configfs none /config +``` + +Finally, we can configure AVIRT, for example: + +```sh +# Set up each of the cards channels +mkdir /config/snd-avirt/streams/playback_media +echo "2">/config/snd-avirt/streams/playback_media/channels +echo "ap_dummy">/config/snd-avirt/streams/playback_media/map + +mkdir /config/snd-avirt/streams/playback_navigation +echo "1">/config/snd-avirt/streams/playback_navigation/channels +echo "ap_dummy">/config/snd-avirt/streams/playback_navigation/map + +mkdir /config/snd-avirt/streams/playback_emergency +echo "1">/config/snd-avirt/streams/playback_emergency/channels +echo "ap_dummy">/config/snd-avirt/streams/playback_emergency/map + +mkdir /config/snd-avirt/streams/capture_voice +echo "1">/config/snd-avirt/streams/capture_voice/channels +echo "ap_dummy">/config/snd-avirt/streams/capture_voice/map + +# Finally, seal the card, and initiate configuration +echo "1">/config/snd-avirt/streams/sealed +``` + +Alternatively, the test script at `scripts/test_configfs.sh` can be used. + +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 + +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/4.4A-Integration.md b/docs/4.4A-Integration.md new file mode 100644 index 0000000..cb88dd3 --- /dev/null +++ b/docs/4.4A-Integration.md @@ -0,0 +1,22 @@ +4A Integration +=================== + +AVIRT has been integrated with [4a-softmixer](https://github.com/iotbzh/4a-softmixer) +and [4a-hal-generic](https://github.com/iotbzh/4a-hal-generic) to provide a smooth +transition from the existing aloop implementation to the future AVIRT loopback implementation. + +### User-space Library + +The user-space library [libavirt](https://github.com/fiberdyne/libavirt) can be used to configure AVIRT from within a given AGL 4A binding. + +### Softmixer + +The AVIRT loopback can be used in-place of the standard aloop module. Modifications are currently underway +to port the current 4a-softmixer to the new AVIRT loopback. + +### Hardmixer + +A new 4A mixer controller plugin (`.ctlso`) 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. diff --git a/docs/images/arch-4a.png b/docs/images/arch-4a.png Binary files differnew file mode 100644 index 0000000..6f085db --- /dev/null +++ b/docs/images/arch-4a.png |
