summaryrefslogtreecommitdiffstats
path: root/alsa-hook/README.md
diff options
context:
space:
mode:
authorFulup Ar Foll <fulup@iot.bzh>2017-11-01 19:22:36 +0100
committerFulup Ar Foll <fulup@iot.bzh>2017-11-01 19:22:36 +0100
commitfb2566c629de780c8ddc88058c864ea08436d1de (patch)
tree7cba08126f8fd0a11102bbd506eaf70a67022b1f /alsa-hook/README.md
parentbc799a90ab7cc23dbe7286eb38d64af545de417c (diff)
Move to support Audio-4a High Level API
Diffstat (limited to 'alsa-hook/README.md')
-rw-r--r--alsa-hook/README.md211
1 files changed, 211 insertions, 0 deletions
diff --git a/alsa-hook/README.md b/alsa-hook/README.md
new file mode 100644
index 0000000..a51ec19
--- /dev/null
+++ b/alsa-hook/README.md
@@ -0,0 +1,211 @@
+Alsa-Hook-Plugin
+
+Object: Provide a Hook on Alsa PCM to check permission again AGL Advance Audio Agent
+Status: Release Candidate
+Author: Fulup Ar Foll fulup@iot.bzh
+Date : August-2017
+ References: https://www.spinics.net/lists/alsa-devel/msg54235.html
+
+
+## Functionalities:
+ - Execute a set of unix/ws RPC request again AGL binders to allow/deny access
+ - Keep websocket open in an idependant thread in order to monitor event received from AGL audio agent
+
+## Installation
+ - Alsaplugins are typically search in /usr/share/alsa-lib. Nevertheless a full path might be given
+ - This plugin implement a hook on a slave PCM. Typically this slave PCM is a dedicated virtual channel (eg: navigation, emergency,...)
+ - Config should be place in ~/.asoundrc (see config sample in PROJECT_ROOT/conf.d/alsa)
+
+## Test
+ - Install a full .asoundrc from conf.d/project/alsa.d
+ - Check SoundCard ==> speaker-test -Dhw:v1340 -c2 -twav
+ - Check MixerPCM ==> speaker-test -DSpeakers -c2 -twav
+ - Check SoftVol ==> speaker-test -DMusicPCM -c2 -twav
+ - Check Plugin ==> speaker-test -DMultimedia -c2 -twav
+ - Check MultiMedia aplay -DDMyNavPCM /usr/share/sounds/alsa/test.wav
+
+
+## Pulse audio integration
+
+By default Pulse only auto detect hardware sound card and virtual channel should be specified
+
+ 1) update ~/.asoundrc file and check basic ALSA virtual channel works as expected
+ 2) kill/restart pulseaudio server to force alsa hookplugin loading
+ 3) declare alsa virtual channel as pulse sink
+ - pacmd load-module module-alsa-sink device=MusicPCM
+ - pacmd load-module module-alsa-sink device=NavPCM control=NavAlsaCtl
+ - pacmd list-sinks | grep -i music
+ 4) check your virtual pulse sink work
+ - paplay -d alsa_output.MusicPCM /usr/share/sounds/alsa/test.wav
+ - paplay -d alsa_output.NavPCM /usr/share/sounds/alsa/Front_Center.wav
+
+optional integration with ALSA legacy apps
+
+ 5) start audio-pol4a controller
+ - repeat previous step(3) this time with device=Multimedia device=Navigation, ....
+ 6) check virtual channel with policy controller protection
+ - paplay -d alsa_output.Multimedia /usr/share/sounds/alsa/test.wav
+ - paplay -d alsa_output.Navigation /usr/share/sounds/alsa/Front_Center.wav
+
+
+Bug/Feature:
+ 1) when softvol control is initialised from plugin and not
+ from AGL binding. At 1st run ctl has invalid TLV and cannot be used
+ Bypass Solution:
+ * start audio-binder before playing sound (binding create control before softvol plugin)
+ * run a dummy aplay -DMyNavPCM "" to get a clean control
+ 2) When using Audio-Pol4a to protect virtual channel, the audio policy controller should
+ run before adding virtual channel into pulse.
+ 3) In order to leverage SMACK to protect virtual audio role, a Pulse rooting plugin should be used.
+
+
+## Alsa Config Sample
+
+```
+# ------------------------------------------------------
+# Mixer PCM allow to play multiple stream simultaneously
+# ------------------------------------------------------
+pcm.Speakers {
+ type dmix
+ slave {pcm "hw:v1340"} #Jabra Solmate 1
+ ipc_key 1001 # ipc_key should be unique to each dmix
+}
+
+# -----------------------------------------------------
+# Register ControllerHookPlugin (ToiBeFix fullpath)
+# -----------------------------------------------------
+pcm_hook_type.CtlHookPlugin {
+ install "AlsaInstallHook"
+ lib "/home/fulup/Workspace/Audio-4a/alsa-4a/build/alsa-hook/policy_alsa_hook.so"
+}
+
+
+# -------------------------------------------------------
+# Define one Audio Virtual Channel per Audio Roles
+# -------------------------------------------------------
+pcm.MusicPCM {
+ type softvol
+
+ # Point Slave on HOOK for policies control
+ slave.pcm "Speakers"
+
+ # name should match with HAL definition
+ control.name "Playback Multimedia"
+}
+
+pcm.NaviPCM {
+ type softvol
+
+ # Point Slave on HOOK for policies control
+ slave.pcm "Speakers"
+
+ # name should match with HAL definition
+ control.name "Playback Navigation"
+}
+
+pcm.UrgentPCM {
+ type softvol
+
+ # Point Slave on HOOK for policies control
+ slave.pcm "Speakers"
+
+ # name should match with HAL definition
+ control.name "Playback Emergency"
+}
+
+# ----------------------------------------------------
+# Define one hooked PCM channel per Audio Roles
+# ----------------------------------------------------
+pcm.Multimedia {
+ type hooks
+ slave {pcm "MusicPCM"}
+ hooks.0 {
+ comment "Defined used hook sharelib and provide arguments/config to install func"
+ type "CtlHookPlugin"
+ hook_args {
+
+ # print few log messages (default false)
+ verbose true
+
+ # uri to audio-4a policy engine
+ uri="unix:/var/tmp/pol4a"
+
+ # timeout in ms (default 500)
+ timeout 5000
+
+ # force API synchronous mode
+ synchronous true
+
+ # api subcall to request a role
+ request {
+ multimedia-role "{'uid':'alsa-hook-client'}"
+ signal-timeout "{'timeout':180, 'music':'quit'}"
+ }
+
+ # api subcall to request a role
+ release {
+ release-role "{'uid':'alsa-hook-client'}"
+ }
+
+ # map AGL event on Unix signal. Search in event for json key=value
+ events {
+ sig-02 {search music, value quit}
+ sig-31 {search event, value start}
+ sig-32 {search event, value start}
+ }
+ }
+ }
+}
+
+pcm.Navigation {
+ type hooks
+ slave {pcm "NaviPCM"}
+ hooks.0 {
+ comment "Defined used hook sharelib and provide arguments/config to install func"
+ type "CtlHookPlugin"
+ hook_args {
+
+ # print few log messages (default false)
+ verbose true
+
+ # uri to audio-4a policy engine
+ uri="unix:/var/tmp/pol4a"
+
+ # timeout in ms (default 500)
+ timeout 5000
+
+ # force API synchronous mode
+ synchronous true
+
+ # api subcall to request a role
+ request {
+ navigation-role "{'uid':'alsa-hook-client'}"
+ signal-timeout "{'timeout':5, 'navi':'quit'}"
+ }
+
+ # api subcall to request a role
+ release {
+ release-role "{'uid':'alsa-hook-client'}"
+ }
+
+ # map AGL event on Unix signal. Search in event for json key=value
+ events {
+ sig-02 {search navi, value quit}
+ sig-31 {search event, value start}
+ sig-32 {search event, value start}
+ }
+ }
+ }
+}
+
+
+```
+
+NOTE:
+
+* Hook plugin is loaded by Alsa libasound within client context. It inherits client process attributes, as UID/GID and
+SMACK label when running on AGL. The smack label is control by AGL security framework.
+As a result a control request succeeds only when client application permission match requested audio role inside Cynara security database.
+
+* Hook plugin keep a connection with the Audio-Agent until PCM is closed by the application. This connection allow the
+Audio-Agent to send events. eg: pause, quit, mute, ... \ No newline at end of file