From 75e26b091f6aae38c9edb069c173bcb04ae3ffd1 Mon Sep 17 00:00:00 2001 From: Loïc Collignon Date: Mon, 10 Sep 2018 10:36:46 +0200 Subject: Updated documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated documentation up to date and using the gitbook format. Change-Id: Ie5d6a3bb489b9a9a95e21f5edd05bdd77bff5816 Signed-off-by: Loïc Collignon --- docs/4a-framework/README.md | 42 +++++++ docs/4a-framework/SUMMARY.md | 5 + docs/4a-framework/book.json | 11 ++ docs/4a-framework/components.md | 49 ++++++++ docs/4a-framework/concepts.md | 37 ++++++ docs/4a-framework/images/4a-architecture.svg | 155 +++++++++++++++++++++++++ docs/4a-framework/images/apps-architecture.svg | 119 +++++++++++++++++++ 7 files changed, 418 insertions(+) create mode 100644 docs/4a-framework/README.md create mode 100644 docs/4a-framework/SUMMARY.md create mode 100644 docs/4a-framework/book.json create mode 100644 docs/4a-framework/components.md create mode 100644 docs/4a-framework/concepts.md create mode 100644 docs/4a-framework/images/4a-architecture.svg create mode 100644 docs/4a-framework/images/apps-architecture.svg (limited to 'docs/4a-framework') diff --git a/docs/4a-framework/README.md b/docs/4a-framework/README.md new file mode 100644 index 0000000..90de65b --- /dev/null +++ b/docs/4a-framework/README.md @@ -0,0 +1,42 @@ +# AGL Advanced Audio Architecture (4a) + +## Abstract + +4a is an audio framework made to handle automotive use cases like stream +priority and interruptions. It does **not** deal with the audio by itself but +rather with the policies and signaling around it. This means that 4a must be +used in conjunction with an other API that is in charge of the audio stuff, +like **alsa** or **pulseaudio**. + +## Architecture + +### Global architecture + +![applications architecture diagram](images/apps-architecture.svg) + +This diagram shows the global architecture that any application playing audio +should follow. As a developer, when you want to play audio, you rely on APIs +such as alsa, pulseaudio or higher level API(s). To play audio you usually have +some kind of device URI that you have to open in order to write audio data to +it. + +4a does **not** change anything about that. You still have to do all of this. 4a +provides permissions, signals and policies. This means that all compliant +applications have to ask 4a for a 'role' when they want to play audio. If 4a +grants them the permission, it returns a device URI that applications have to +open. + +Nothing prevent an application to directly open a device, but in this case no +policies can be applied and access permissions are handled by system policies. + +### 4a Architecture + +![4a's architecture diagram](images/4a-architecture.svg) + +Even if applications only deal with the high level API, 4a is made of multiple +components that rely on each other. + +The high level API uses the hal-manager to list enabled HALs then it uses +directly those HALs. + +HALs rely directly on drivers and/or softmixer. diff --git a/docs/4a-framework/SUMMARY.md b/docs/4a-framework/SUMMARY.md new file mode 100644 index 0000000..413454c --- /dev/null +++ b/docs/4a-framework/SUMMARY.md @@ -0,0 +1,5 @@ +# Summary + +* [Architecture](README.md) +* [Concepts](concepts.md) +* [Components](components.md) \ No newline at end of file diff --git a/docs/4a-framework/book.json b/docs/4a-framework/book.json new file mode 100644 index 0000000..43eb2f0 --- /dev/null +++ b/docs/4a-framework/book.json @@ -0,0 +1,11 @@ +{ + "title": "AGL Advanced Audio Architecture (4A)", + "subtitle": "4A Framework", + "description": "This is the 4A framework documentation", + "keywords": "Audio, 4a, AGL, Development, Iotbzh", + "author": "IoT.Bzh Team", + "website": "http://iot.bzh", + "published": "September 2018", + "version": "1.0", + "pdf_filename": "AGL_4A_Framework" +} \ No newline at end of file diff --git a/docs/4a-framework/components.md b/docs/4a-framework/components.md new file mode 100644 index 0000000..2709d60 --- /dev/null +++ b/docs/4a-framework/components.md @@ -0,0 +1,49 @@ +# Components + +4a framework is made of several components which provide features to each other. +The High Level API component is the only one that exports a public API. This +means that, as an application developer you only need to care about the High +Level API. + +## High level API + +This is the publicly exported API. It exposes one verb for each audio roles, +plus **get_roles** to get the list of audio roles. + +This component manages audio roles and applies permissions, signaling and +policies. Because each role is a unique verb, it means that each role can have +its own smack label. + +It makes use of the **4a-hal-manager** to list all HALs and their +configurations. Then it uses directly the enabled HALs. + +## 4a-hal-manager + +This component is responsible for HALs detection, initialization and state +management. + +## 4a-hal-* + +This block represents all the different HALs. You can load multiple HALs +provided that they don't interfere with each other. +HALs can be provided by two means: + +* Built directly by the **4a-hal-manager** using it's controller and json files. +* External HAL (like the unicens one), that have to register themselves to the + **4a-hal-manager**. + +HALs manage audio streams and zones. The streams are bound to audio roles. + +## 4a-softmixer + +This component abstracts the real devices to virtual ones and provides some +basic mixing capabilities for devices that don't have this feature builtin. +It exposes streams named like the audio roles. + +This component can be used by HALs, but this is not mandatory. + +HALs can either : + +* use 4a-softmixer (for example when hardware doesn't provide mixing feature), + or +* take advantage from the hardware to provide the mixing capabilities. diff --git a/docs/4a-framework/concepts.md b/docs/4a-framework/concepts.md new file mode 100644 index 0000000..dba024d --- /dev/null +++ b/docs/4a-framework/concepts.md @@ -0,0 +1,37 @@ +# Concepts + +A user application requests to open an audio role, which is bound to a stream, +which is bound to a zone. This allows the application to only care about the +audio role. + +For example, a navigation application can request the **navigation** role, which +is bound to the **navigation** stream defined by the HAL. This stream is bound +to the **driver** zone, which is the closest speaker to the driver. + +## Roles + +The high level API allows applications to open roles such as **emergency**, +**navigation** or **multimedia**. A role is bound to a stream, which is +basically a device URI. When a role is opened, then the policy engine is +notified and executes an interrupt on every other opened role with a lower +priority. An interrupt is a policy engine function that can change the volume, +mute or unmute, change the stream's state. + +This behaviour allows the policy engine to take actions like lowering the radio +volume when an application wants to play something on the emergency role. + +## Streams + +A stream is basically a device URI that you can open to write audio data. For +example, it can be "hw:2,0,1", which means that you have to use this as an alsa +device URI. + +## Zones + +Multiple speakers are spread around inside a vehicule, they are named depending +on their position, like **front-center**, **front-left**, **front-right**, +**rear-left**, **rear-right**, etc... + +Zones are an abstraction of positional audio. A zone is made of one or more +speakers and describes logical audio areas like **driver**, **front**, **rear**, +etc. diff --git a/docs/4a-framework/images/4a-architecture.svg b/docs/4a-framework/images/4a-architecture.svg new file mode 100644 index 0000000..1554e8e --- /dev/null +++ b/docs/4a-framework/images/4a-architecture.svg @@ -0,0 +1,155 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 4a-hal-* + + + 4a-hal-* + + + + + + + + HARDWARE + + + + + + + + Drivers + + + + + + + + APPLICATIONS + + + + + + + + 4a-softmixer + + + + + + + + 4a-high-level + + + + + + + + 4a-hal-manager + + + + + + + + \ No newline at end of file diff --git a/docs/4a-framework/images/apps-architecture.svg b/docs/4a-framework/images/apps-architecture.svg new file mode 100644 index 0000000..4dca8b5 --- /dev/null +++ b/docs/4a-framework/images/apps-architecture.svg @@ -0,0 +1,119 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + HARDWARE + + + + + + + + APPLICATIONS + + + + + + + + Audio lib + + + + + + + + 4a + + + + + + + + \ No newline at end of file -- cgit 1.2.3-korg