blob: 1fe8cc9dfcd0581983b53172fc42f8dfa8011b0e [file] [log] [blame]
Sasha Levitskiya747c062014-03-24 16:14:42 -07001/*
2 * Copyright (C) 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H
18#define ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H
19
20#define FINGERPRINT_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -080021#define FINGERPRINT_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0)
Sasha Levitskiya747c062014-03-24 16:14:42 -070022#define FINGERPRINT_HARDWARE_MODULE_ID "fingerprint"
23
Sasha Levitskiy73082842014-04-18 11:14:11 -070024typedef enum fingerprint_msg_type {
Sasha Levitskiya747c062014-03-24 16:14:42 -070025 FINGERPRINT_ERROR = -1,
Sasha Levitskiyba45e052014-06-09 13:19:52 -070026 FINGERPRINT_ACQUIRED = 1,
27 FINGERPRINT_PROCESSED = 2,
28 FINGERPRINT_TEMPLATE_ENROLLING = 3,
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -080029 FINGERPRINT_TEMPLATE_REMOVED = 4,
30 FINGERPRINT_AUTHENTICATED = 5
Sasha Levitskiy73082842014-04-18 11:14:11 -070031} fingerprint_msg_type_t;
Sasha Levitskiya747c062014-03-24 16:14:42 -070032
33typedef enum fingerprint_error {
34 FINGERPRINT_ERROR_HW_UNAVAILABLE = 1,
Sasha Levitskiyba45e052014-06-09 13:19:52 -070035 FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2,
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -070036 FINGERPRINT_ERROR_TIMEOUT = 3,
Jim Miller1fb1e332015-03-24 19:25:47 -070037 FINGERPRINT_ERROR_NO_SPACE = 4, /* No space available to store a template */
38 FINGERPRINT_ERROR_CANCELED = 5,
39 FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6, /* fingerprint id can't be removed */
40 FINGERPRINT_ERROR_VENDOR_BASE = 1000 /* vendor-specific error messages start here */
Sasha Levitskiya747c062014-03-24 16:14:42 -070041} fingerprint_error_t;
42
Jim Miller953524b2014-06-16 17:59:40 -070043typedef enum fingerprint_acquired_info {
44 FINGERPRINT_ACQUIRED_GOOD = 0,
45 FINGERPRINT_ACQUIRED_PARTIAL = 1,
46 FINGERPRINT_ACQUIRED_INSUFFICIENT = 2,
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -080047 FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3,
48 FINGERPRINT_ACQUIRED_TOO_SLOW = 4,
49 FINGERPRINT_ACQUIRED_TOO_FAST = 5,
Jim Miller1fb1e332015-03-24 19:25:47 -070050 FINGERPRINT_ACQUIRED_VENDOR_BASE = 1000 /* vendor-specific acquisition messages start here */
Jim Miller953524b2014-06-16 17:59:40 -070051} fingerprint_acquired_info_t;
Sasha Levitskiyba45e052014-06-09 13:19:52 -070052
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -080053typedef struct fingerprint_finger_id {
54 uint32_t gid;
55 uint32_t fid;
56} fingerprint_finger_id_t;
57
58/* The progress indication may be augmented by a bitmap encoded indication
59* of what finger area is considered as collected.
60* Bit numbers mapped to physical location:
61*
62* distal
63* +--+--+--+--+--+
64* | 4| 3| 2| 1| 0|
65* | 9| 8| 7| 6| 5|
66* medial |14|13|12|11|10| lateral
67* |19|18|17|16|15|
68* |24|23|22|21|20|
69* +--+--+--+--+--+
70* proximal
71*
72*/
73typedef uint32_t finger_map_bmp;
74
75typedef enum fingerprint_enroll_msg_type {
76 FINGERPRINT_ENROLL_MSG_NONE = 0,
77 FINGERPRINT_ENROLL_MSG_PREDEFINED = 1, /* TODO: define standard enroll cues */
78 FINGERPRINT_ENROLL_MSG_BITMAP = 2, /* typeof(fingerprint_enroll.msg) == *finger_map_bmp */
79 FINGERPRINT_ENROLL_MSG_VENDOR = 3
80} fingerprint_enroll_msg_type_t;
81
Sasha Levitskiy73082842014-04-18 11:14:11 -070082typedef struct fingerprint_enroll {
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -080083 fingerprint_finger_id_t finger;
Sasha Levitskiy3b9ee8d2014-04-23 10:04:57 -070084 /* samples_remaining goes from N (no data collected, but N scans needed)
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -080085 * to 0 (no more data is needed to build a template). */
Jim Miller1fb1e332015-03-24 19:25:47 -070086 uint32_t samples_remaining;
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -080087 fingerprint_enroll_msg_type_t msg_type;
88 size_t msg_size;
89 void *msg;
Sasha Levitskiy73082842014-04-18 11:14:11 -070090} fingerprint_enroll_t;
91
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -070092typedef struct fingerprint_removed {
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -080093 fingerprint_finger_id_t finger;
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -070094} fingerprint_removed_t;
95
Sasha Levitskiyba45e052014-06-09 13:19:52 -070096typedef struct fingerprint_acquired {
Jim Miller953524b2014-06-16 17:59:40 -070097 fingerprint_acquired_info_t acquired_info; /* information about the image */
Sasha Levitskiyba45e052014-06-09 13:19:52 -070098} fingerprint_acquired_t;
99
100typedef struct fingerprint_processed {
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -0800101 fingerprint_finger_id_t finger; /* all 0s is a special case and means no match */
Sasha Levitskiyba45e052014-06-09 13:19:52 -0700102} fingerprint_processed_t;
Sasha Levitskiy73082842014-04-18 11:14:11 -0700103
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -0800104typedef struct fingerprint_authenticated {
105 uint32_t user_id;
106 uint32_t auth_id;
107 uint32_t timestamp;
108 uint32_t app_id;
109 uint64_t crypto_op_id;
110 uint8_t hmac[16]; /* 128-bit */
111 uint32_t auth_token_size;
112 uint8_t *auth_token;
113} fingerprint_authenticated_t;
114
Sasha Levitskiy73082842014-04-18 11:14:11 -0700115typedef struct fingerprint_msg {
116 fingerprint_msg_type_t type;
117 union {
Sasha Levitskiy73082842014-04-18 11:14:11 -0700118 fingerprint_error_t error;
119 fingerprint_enroll_t enroll;
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -0700120 fingerprint_removed_t removed;
Sasha Levitskiyba45e052014-06-09 13:19:52 -0700121 fingerprint_acquired_t acquired;
122 fingerprint_processed_t processed;
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -0800123 fingerprint_authenticated_t authenticated;
Sasha Levitskiy73082842014-04-18 11:14:11 -0700124 } data;
125} fingerprint_msg_t;
126
127/* Callback function type */
128typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg);
129
Sasha Levitskiya747c062014-03-24 16:14:42 -0700130/* Synchronous operation */
131typedef struct fingerprint_device {
Stewart Miles84d35492014-05-01 09:03:27 -0700132 /**
Sasha Levitskiyba45e052014-06-09 13:19:52 -0700133 * Common methods of the fingerprint device. This *must* be the first member
134 * of fingerprint_device as users of this structure will cast a hw_device_t
135 * to fingerprint_device pointer in contexts where it's known
136 * the hw_device_t references a fingerprint_device.
Stewart Miles84d35492014-05-01 09:03:27 -0700137 */
Sasha Levitskiya747c062014-03-24 16:14:42 -0700138 struct hw_device_t common;
139
140 /*
Sasha Levitskiy3b9ee8d2014-04-23 10:04:57 -0700141 * Fingerprint enroll request:
Sasha Levitskiy73082842014-04-18 11:14:11 -0700142 * Switches the HAL state machine to collect and store a new fingerprint
143 * template. Switches back as soon as enroll is complete
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -0700144 * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
Sasha Levitskiy73082842014-04-18 11:14:11 -0700145 * fingerprint_msg.data.enroll.samples_remaining == 0)
Sasha Levitskiy3b9ee8d2014-04-23 10:04:57 -0700146 * or after timeout_sec seconds.
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -0800147 * The fingerprint template will be assigned to the group gid. User has a choice
148 * to supply the gid or set it to 0 in which case a unique group id will be generated.
Sasha Levitskiya747c062014-03-24 16:14:42 -0700149 *
Sasha Levitskiy73082842014-04-18 11:14:11 -0700150 * Function return: 0 if enrollment process can be successfully started
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -0700151 * -1 otherwise. A notify() function may be called
152 * indicating the error condition.
Sasha Levitskiya747c062014-03-24 16:14:42 -0700153 */
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -0800154 int (*enroll)(struct fingerprint_device *dev, uint32_t gid, uint32_t timeout_sec);
Sasha Levitskiya747c062014-03-24 16:14:42 -0700155
156 /*
Sasha Levitskiy969466c2014-05-07 09:07:11 -0700157 * Cancel fingerprint enroll request:
158 * Switches the HAL state machine back to accept a fingerprint scan mode.
159 * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
160 * fingerprint_msg.data.enroll.samples_remaining == 0)
161 * will indicate switch back to the scan mode.
162 *
163 * Function return: 0 if cancel request is accepted
164 * -1 otherwise.
165 */
166 int (*enroll_cancel)(struct fingerprint_device *dev);
167
168 /*
Sasha Levitskiy3b9ee8d2014-04-23 10:04:57 -0700169 * Fingerprint remove request:
Sasha Levitskiy73082842014-04-18 11:14:11 -0700170 * deletes a fingerprint template.
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -0800171 * If the fingerprint id is 0 and the group is 0 then the entire template
172 * database will be removed. A combinaiton of fingerprint id 0 and a valid
173 * group id deletes all fingreprints in that group.
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -0700174 * notify() will be called for each template deleted with
175 * fingerprint_msg.type == FINGERPRINT_TEMPLATE_REMOVED and
176 * fingerprint_msg.data.removed.id indicating each template id removed.
Sasha Levitskiya747c062014-03-24 16:14:42 -0700177 *
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -0700178 * Function return: 0 if fingerprint template(s) can be successfully deleted
Sasha Levitskiy73082842014-04-18 11:14:11 -0700179 * -1 otherwise.
Sasha Levitskiya747c062014-03-24 16:14:42 -0700180 */
Sasha Levitskiy3b7402e2014-12-11 06:49:36 -0800181 int (*remove)(struct fingerprint_device *dev, fingerprint_finger_id_t finger);
182
183 /*
184 * Restricts the HAL operation to a set of fingerprints belonging to a
185 * group provided. Gid of 0 signals global operation.
186 *
187 * Function return: 0 on success
188 * -1 if the group does not exist.
189 */
190 int (*set_active_group)(struct fingerprint_device *dev, uint32_t gid);
191
192 /*
193 * Authenticates an operation identifed by operation_id
194 *
195 * Function return: 0 on success
196 * -1 if the size is out of bounds.
197 */
Jim Miller1fb1e332015-03-24 19:25:47 -0700198 int (*authenticate)(struct fingerprint_device *dev, uint64_t operation_id, uint32_t gid);
Sasha Levitskiya747c062014-03-24 16:14:42 -0700199
200 /*
Sasha Levitskiy73082842014-04-18 11:14:11 -0700201 * Set notification callback:
202 * Registers a user function that would receive notifications from the HAL
203 * The call will block if the HAL state machine is in busy state until HAL
204 * leaves the busy state.
Sasha Levitskiya747c062014-03-24 16:14:42 -0700205 *
Sasha Levitskiy73082842014-04-18 11:14:11 -0700206 * Function return: 0 if callback function is successfuly registered
207 * -1 otherwise.
Sasha Levitskiya747c062014-03-24 16:14:42 -0700208 */
Sasha Levitskiy73082842014-04-18 11:14:11 -0700209 int (*set_notify)(struct fingerprint_device *dev,
210 fingerprint_notify_t notify);
211
212 /*
213 * Client provided callback function to receive notifications.
214 * Do not set by hand, use the function above instead.
215 */
216 fingerprint_notify_t notify;
Sasha Levitskiya747c062014-03-24 16:14:42 -0700217
218 /* Reserved for future use. Must be NULL. */
Sasha Levitskiy73082842014-04-18 11:14:11 -0700219 void* reserved[8 - 4];
Sasha Levitskiya747c062014-03-24 16:14:42 -0700220} fingerprint_device_t;
221
222typedef struct fingerprint_module {
Stewart Miles84d35492014-05-01 09:03:27 -0700223 /**
Sasha Levitskiyba45e052014-06-09 13:19:52 -0700224 * Common methods of the fingerprint module. This *must* be the first member
225 * of fingerprint_module as users of this structure will cast a hw_module_t
226 * to fingerprint_module pointer in contexts where it's known
227 * the hw_module_t references a fingerprint_module.
Stewart Miles84d35492014-05-01 09:03:27 -0700228 */
Sasha Levitskiya747c062014-03-24 16:14:42 -0700229 struct hw_module_t common;
230} fingerprint_module_t;
231
Sasha Levitskiya747c062014-03-24 16:14:42 -0700232#endif /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */