Hardware: Fingerprint: Move the HAL to an async model, add some vendor requested functionality.

Change-Id: Ib99e3edb99579ac4495918eb57d1022d75dccb57
Signed-off-by: Sasha Levitskiy <sanek@google.com>

1 files changed, 63 insertions, 28 deletions

diff --git a/include/hardware/fingerprint.h b/include/hardware/fingerprint.h
index be2f9e2..acd96e2 100644
--- a/include/hardware/fingerprint.h
+++ b/include/hardware/fingerprint.h
@@ -20,63 +20,98 @@
 #define FINGERPRINT_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
 #define FINGERPRINT_HARDWARE_MODULE_ID "fingerprint"
 
-typedef enum fingerprint_msg {
+typedef enum fingerprint_msg_type {
     FINGERPRINT_ERROR = -1,
-    FINGERPRINT_NO_MATCH = 0,
-    FINGERPRINT_MATCH = 1,
+    FINGERPRINT_SCANNED = 1,
     FINGERPRINT_TEMPLATE_COLLECTING = 2,
-    FINGERPRINT_TEMPLATE_REGISTERED = 3,
     FINGERPRINT_TEMPLATE_DELETED = 4
-} fingerprint_msg_t;
+} fingerprint_msg_type_t;
 
 typedef enum fingerprint_error {
     FINGERPRINT_ERROR_HW_UNAVAILABLE = 1,
-    FINGERPRINT_ERROR_BAD_CAPTURE = 2
+    FINGERPRINT_ERROR_BAD_CAPTURE = 2,
+    FINGERPRINT_ERROR_TIMEOUT = 3
 } fingerprint_error_t;
 
+typedef struct fingerprint_enroll {
+    uint32_t id;
+    /* samples_remaining goes form N (no data collected, but N scans needed)
+     * to 0 (no more data is needed to build a template)
+     * If HAL fails to decrement samples_remaining between calls the client
+     * will declare template collection a failure and should abort the operation
+     * by calling fingerprint_close() */
+    uint32_t samples_remaining;
+} fingerprint_enroll_t;
+
+typedef struct fingerprint_scanned {
+    uint32_t id; /* 0 is a special id and means no match */
+    uint32_t confidence; /* Goes form 0 (no match) to 0xffffFFFF (100% sure) */
+} fingerprint_ident_t;
+
+typedef struct fingerprint_msg {
+    fingerprint_msg_type_t type;
+    union {
+        uint64_t raw;
+        fingerprint_error_t error;
+        fingerprint_enroll_t enroll;
+        fingerprint_ident_t ident;
+    } data;
+} fingerprint_msg_t;
+
+/* Callback function type */
+typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg);
+
 /* Synchronous operation */
 typedef struct fingerprint_device {
     struct hw_device_t common;
 
     /*
-     * Figerprint enroll request: records and stores a fingerprint template.
-     * Timeout after temeout_sec seconds.
+     * Figerprint enroll request:
+     * Switches the HAL state machine to collect and store a new fingerprint
+     * template. Switches back as soon as enroll is complete
+     * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_COLLECTING &&
+     *  fingerprint_msg.data.enroll.samples_remaining == 0)
+     * or after temeout_sec seconds.
      *
-     * Function return:
-     *   - Machine state: error, collected or registered.
-     *   - Data is interpreted as error code, collection percentage
-     *     or fingerprint id.
+     * Function return: 0 if enrollment process can be successfully started
+     *                 -1 otherwise.
      */
-    fingerprint_msg_t (*enroll)(unsigned timeout_sec, unsigned *data);
+    int (*enroll)(struct fingerprint_device *dev, unsigned timeout_sec);
 
     /*
-     * Figerprint remove request: deletes a fingerprint template.
+     * Figerprint remove request:
+     * deletes a fingerprint template.
+     * If the fingerprint id is 0 the entire template database will be removed.
      *
-     * Function return:
-     *   - Delete result: error or success.
+     * Function return: 0 if fingerprint template can be successfully deleted
+     *                 -1 otherwise.
      */
-    fingerprint_msg_t (*remove)(unsigned fingerprint_id);
+    int (*remove)(struct fingerprint_device *dev, uint32_t fingerprint_id);
 
     /*
-     * Figerprint match request: Collect a fingerprint and
-     * match against stored template with fingerprint_id.
-     * Timeout after temeout_sec seconds.
+     * Set notification callback:
+     * Registers a user function that would receive notifications from the HAL
+     * The call will block if the HAL state machine is in busy state until HAL
+     * leaves the busy state.
      *
-     * Function return:
-     *   - Match, no match or error.
+     * Function return: 0 if callback function is successfuly registered
+     *                 -1 otherwise.
      */
-    fingerprint_msg_t (*match)(unsigned fingerprint_id, unsigned timeout_sec);
+    int (*set_notify)(struct fingerprint_device *dev,
+                        fingerprint_notify_t notify);
+
+    /*
+     * Client provided callback function to receive notifications.
+     * Do not set by hand, use the function above instead.
+     */
+    fingerprint_notify_t notify;
 
     /* Reserved for future use. Must be NULL. */
-    void* reserved[8 - 3];
+    void* reserved[8 - 4];
 } fingerprint_device_t;
 
 typedef struct fingerprint_module {
     struct hw_module_t common;
 } fingerprint_module_t;
 
-/* For asyncronous mode - as a possible API model
-typedef void (*fingerprint_callback)(int request_id, fingerprint_msg msg, data);
-*/
-
 #endif  /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */