add detail documentation

Signed-off-by: Tai Vuong <tvuong@audiokinetic.com>

2 files changed, 217 insertions, 67 deletions

diff --git a/README.md b/README.md
index f9b55ed..a19c38c 100644
--- a/README.md
+++ b/README.md
@@ -2,90 +2,137 @@
                   AGL Audio High Level Binding
 ------------------------------------------------------------------------
 
-# Cloning Audio High Level from Git
+# Audio High Level Binding
+-----------------------------
+The Audio High Level Binding is the upper layer in the Audio 4A architecture.
+The binding provide a simple, unified single entry point for all AGL audio applications.
+
+Here are the features provide by the binding:
+
+- Expose all audio device capabilities in uniform way to applications
+- Provide display name for device to applications  (e.g. for user selection)
+- Provide target device URI (e.g. stream to selected endpoint) to applications 
+- Automatically retrieve associated volume control for ALSA softvol URI
+- Allow fine grain security permissions control, policy enforcement and application audio stream control isolation
+- Priority-based and audio role specific endpoint selection / stream routings (automatic or explicit)
+- Aggregation of different audio domains (ALSA, Pulse)
+- Audio stream controls (volume, mute, state, properties)
+
+
+# Glossary
+-----------------------------
+The binding define the following term:
+
+- AHL                : Audio High Level Binding
+- Audio role         : Specific set of audio policy rules applied to a group of audio stream
+- Endpoint           : Virtual audio sink or source device.
+- Stream             : Audio connection between an application and an endpoint (source or sink).
+- Audio 4A Framework : AGL Audio Framework using a set of low level, HAL and HLB bindings.
+- Policy Engine      : Static library define in ahl-policy.c implementing audio policy.
+- URI		     : Uniform Resource Identifier (e.g. ALSA PCM name)
+
+
+# Policy Engine
+------------------------------
+
+The sample implementation of the policy engine is implemented as a static library.
+The interface between the policy engine and the audio high level binding is a simple JSON interface.
+This allows users to easily replace it with their own policy engine.
+
+
+# Endpoint Selection
+------------------------------
+The AHL JSON configuration file defines a number of possible endpoints per audio role. The endpoints are listed in order of priority, from highest to lowest priority.
+At initialization time, the AHL will validate each endpoint and only keep a list of available endpoints per audio role. Inactive endpoints are discarded and are not accessible to applications.
+
+Applications can request a list of available endpoints for a specific audio role by calling the API/Verb get_endpoints.
+Applications can decide to open a stream on a specific endpoint from the list by specifying an EndpointID or let AHL select automatically an endpoint based on it audio role endpoint priority list.
+In the latter case, the endpoint selected will be the first available endpoint on the audio-role specific list.
+
+# Events
+-------------------------------
+AHL will generate 4 types of events, defined in ahl-interface.h:
+
+- **AHL_STREAM_STATE_EVENT**
+
+   Applications are automatically susbcribed to this event and will only receive events for streams they have opened.
+- **AHL_ENDPOINT_VOLUME_EVENT**
+
+   Applications need to subscribe to this event to receive volume change notifications.
+- **AHL_ENDPOINT_PROPERTY_EVENT**
+
+   Applications need to subscribe to this event to receive property change notifications.
+- **AHL_POST_ACTION_EVENT**
+
+   Applications need to subscribe to this event to receive action notifications. Note: This is for future use cases, involving sound generation for example.
+
+
+# AHL Configuration File and System Configuration
+----------------------------------------------
+Please refer to README.md documentation inside subfolder:
+
+conf.d/project/README.md
+
+
+# Cloning Audio High Level Binding from Git
 -------------------------------------------------------
 
 ```
 # Initial clone with submodules
 git clone --recurse-submodules https://github.com/Audiokinetic-Automotive/afb-audiohighlevel.git
 cd  audio-binding
-
 # Do not forget submodules with pulling
 git pull --recurse-submodules https://github.com/Audiokinetic-Automotive/afb-audiohighlevel.git
 
 ```
 
-# AFB-daemon dependencies
--------------------------------------------------------
-
-    OpenSuse >=42.2, Fedora>=25, Ubuntu>=16.4 Binary packages from  https://en.opensuse.org/LinuxAutomotive
+# System libraries Dependencies
+------------------------------------------------------------------
+- libasound (version 1.1.2 or latest)
+- libsystemd (version 222 or latest)
+- libmicrohttpd (version 0.9.55 or latest)
+- afb-daemon (version 2.0 or latest)
+- json-c
+- libafbwsc
+- glib-2.0
 
-    For other distro see # Building AFB-daemon from source on Standard Linux Distribution
+# AGL Binding Dependencies
+-------------------------------------------------------------------
+AGL Audio High Level Binding is part of the AGL Audio 4A framework,
+It requires the following AGL bindings:
 
- 
-# Specific Dependencies 
+- **4a-alsa-core**
 
- * alsa-devel >= 1.1.2 Warning some distro like Fedora-25 still ship version 1.1.1 as default
- * lua >= 5.3  Most distribution only ship version 5.2 but binary package should be easy to find
+   Alsa Low Level Binding
 
