From 386c29da3416d86b66430e590aaa5c51f2942477 Mon Sep 17 00:00:00 2001 From: James O'Shannessy Date: Thu, 13 Sep 2018 16:13:48 -0700 Subject: Add docs folder for in depth breakdown of module. After discussion at AGL F2F, it was suggested to have simpler readmes that summarise the system/architecture/build process/etc. Starting to dotpoint out that process with these readmes. Signed-off-by: James O'Shannessy --- docs/1. Introduction.md | 0 docs/2. Building.md | 0 docs/3. Usage.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/1. Introduction.md create mode 100644 docs/2. Building.md create mode 100644 docs/3. Usage.md (limited to 'docs') diff --git a/docs/1. Introduction.md b/docs/1. Introduction.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/2. Building.md b/docs/2. Building.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/3. Usage.md b/docs/3. Usage.md new file mode 100644 index 0000000..e69de29 -- cgit From 5a2a915287e7cd12a347a03d37861310701a72fb Mon Sep 17 00:00:00 2001 From: James O'Shannessy Date: Thu, 13 Sep 2018 16:34:25 -0700 Subject: Changes to readme files Dot points to introduction, and shifting the build instructions to docs/2.\ Building.md Signed-off-by: James O'Shannessy --- docs/1. Introduction.md | 18 ++++++++++++++++++ docs/2. Building.md | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) (limited to 'docs') diff --git a/docs/1. Introduction.md b/docs/1. Introduction.md index e69de29..f2d088d 100644 --- a/docs/1. Introduction.md +++ b/docs/1. Introduction.md @@ -0,0 +1,18 @@ +Introduction +=================== + +## Problem +- Insecure +- Limited +- Not fully optimised for use case (ie. Routing Audio to DSP vs. Loopback) +- Not generic interface for highly configurable hardware +- + +## Solution + +## Added Features +- Dynamic Runtime Alsa Front end +- Adjustable Audio Path +- Mappable Audio Path +- Secure Audio Routing w/ SMACK +- \ No newline at end of file diff --git a/docs/2. Building.md b/docs/2. Building.md index e69de29..983db8d 100644 --- a/docs/2. Building.md +++ b/docs/2. Building.md @@ -0,0 +1,39 @@ +Building AVIRT +=================================== + +## Table of Contents +1. [Out of Tree](#out-of-tree) +2. [In Tree](#in-tree) + + + +## Out Of Tree + +The kernel modules can be built either in-tree, or out-of-tree. +To build both AVIRT and the dummy Audio Path out-of-tree, use the following command: + +```sh +$ CONFIG_AVIRT=m CONFIG_AVIRT_BUILDLOCAL=y CONFIG_AVIRT_DUMMYAP=m make -C /lib/modules/$(uname -r)/build/ M=$(pwd) +``` + +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} +``` + + + +## In tree + + +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 ``. 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 +``` \ No newline at end of file -- cgit From 72499de21381625577160fac2e1e31af0d1f104d Mon Sep 17 00:00:00 2001 From: James O'Shannessy Date: Thu, 13 Sep 2018 17:20:37 -0700 Subject: Updating build instructions Cleaning up build instructions for building AVIRT Signed-off-by: James O'Shannessy --- docs/2. Building.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/2. Building.md b/docs/2. Building.md index 983db8d..0016822 100644 --- a/docs/2. Building.md +++ b/docs/2. Building.md @@ -2,20 +2,34 @@ Building AVIRT =================================== ## Table of Contents -1. [Out of Tree](#out-of-tree) -2. [In Tree](#in-tree) +1. [Introduction](#intro) +2. [Out of Tree](#out-of-tree) +3. [In Tree](#in-tree) + + + +## 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. + ## Out Of Tree -The kernel modules can be built either in-tree, or out-of-tree. -To build both AVIRT and the dummy Audio Path out-of-tree, use the following command: +### 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_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 @@ -26,6 +40,7 @@ $ ./make_agl.sh ${XDS_SDK_ID} ## 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 ``. The drivers can be found here: ``` @@ -33,6 +48,7 @@ $ make menuconfig # Navigate to: Device Drivers--->Staging Drivers--->AVIRT Support ``` + Finally build the kernel with the configuration selected by making. ``` $ make -- cgit From 819bbaa22430988a88999e283ceb02368ad0f7b3 Mon Sep 17 00:00:00 2001 From: James O'Shannessy Date: Mon, 8 Oct 2018 12:22:32 +1100 Subject: Committing usage document Updated usage document with loading/unloading, configuration information Signed-off-by: James O'Shannessy --- docs/3. Usage.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) (limited to 'docs') diff --git a/docs/3. Usage.md b/docs/3. Usage.md index e69de29..b5ec136 100644 --- a/docs/3. Usage.md +++ b/docs/3. Usage.md @@ -0,0 +1,70 @@ +Using AVIRT +=================================== + +## Introduction + +## Table of Contents +1. [Load/Unload AVIRT](#un-load-avirt) +2. [Configuring AVIRT](#configuring-avirt) + + + +## Loading and Unloading AVIRT + +To run, we must load the kernel modules using the `loadDrivers.sh` script, which contains sample module parameters to AVIRT: +```sh +$ ./loadDrivers.sh +``` +To unload the drivers use: +```sh +$ ./unload.sh +``` + + + +## 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 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: + +```sh +# Set up each of the cards channels +mkdir /config/avirt/streams/playback_media +echo "2">/config/avirt/streams/playback_media/channels + +mkdir /config/avirt/streams/playback_navigation +echo "1">/config/avirt/streams/playback_navigation/channels + +mkdir /config/avirt/streams/playback_emergency +echo "1">/config/avirt/streams/playback_emergency/channels + +mkdir /config/avirt/streams/capture_voice +echo "1">/config/avirt/streams/capture_voice/channels + +# Finally, seal the card, and initiate configuration +echo "1">/config/avirt/streams/sealed +``` + +### Note: +A simplified helper library, libavirt, is available [here](https://github.com/fiberdyne/libavirt). +Please refer to the readme in libavirt for further details. -- cgit From a3e9a9eb2b927ef05161f1c2bf5feb62db84c5b3 Mon Sep 17 00:00:00 2001 From: James O'Shannessy Date: Mon, 8 Oct 2018 12:26:39 +1100 Subject: Added load/unload documentation. Updated documentation to use load/unload Signed-off-by: James O'Shannessy --- docs/3. Usage.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/3. Usage.md b/docs/3. Usage.md index b5ec136..7eb46d3 100644 --- a/docs/3. Usage.md +++ b/docs/3. Usage.md @@ -11,6 +11,16 @@ Using AVIRT ## Loading and Unloading AVIRT +As root, load the required ```avirt_core.ko``` and subsequent audio path. +As an example, the Dummy Audiopath is being loaded here. + +```sh +insmod avirt_core.ko +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: ```sh $ ./loadDrivers.sh -- cgit From 83ab0cdf84def71eebdebf0c813cebfce8f99d06 Mon Sep 17 00:00:00 2001 From: James O'Shannessy Date: Thu, 13 Sep 2018 16:34:25 -0700 Subject: Changes to readme files Dot points to introduction, and shifting the build instructions to docs/2.\ Building.md Signed-off-by: James O'Shannessy --- docs/2. Building.md | 24 ++++-------------------- 1 file changed, 4 insertions(+), 20 deletions(-) (limited to 'docs') diff --git a/docs/2. Building.md b/docs/2. Building.md index 0016822..983db8d 100644 --- a/docs/2. Building.md +++ b/docs/2. Building.md @@ -2,34 +2,20 @@ Building AVIRT =================================== ## Table of Contents -1. [Introduction](#intro) -2. [Out of Tree](#out-of-tree) -3. [In Tree](#in-tree) - - - -## 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. - +1. [Out of Tree](#out-of-tree) +2. [In Tree](#in-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 -``` +The kernel modules can be built either in-tree, or out-of-tree. +To build both AVIRT and the dummy Audio Path out-of-tree, use the following command: -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 @@ -40,7 +26,6 @@ $ ./make_agl.sh ${XDS_SDK_ID} ## 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 ``. The drivers can be found here: ``` @@ -48,7 +33,6 @@ $ make menuconfig # Navigate to: Device Drivers--->Staging Drivers--->AVIRT Support ``` - Finally build the kernel with the configuration selected by making. ``` $ make -- cgit From 7e4db2ff6865d723a2a6233a9542730876d06260 Mon Sep 17 00:00:00 2001 From: James O'Shannessy Date: Thu, 13 Sep 2018 17:20:37 -0700 Subject: Updating build instructions Cleaning up build instructions for building AVIRT Signed-off-by: James O'Shannessy --- docs/1. Introduction.md | 21 ++++++++------------- docs/2. Building.md | 24 ++++++++++++++++++++---- docs/4. 4A Integration | 17 +++++++++++++++++ 3 files changed, 45 insertions(+), 17 deletions(-) create mode 100644 docs/4. 4A Integration (limited to 'docs') diff --git a/docs/1. Introduction.md b/docs/1. Introduction.md index f2d088d..29cac71 100644 --- a/docs/1. Introduction.md +++ b/docs/1. Introduction.md @@ -1,18 +1,13 @@ Introduction =================== -## Problem -- Insecure -- Limited -- Not fully optimised for use case (ie. Routing Audio to DSP vs. Loopback) -- Not generic interface for highly configurable hardware -- +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. -## Solution +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". -## Added Features -- Dynamic Runtime Alsa Front end -- Adjustable Audio Path -- Mappable Audio Path -- Secure Audio Routing w/ SMACK -- \ No newline at end of file +The top-level driver is configured (currently) using module parameters, as is the norm for sound drivers in the Linux tree, however this will utilise a configfs configuration implementation in future. + +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 diff --git a/docs/2. Building.md b/docs/2. Building.md index 983db8d..0016822 100644 --- a/docs/2. Building.md +++ b/docs/2. Building.md @@ -2,20 +2,34 @@ Building AVIRT =================================== ## Table of Contents -1. [Out of Tree](#out-of-tree) -2. [In Tree](#in-tree) +1. [Introduction](#intro) +2. [Out of Tree](#out-of-tree) +3. [In Tree](#in-tree) + + + +## 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. + ## Out Of Tree -The kernel modules can be built either in-tree, or out-of-tree. -To build both AVIRT and the dummy Audio Path out-of-tree, use the following command: +### 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_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 @@ -26,6 +40,7 @@ $ ./make_agl.sh ${XDS_SDK_ID} ## 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 ``. The drivers can be found here: ``` @@ -33,6 +48,7 @@ $ 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/4. 4A Integration b/docs/4. 4A Integration new file mode 100644 index 0000000..7c9b980 --- /dev/null +++ b/docs/4. 4A Integration @@ -0,0 +1,17 @@ +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. + +### Hardmixer + +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 -- cgit From 056c3754bc7be349de1a41ac6d4819f3d032bd0c Mon Sep 17 00:00:00 2001 From: James O'Shannessy Date: Mon, 8 Oct 2018 15:19:34 +1100 Subject: Fixing table of contents in README documentation Restructure docs file tree Signed-off-by: James O'Shannessy --- docs/1. Introduction.md | 13 -------- docs/1.Introduction.md | 13 ++++++++ docs/2. Building.md | 55 --------------------------------- docs/2.Building.md | 56 +++++++++++++++++++++++++++++++++ docs/3. Usage.md | 80 ------------------------------------------------ docs/3.Usage.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/4. 4A Integration | 17 ---------- docs/4.4A-Integration.md | 17 ++++++++++ 8 files changed, 166 insertions(+), 165 deletions(-) delete mode 100644 docs/1. Introduction.md create mode 100644 docs/1.Introduction.md delete mode 100644 docs/2. Building.md create mode 100644 docs/2.Building.md delete mode 100644 docs/3. Usage.md create mode 100644 docs/3.Usage.md delete mode 100644 docs/4. 4A Integration create mode 100644 docs/4.4A-Integration.md (limited to 'docs') diff --git a/docs/1. Introduction.md b/docs/1. Introduction.md deleted file mode 100644 index 29cac71..0000000 --- a/docs/1. Introduction.md +++ /dev/null @@ -1,13 +0,0 @@ -Introduction -=================== - -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". - -The top-level driver is configured (currently) using module parameters, as is the norm for sound drivers in the Linux tree, however this will utilise a configfs configuration implementation in future. - -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 diff --git a/docs/1.Introduction.md b/docs/1.Introduction.md new file mode 100644 index 0000000..29cac71 --- /dev/null +++ b/docs/1.Introduction.md @@ -0,0 +1,13 @@ +Introduction +=================== + +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". + +The top-level driver is configured (currently) using module parameters, as is the norm for sound drivers in the Linux tree, however this will utilise a configfs configuration implementation in future. + +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 diff --git a/docs/2. Building.md b/docs/2. Building.md deleted file mode 100644 index 0016822..0000000 --- a/docs/2. Building.md +++ /dev/null @@ -1,55 +0,0 @@ -Building AVIRT -=================================== - -## Table of Contents -1. [Introduction](#intro) -2. [Out of Tree](#out-of-tree) -3. [In Tree](#in-tree) - - - -## 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. - - - - -## 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_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 -$ ./make_agl.sh ${XDS_SDK_ID} -``` - - - -## 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 ``. 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 -``` \ No newline at end of file diff --git a/docs/2.Building.md b/docs/2.Building.md new file mode 100644 index 0000000..237d834 --- /dev/null +++ b/docs/2.Building.md @@ -0,0 +1,56 @@ +Building AVIRT +=================================== + +## Table of Contents +1. [Introduction](#intro) +2. [Out of Tree](#out-of-tree) +3. [In Tree](#in-tree) + + + +## 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. + + + + +## 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_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 +$ ./make_agl.sh ${XDS_SDK_ID} +``` + + + +## 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 ``. 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 +``` \ No newline at end of file diff --git a/docs/3. Usage.md b/docs/3. Usage.md deleted file mode 100644 index 7eb46d3..0000000 --- a/docs/3. Usage.md +++ /dev/null @@ -1,80 +0,0 @@ -Using AVIRT -=================================== - -## Introduction - -## Table of Contents -1. [Load/Unload AVIRT](#un-load-avirt) -2. [Configuring AVIRT](#configuring-avirt) - - - -## Loading and Unloading AVIRT - -As root, load the required ```avirt_core.ko``` and subsequent audio path. -As an example, the Dummy Audiopath is being loaded here. - -```sh -insmod avirt_core.ko -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: -```sh -$ ./loadDrivers.sh -``` -To unload the drivers use: -```sh -$ ./unload.sh -``` - - - -## 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 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: - -```sh -# Set up each of the cards channels -mkdir /config/avirt/streams/playback_media -echo "2">/config/avirt/streams/playback_media/channels - -mkdir /config/avirt/streams/playback_navigation -echo "1">/config/avirt/streams/playback_navigation/channels - -mkdir /config/avirt/streams/playback_emergency -echo "1">/config/avirt/streams/playback_emergency/channels - -mkdir /config/avirt/streams/capture_voice -echo "1">/config/avirt/streams/capture_voice/channels - -# Finally, seal the card, and initiate configuration -echo "1">/config/avirt/streams/sealed -``` - -### 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/3.Usage.md b/docs/3.Usage.md new file mode 100644 index 0000000..7eb46d3 --- /dev/null +++ b/docs/3.Usage.md @@ -0,0 +1,80 @@ +Using AVIRT +=================================== + +## Introduction + +## Table of Contents +1. [Load/Unload AVIRT](#un-load-avirt) +2. [Configuring AVIRT](#configuring-avirt) + + + +## Loading and Unloading AVIRT + +As root, load the required ```avirt_core.ko``` and subsequent audio path. +As an example, the Dummy Audiopath is being loaded here. + +```sh +insmod avirt_core.ko +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: +```sh +$ ./loadDrivers.sh +``` +To unload the drivers use: +```sh +$ ./unload.sh +``` + + + +## 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 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: + +```sh +# Set up each of the cards channels +mkdir /config/avirt/streams/playback_media +echo "2">/config/avirt/streams/playback_media/channels + +mkdir /config/avirt/streams/playback_navigation +echo "1">/config/avirt/streams/playback_navigation/channels + +mkdir /config/avirt/streams/playback_emergency +echo "1">/config/avirt/streams/playback_emergency/channels + +mkdir /config/avirt/streams/capture_voice +echo "1">/config/avirt/streams/capture_voice/channels + +# Finally, seal the card, and initiate configuration +echo "1">/config/avirt/streams/sealed +``` + +### 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 b/docs/4. 4A Integration deleted file mode 100644 index 7c9b980..0000000 --- a/docs/4. 4A Integration +++ /dev/null @@ -1,17 +0,0 @@ -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. - -### Hardmixer - -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 diff --git a/docs/4.4A-Integration.md b/docs/4.4A-Integration.md new file mode 100644 index 0000000..7c9b980 --- /dev/null +++ b/docs/4.4A-Integration.md @@ -0,0 +1,17 @@ +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. + +### Hardmixer + +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 -- cgit From 94eb09750343f0adc8f4bf56eb4ee05ce9def8f1 Mon Sep 17 00:00:00 2001 From: James O'Shannessy Date: Mon, 8 Oct 2018 16:03:12 +1100 Subject: Updating Introduction doc Signed-off-by: James O'Shannessy --- docs/1.Introduction.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/1.Introduction.md b/docs/1.Introduction.md index 29cac71..25b3ea8 100644 --- a/docs/1.Introduction.md +++ b/docs/1.Introduction.md @@ -1,13 +1,27 @@ Introduction =================== +## Problem +The existing solution contains the following drawbacks: + 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. + +## 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". -The top-level driver is configured (currently) using module parameters, as is the norm for sound drivers in the Linux tree, however this will utilise a configfs configuration implementation in future. +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. \ No newline at end of file -- cgit From c6c2c324c13fec5a3e1d52059454e4d8b17b1e28 Mon Sep 17 00:00:00 2001 From: James O'Shannessy Date: Mon, 8 Oct 2018 15:20:38 +1100 Subject: Update README.md Fix table of contents Markdown links Fixing whitespace problems in Markdown docs Fix alignment of table of contents Signed-off-by: James O'Shannessy --- docs/1.Introduction.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/1.Introduction.md b/docs/1.Introduction.md index 25b3ea8..7bf3ebe 100644 --- a/docs/1.Introduction.md +++ b/docs/1.Introduction.md @@ -3,12 +3,12 @@ Introduction ## Problem The existing solution contains the following drawbacks: - 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. +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. ## 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. @@ -18,9 +18,9 @@ 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. +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. -- cgit From 3b62055c816764ff02aeb3a548e9bba36df8aae4 Mon Sep 17 00:00:00 2001 From: Mark Farrugia Date: Mon, 8 Oct 2018 16:47:25 +1100 Subject: Update documentation Add 'map' to configfs test, remove old mentions of module parameters Signed-off-by: Mark Farrugia --- docs/1.Introduction.md | 17 ++++++++++++---- docs/2.Building.md | 12 ++++++++--- docs/3.Usage.md | 53 +++++++++++++++++++++++++++++++++++++++++------- docs/4.4A-Integration.md | 4 ++-- 4 files changed, 70 insertions(+), 16 deletions(-) (limited to 'docs') 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) ## 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. ## 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 ``` @@ -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. -- cgit From cd128853f392960ceec44476f37f0d569a680db5 Mon Sep 17 00:00:00 2001 From: Mark Farrugia Date: Mon, 8 Oct 2018 17:59:15 +1100 Subject: Update docs to include loopback Signed-off-by: Mark Farrugia --- docs/1.Introduction.md | 2 +- docs/3.Usage.md | 6 ++++-- docs/4.4A-Integration.md | 7 ++++++- 3 files changed, 11 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/1.Introduction.md b/docs/1.Introduction.md index 2ddaf57..e189c7c 100644 --- a/docs/1.Introduction.md +++ b/docs/1.Introduction.md @@ -33,4 +33,4 @@ AVIRT attempts to address the aforementioned problems by: 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. +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. diff --git a/docs/3.Usage.md b/docs/3.Usage.md index 6d4d9f1..df56cf1 100644 --- a/docs/3.Usage.md +++ b/docs/3.Usage.md @@ -19,7 +19,8 @@ As an example, the Dummy Audiopath is being loaded here. ```sh insmod avirt_core.ko -insmod dummy/dummy_audiopath.ko +insmod dummy/avirt_dummyap.ko +insmod loopback/avirt_loopbackap.ko ``` ### Note: @@ -46,7 +47,7 @@ For example, in AGL: ```sh mkdir -p /lib/modules/$(uname -r)/extra -cp avirt_core.ko avirt_dummyap.ko /lib/modules/$(uname -r)/extra +cp avirt_core.ko avirt_dummyap.ko avirt_loopbackap.ko /lib/modules/$(uname -r)/extra depmod ``` @@ -55,6 +56,7 @@ Once the modules are in place, we can load the modules using: ```sh modprobe avirt_core modprobe avirt_dummyap +modprobe avirt_loopbackap ``` diff --git a/docs/4.4A-Integration.md b/docs/4.4A-Integration.md index da4eeb7..cb88dd3 100644 --- a/docs/4.4A-Integration.md +++ b/docs/4.4A-Integration.md @@ -9,9 +9,14 @@ transition from the existing aloop implementation to the future AVIRT loopback i 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 binding has been developed to demonstrate the capabilities of the +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. -- cgit From 964987727646a7139a3d259830f25a739937fa73 Mon Sep 17 00:00:00 2001 From: Mark Farrugia Date: Tue, 9 Oct 2018 10:10:49 +1100 Subject: Add docs: Add architecture diagram for 4A Tidy other docs Signed-off-by: Mark Farrugia --- docs/1.Introduction.md | 24 +++++++++++++----------- docs/3.Usage.md | 30 ++++++++++++++++++++++++------ docs/images/arch-4a.png | Bin 0 -> 282311 bytes 3 files changed, 37 insertions(+), 17 deletions(-) create mode 100644 docs/images/arch-4a.png (limited to 'docs') 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. + + + +## 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 Binary files /dev/null and b/docs/images/arch-4a.png differ -- cgit From d66dbf0820e9e7e14a6f723c1ce92b7ac4e0280d Mon Sep 17 00:00:00 2001 From: Mark Farrugia Date: Thu, 25 Oct 2018 17:37:07 +1100 Subject: Refactor all avirt_ symbols to have have snd prefix, as per Linux sound This will aid the eventual migration the the upstream mainline Linux kernel Fix some checkpatch warnings, and other compiler warnings Signed-off-by: Mark Farrugia --- docs/2.Building.md | 2 +- docs/3.Usage.md | 40 ++++++++++++++++++++-------------------- 2 files changed, 21 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/2.Building.md b/docs/2.Building.md index 3e42746..5fd9d23 100644 --- a/docs/2.Building.md +++ b/docs/2.Building.md @@ -28,7 +28,7 @@ $ make or ```sh -$ CONFIG_AVIRT=m CONFIG_AVIRT_BUILDLOCAL=y CONFIG_AVIRT_DUMMYAP=m make -C /lib/modules/$(uname -r)/build/ M=$(pwd) +$ 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. diff --git a/docs/3.Usage.md b/docs/3.Usage.md index d65d50d..f535a07 100644 --- a/docs/3.Usage.md +++ b/docs/3.Usage.md @@ -18,9 +18,9 @@ As root, load the required `avirt_core.ko` and subsequent audio path. As an example, the Dummy Audiopath is being loaded here. ```sh -insmod avirt_core.ko -insmod dummy/avirt_dummyap.ko -insmod loopback/avirt_loopbackap.ko +insmod snd-avirt-core.ko +insmod dummy/snd-avirt-ap-dummy.ko +insmod loopback/snd-avirt-ap-loopback.ko ``` ### Note: @@ -47,16 +47,16 @@ For example, in AGL: ```sh mkdir -p /lib/modules/$(uname -r)/extra -cp avirt_core.ko avirt_dummyap.ko avirt_loopbackap.ko /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 avirt_core -modprobe avirt_dummyap -modprobe avirt_loopbackap +modprobe snd-avirt-core +modprobe snd-avirt-ap-dummy +modprobe snd-avirt-ap-loopback ``` @@ -93,24 +93,24 @@ Finally, we can configure AVIRT, for example: ```sh # 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/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/avirt/streams/playback_navigation -echo "1">/config/avirt/streams/playback_navigation/channels -echo "ap_dummy">/config/avirt/streams/playback_navigation/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/avirt/streams/playback_emergency -echo "1">/config/avirt/streams/playback_emergency/channels -echo "ap_dummy">/config/avirt/streams/playback_emergency/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/avirt/streams/capture_voice -echo "1">/config/avirt/streams/capture_voice/channels -echo "ap_dummy">/config/avirt/streams/capture_voice/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/avirt/streams/sealed +echo "1">/config/snd-avirt/streams/sealed ``` Alternatively, the test script at `scripts/test_configfs.sh` can be used. -- cgit From 188712f58b309d94d26d7468a792326c464a7eda Mon Sep 17 00:00:00 2001 From: Mark Farrugia Date: Fri, 26 Oct 2018 17:30:31 +1100 Subject: Add missing changes after GitHub rebase Some Usage doc changes Signed-off-by: Mark Farrugia --- docs/3.Usage.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/3.Usage.md b/docs/3.Usage.md index f535a07..ba5c3e6 100644 --- a/docs/3.Usage.md +++ b/docs/3.Usage.md @@ -7,10 +7,11 @@ Using AVIRT 1. [Load/Unload AVIRT](#un-load-avirt) 2. [Configuring AVIRT](#configuring-avirt) +3. [Checking AVIRT](#checking-avirt) -## Loading and Unloading AVIRT +## 1. Loading and Unloading AVIRT ### Load Out of Tree @@ -61,7 +62,7 @@ modprobe snd-avirt-ap-loopback -## Configuring AVIRT +## 2. Configuring AVIRT AVIRT is configured using configfs. -- cgit