summaryrefslogtreecommitdiffstats
path: root/hook-plugin/README.md
blob: 4297498e8e42f4854b4683c964957dfa4d6481c1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
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

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
 - speaker-test -DMyNavigationHook -c2 -twav

Config
```
# 
# Author: Fulup Ar Foll
# Object: PCM hook type 
#
# Test  :  Note: Jabra_USB=hw:v1340
#  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
#  MultiMedia aplay -DDMyNavPCM /usr/share/sounds/alsa/test.wav
#
# Bug/Feature: when softvol control is initialised from plugin and not
#    from AGL binding. At 1st run ctl has invalid TLV and cannot be
#    use. Bypass Solution: 
#     * start audio-binder before playing sound (binding create control before softvol plugin)
#     * run a dummy aplay -DMyNavPCM "" to get a clean control
#
# References: https://www.spinics.net/lists/alsa-devel/msg54235.html
# --------------------------------------------------------------------

# ------------------------------------------------------
# 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/hook-plugin/policy_hook_cb.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.NavPCM {
    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
            ws-client="unix:/var/tmp/pol4a"

            # api subcall to request a role
            controls {
                # Request authorisation to write on navigation
                navigation-ctl {
                    request "navigation-role"
                    release "release-role"
                    args    "{'uid':'alsa-hook-navigation'}"
                }
            }
            events {    # map event reception to self generated signal
                pause  30
                resume 31
                stop   3
            }
        }
    }
}


```

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, ...