-On Ubuntu 16.4 you should recompile AlsaLib from source ftp://ftp.alsa-project.org/pub/lib/
-as today latest stable is 1.1.4. 
+   source: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/4a-alsa-core
+- **4a-hal-reference**
 
+   Hardware Abstraction Layer Binding
 
-```
-  OpenSuse
-     - LUA-5.3-devel  https://software.opensuse.org//download.html?project=devel%3Alanguages%3Alua&package=lua53
-     - Alsa-devel zypper --install alsa-devel # 42.3 is shipped default with 1.1.4 
-
-  Fedora 26 (out of the box)
-     - Lua 5.3 
-     - Alsa-devel 1.1.4
-
-  Ubuntu-16.4
-     - LUA-5.3 is avaliable in binary through apt-get
-     - Alsa should be recompiled from source
- 
-        wget ftp://ftp.alsa-project.org/pub/lib/alsa-lib-1.1.4.1.tar.bz2
-        tar -xjf alsa-lib-1.1.4.1.tar.bz2
-        cd alsa-lib-1.1.4.1
-        ./configure --prefix=/opt
-
-  Ubuntu-17.04 (out of the box)
-     - Alsa 1.1.4
-     - Lua 5.3 
-
-  #WARNING: do not forget to upgrade your PKG_CONFIG_PATH=/opt/lib/pkgconfig or whatever is the place where
-  your installed alsa/lua.
-```
+   source: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/4a-hal-reference 
 
 
 # Compile AGL Audio High Level Binding
 --------------------------------------
 
-* Edit your ~/.config/app-templates/cmake.d/00-common-userconf.cmake to reflect your local configuration
-
-```
-    message(STATUS "*** User Local Config For Native Linux ***")
-    add_compile_options(-DNATIVE_LINUX)
-    
-    set(CMAKE_INSTALL_PREFIX $ENV{HOME}/opt)
-    set(BINDINGS_INSTALL_PREFIX $ENV{HOME}/opt)
+Set INSTALL_PREFIX variable to your local AGL binding install folder.
 
-    set(CMAKE_PREFIX_PATH ${CMAKE_INSTALL_PREFIX}/lib64/pkgconfig ${CMAKE_INSTALL_PREFIX}/lib/pkgconfig)
-    set(LD_LIBRARY_PATH ${CMAKE_INSTALL_PREFIX}/lib64 ${CMAKE_INSTALL_PREFIX}/lib)
 
 ```
-
+export INSTALL_PREFIX=~/opt
+mkdir -p build
+cd build
+cmake -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX ..
+make
+make install
 
 ```
-    mkdir -p build
-    cd build
-    cmake -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX ..
-    make
-    make install
 
+# Launch command to test and usage (the actual list of HAL to use may be specific to each hardware setup, please adapt name and ldpath parameters to match with your system configuration)
 
-    afb-daemon --workdir=. --ldpaths=.. --port=1234  --roothttp=./htdocs --token="" --verbose
-    
 
+```
+afb-daemon --name=audio4a --workdir=.--ldpaths=./lib:../agl-service-audio-4a/lib/afb-audiohighlevel.so:../4a-hal-reference/lib/afb-hal-intel-hda.so:../4a-alsa-core/lib/afb-alsa-4a.so --port=1234 --roothttp=./htdocs --token="" --verbose
 
