README
1 ==== Summary ====
2
3 android.frameworks.sensorservice (a] 1.0 is a package that mimics the sensors API in
4 NDK (sensor.h). It includes a subset of these APIs and introduces a few
5 adaptations.
6
7 === Design Details ===
8
9 - ISensorManager
10 ISensorMangaer includes member functions that adapts the ASensorManager_*
11 series in NDK. An instance of ISensorManager must be able to
12 - retrieve sensors
13 - create direct report channel
14 - create event queue
15
16 - IDirectReportChannel
17 IDirectReportChannel corresponds to a channel ID, an integer obtained in
18 ASensorManager_createSharedMemoryDirectChannel and
19 ASensorManager_createHardwareBufferDirectChannel. An instance of
20 IDirectReportChannel must also destroy it against the sensor manager. An
21 IDirectReportChannel must be able to configure itself (an adaptation to
22 ASensorManager_configureDirectReport). The implementation must also call
23 ASensorManager_destroyEventQueue on destruction of IDirectReportChannel.
24
25 Usage typically looks like this (transaction errors are not handled):
26
27 sp<ISensorManager> manager = ISensorManager::getService();
28 int32_t sensorHandle;
29 manager->getDefaultSensor(SensorType::GYROSCOPE,
30 [&sensorHandle] (const auto &info) {
31 sensorHandle = info.sensorHandle;
32 });
33 hidl_memory mem;
34 const uint64_t size = 4096;
35 ::android::hidl::memory::V1_0::IAllocator::getService()->allocate(size,
36 [&](auto, const auto &m) { mem = m; });
37 if (!mem.handle()) {
38 /* error handling */
39 }
40 sp<IDirectChannel> chan;
41 Result res;
42 manager->createAshmemDirectChannel(mem, size,
43 [&chan, &res] (const auto &c, auto r) {
44 chan = c; res = r;
45 });
46 if (res != Result::OK) { /* error handling */ }
47 chan->configure(sensorHandle, RateLevel::FAST, [&](auto token, auto result) {
48 if (result != Result::OK) {
49 /* error handling */
50 }
51 });
52
53 /* obtain sensor events from shared memory */
54
55 chan->configure(sensorHandle, RateLevel::STOP, [&](auto token, auto result) {
56 if (result != Result::OK) {
57 /* error handling */
58 }
59 });
60
61 /*
62 * Free the channel.
63 * kernel calls decStrong() on server side implementation of IDirectChannel,
64 * hence resources are freed as well.
65 */
66 chan = nullptr;
67
68 - IEventQueue, IEventQueueCallback
69 IEventQueue includes member functions that adapts some of the
70 ASensorEventQueue_* seeries in NDK. An instance of IEventQueue must be able to
71 - enable selected sensors (adapts ASensorEventQueue_registerSensor)
72 - disable selected sensors (adapts ASensorEventQueue_disableSensor)
73
74 The implementation must free all resources related to this IEventQueue instance
75 and call ASensorManager_destroyEventQueue on destruction of IEventQueue.
76
77 Unlike NDK ASensorEventQueue_hasEvents and ASensorEventQueue_getEvents, which
78 implies a poll model for sensor events, IEventQueue uses a push model by using
79 callbacks. When creating an event queue, client must provide an instance of
80 IEventQueueCallback. The implementation of IEventQueue must either use a global
81 looper or create a new looper to call on ASensorManager_createEventQueue. The
82 server implementation must use this looper to constantly poll for events, then
83 invoke the callback when any event is fired.
84
85 IEventQueueCallback.onEvent is designed to be oneway, because the server should
86 not wait for the client to finish handling the event. The callback
87 should finish in a predictably short time, and should not block or run for an
88 extended period of time. The callbacks can be invoked in a very high frequency;
89 a long running callback means delay in handling of subsequent events and filling
90 up the (kernel binder buffer) memory space of the client process, eventually the
91 server sees a transaction error when issuing the callback. It is up to the
92 client to be configured single-threaded or multi-threaded to handle these
93 callbacks.
94 - Single-threaded clients receive events in the correct order in the same
95 thread.
96 - Multi-threaded clients receive events in the correct order but in
97 different threads; it is the clients' responsibility to deal with
98 concurrency issues and handle events in the expected order to avoid race
99 conditions.
100
101 Usage typically looks like this (transaction errors are not handled):
102
103 struct Callback : IEventQueueCallback {
104 Return<void> onEvent(const Event &e) {
105 /* handle sensor event e */
106 }
107 };
108 sp<ISensorManager> manager = ISensorManager::getService();
109 int32_t sensorHandle;
110 manager->getDefaultSensor(SensorType::GYROSCOPE,
111 [&sensorHandle] (const auto &info) {
112 sensorHandle = info.sensorHandle;
113 });
114 sp<IEventQueue> queue;
115 Result res;
116 manager->createEventQueue(new Callback(),
117 [&queue, &res] (const auto &q, auto r) {
118 queue = q; res = r;
119 });
120 /* Server side implementation of IEventQueue holds a strong reference to
121 * the callback. */
122 if (res != Result::OK) { /* error handling */ }
123
124 if (q->enableSensor(sensorHandle,
125 20000 /* sample period */, 0 /* latency */) != Result::OK) {
126 /* error handling */
127 }
128
129 /* start receiving events via onEvent */
130
131 if (q->disableSensor(sensorHandle) != Result::OK) {
132 /* error handling */
133 }
134
135 /*
136 * Free the event queue.
137 * kernel calls decStrong() on server side implementation of IEventQueue,
138 * hence resources (including the callback) are freed as well.
139 */
140 queue = nullptr;
141