+```
diff --git a/conf.d/project/README.md b/conf.d/project/README.md
index 00e3c2f..274bde3 100644
--- a/conf.d/project/README.md
+++ b/conf.d/project/README.md
@@ -1,15 +1,118 @@
+------------------------------------------------------------------------
+                     Configuration
+------------------------------------------------------------------------
 
-1) $HOME/.asoundrc or /etc/asound.conf should match you hardware audio configuration.
-2) ahl-xxxxxx-config.json should match your .asoundrc config
+#  ALSA Configuration
+An example .asoundrc is provided with the file asoundrc-audio4a. In this configuration, we choose to use software mixing of several virtual audio devices with distinct software volume controls (one per audio role). The example defines 2 audio zones with several ALSA virtual audio devices (endpoints) that applications should target. The prefix of the softvol control must match the configuration audio role name to automatically use audio role specific volume ramping and controls.
 
-Note: config file is search within with following rules:
- - default search path is $PROJECT_ROOT/conf.d/project:${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}
- - if environment variable "AAAA_CONFIG_PATH" is defined that it is used as search path
- - config file should match "ahl-BINDERNAME-config.json" where BINDERNAME is provided through "--name=BINDERNAME" in afb-daemon commande line.
+For example:
+```
+pcm.Entertainment_Main {
+ type softvol
+ slave.pcm "SoftMixer"
+ control{
+   name "Entertainment_Volume"
+   card 0
+ }
+}
+```
 
-Note: you may debug Audio-4A from your development tree with:
+Defines a PCM Entertainment_Main endpoint using Entertainment_Volume softvol control for the Entertainment audio role volume.
+Please modify your /etc/asound.conf or ~/.asoundrc configuration to match your hardware audio configuration.
 
-  afb-daemon --name=afb-audio4a --port=1234 --ws-server=unix:/var/tmp/ahl-4a --cntxtimeout=1 \
-             --alias=/monitoring:/home/fulup/opt/afb-monitoring --binding=package/lib/afb-audiohighlevel.so \
-             --ldpaths=../../alsa-4a/build/package/lib:../../hal-sample-4a/build/package/lib --workdir=. \
-             --roothttp=../htdocs --token= --verbose --verbose
\ No newline at end of file
+# AHL Configuration File
+*ahl-audio4a-config.json* is an example of an AHL configuration file.
+
+Please modify the configuration file to match with your *.asoundrc* configuration and the desired audio roles.
+Copy the file at a location as described below.
+
+# AHL Configuration File Location
+
+At loading time the AHL binding will search for a JSON configuration file located following theses rules:
+
+- default search path is $PROJECT_ROOT/conf.d/project:${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}
+- if environment variable "AAAA_CONFIG_PATH" is defined, it is used as search path
+- configuration file name should match "ahl-BINDERNAME-config.json" where BINDERNAME is provided through "--name=BINDERNAME" in afb-daemon command line.
+
+Example:
+
+```
+export AAAA_CONFIG_PATH=~/opt/config
+afb-daemon --name audio4a --workdir=.--ldpaths=./lib:../afb-aaaa/lib/afb-hal-intel-hda.so:../4a-alsa-core/lib/afb-alsa-4a.so --port=1234 --roothttp=./htdocs --token="" --verbose
+
+```
+# Configuration parameters definitions
+--------------------------------------
+
+#### hal_list
+
+ Define a list of HAL to be used with AHL. This is a list of HAL binding API names and it used by AHL to associate audio endpoints with a corresponding HAL.
+
+#### audio_roles
+
+Defines an application role specific (e.g. entertainment, navigation, etc.) list of prioritized endpoints, priorities and behaviors (e.g. interrupt) to be applied by the audio policy.
+
+Each audio role has the following parameters:
+
+- **name**
+
+   Defines the name of the audio role. Some standard audio role names are provided in ahl-policy/ahl-interface.h and used in the sample policy implementation.                  
+
+   In the sample configuration file (and accompanying policy implementation), the following audio role name are used:
+
+   - **Warning**          : Safety-relevant or critical alerts/alarms
+   - **Guidance**         : Important user information where user action is expected (e.g. navigation instruction)
+   - **Notification**     : HMI or else notifications (e.g. touchscreen events, speech recognition on/off,...)
+   - **Communication**    : Voice communications (e.g. handsfree, speech recognition)
+   - **Entertainment**    : Multimedia content (e.g. tuner, media player, etc.)
+   - **System**           : System level content or development
+   - **Startup**          : Early (startup) sound
+   - **Shutdown**         : Late (shutdown) sound
+
+
+- **priority**         
+Defines the priority audio stream associated with the audio role (will be used by policy implementation to determine audio focus).
+
+- **interupt_behavior**
+
+   Defines what happens when the current stream interrupts a lower or equal priority stream.
+
+   The following interrupt behaviors are implemented in the sample policy engine:
+
+   - "continue" : Volume ducking, the volume of the lower priority stream is lowered. The target volume value is defined by the policy engine. An AHL_ENDPOINT_VOLUME_EVENT volume event is generated.
+
+   - "pause"    : Stream paused, a AHL_STREAM_STATE_EVENT with state_event=STREAM_EVENT_PAUSE is generated for the lower priority stream(s).
+
+   - "cancel"   : Stream stop, a AHL_STREAM_STATE_EVENT with state_event=STREAM_EVENT_STOP is generated for the lower priority stream(s).
+
+  **Example**
+
+   An entertainment application is playing music on the ALSA PCM 'Entertainment_Main' (this PCM is routed to the software mixer targeting hw:0).
+   A navigation application with a higher priority request a stream to be played on the ALSA PCM 'Guidance_Main' (this PCM is also routed to the software mixer targeting hw:0).
+   The guidance audio role has the interrupt_behavior set to "continue".
+
+   The policy engine implements a volume ducking situation and the software volume control associated with 'Entertainment_Main' is lowered during the navigation application playback.
+   When the navigation application stops or closes its audio stream, the volume of 'Entertainment_Main' is restored back to it original value.
+
+- **output/input**
+
+  Defines the list of sink/source endpoints available for the audio role (in order of priority for automatic endpoint selection purposes).
+
+  The endpoint PCM URI values use the following naming convention:
+
+  *framework.pcm_name*
+
+  **Example**:
+
+  ```
+  alsa.hw:0
+  alsa.plug:Entertainment_Main
+  pulse.default
+
+  ```
+
+- **actions**
+
+  Defines the list of sound related actions supported for the audio role.
+
+  Currently not implemented, this is a provision in the configuration file for future use case such as sound generation.