biometrics.h

Go to the documentation of this file.

/*
 * Copyright (c) 2025 Siratul Islam <email@sirat.me>
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_BIOMETRICS_H_
#define ZEPHYR_INCLUDE_DRIVERS_BIOMETRICS_H_

 
#include <zephyr/device.h>
#include <zephyr/kernel.h>
#include <errno.h>
#include <stddef.h>
#include <zephyr/types.h>
 
#ifdef __cplusplus
extern "C" {
#endif

enum biometric_sensor_type {
        BIOMETRIC_TYPE_FINGERPRINT, 
        BIOMETRIC_TYPE_IRIS,        
        BIOMETRIC_TYPE_FACE,        
        BIOMETRIC_TYPE_VOICE,       
};

enum biometric_match_mode {
        BIOMETRIC_MATCH_VERIFY,   
        BIOMETRIC_MATCH_IDENTIFY, 
};

#define BIOMETRIC_STORAGE_DEVICE BIT(0) 
#define BIOMETRIC_STORAGE_HOST   BIT(1) 

enum biometric_led_state {
        BIOMETRIC_LED_OFF,    
        BIOMETRIC_LED_ON,     
        BIOMETRIC_LED_BLINK,  
        BIOMETRIC_LED_BREATHE 
};

enum biometric_attribute {
        BIOMETRIC_ATTR_MATCH_THRESHOLD,
        BIOMETRIC_ATTR_ENROLLMENT_QUALITY,
        BIOMETRIC_ATTR_SECURITY_LEVEL,
        BIOMETRIC_ATTR_TIMEOUT_MS,
        BIOMETRIC_ATTR_ANTI_SPOOF_LEVEL,
        BIOMETRIC_ATTR_IMAGE_QUALITY,
        BIOMETRIC_ATTR_COMMON_COUNT,
        BIOMETRIC_ATTR_PRIV_START = BIOMETRIC_ATTR_COMMON_COUNT,
        BIOMETRIC_ATTR_MAX = INT16_MAX,
};

struct biometric_capabilities {
        enum biometric_sensor_type type;
        uint16_t max_templates;
        uint16_t template_size;
        uint8_t storage_modes;
        uint8_t enrollment_samples_required;
};

struct biometric_match_result {
        int32_t confidence;
        uint16_t template_id;
        uint8_t image_quality;
};

struct biometric_capture_result {
        uint8_t samples_captured;
        uint8_t samples_required;
        uint8_t quality;
};


typedef int (*biometric_api_get_capabilities)(const struct device *dev,
                                              struct biometric_capabilities *caps);

typedef int (*biometric_api_attr_set)(const struct device *dev, enum biometric_attribute attr,
                                      int32_t val);

typedef int (*biometric_api_attr_get)(const struct device *dev, enum biometric_attribute attr,
                                      int32_t *val);

typedef int (*biometric_api_enroll_start)(const struct device *dev, uint16_t template_id);

typedef int (*biometric_api_enroll_capture)(const struct device *dev, k_timeout_t timeout,
                                            struct biometric_capture_result *result);

typedef int (*biometric_api_enroll_finalize)(const struct device *dev);

typedef int (*biometric_api_enroll_abort)(const struct device *dev);

typedef int (*biometric_api_template_store)(const struct device *dev, uint16_t id,
                                            const uint8_t *data, size_t size);

typedef int (*biometric_api_template_read)(const struct device *dev, uint16_t id, uint8_t *data,
                                           size_t size);

typedef int (*biometric_api_template_delete)(const struct device *dev, uint16_t id);

typedef int (*biometric_api_template_delete_all)(const struct device *dev);

typedef int (*biometric_api_template_list)(const struct device *dev, uint16_t *ids,
                                           size_t max_count, size_t *actual_count);

typedef int (*biometric_api_match)(const struct device *dev, enum biometric_match_mode mode,
                                   uint16_t template_id, k_timeout_t timeout,
                                   struct biometric_match_result *result);

typedef int (*biometric_api_led_control)(const struct device *dev, enum biometric_led_state state);

__subsystem struct biometric_driver_api {
        biometric_api_get_capabilities get_capabilities;
        biometric_api_attr_set attr_set;
        biometric_api_attr_get attr_get;
        biometric_api_enroll_start enroll_start;
        biometric_api_enroll_capture enroll_capture;
        biometric_api_enroll_finalize enroll_finalize;
        biometric_api_enroll_abort enroll_abort;
        biometric_api_template_store template_store;
        biometric_api_template_read template_read;
        biometric_api_template_delete template_delete;
        biometric_api_template_delete_all template_delete_all;
        biometric_api_template_list template_list;
        biometric_api_match match;
        biometric_api_led_control led_control;
};


__syscall int biometric_get_capabilities(const struct device *dev,
                                         struct biometric_capabilities *caps);
 
static inline int z_impl_biometric_get_capabilities(const struct device *dev,
                                                    struct biometric_capabilities *caps)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
        __ASSERT_NO_MSG(caps != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        return api->get_capabilities(dev, caps);
}

__syscall int biometric_attr_set(const struct device *dev, enum biometric_attribute attr,
                                 int32_t val);
 
static inline int z_impl_biometric_attr_set(const struct device *dev, enum biometric_attribute attr,
                                            int32_t val)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        if (api->attr_set == NULL) {
                return -ENOSYS;
        }
 
        return api->attr_set(dev, attr, val);
}

__syscall int biometric_attr_get(const struct device *dev, enum biometric_attribute attr,
                                 int32_t *val);
 
static inline int z_impl_biometric_attr_get(const struct device *dev, enum biometric_attribute attr,
                                            int32_t *val)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
        __ASSERT_NO_MSG(val != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        if (api->attr_get == NULL) {
                return -ENOSYS;
        }
 
        return api->attr_get(dev, attr, val);
}

__syscall int biometric_enroll_start(const struct device *dev, uint16_t template_id);
 
static inline int z_impl_biometric_enroll_start(const struct device *dev, uint16_t template_id)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        return api->enroll_start(dev, template_id);
}

__syscall int biometric_enroll_capture(const struct device *dev, k_timeout_t timeout,
                                       struct biometric_capture_result *result);
 
static inline int z_impl_biometric_enroll_capture(const struct device *dev, k_timeout_t timeout,
                                                  struct biometric_capture_result *result)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        return api->enroll_capture(dev, timeout, result);
}

__syscall int biometric_enroll_finalize(const struct device *dev);
 
static inline int z_impl_biometric_enroll_finalize(const struct device *dev)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        return api->enroll_finalize(dev);
}

__syscall int biometric_enroll_abort(const struct device *dev);
 
static inline int z_impl_biometric_enroll_abort(const struct device *dev)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        if (api->enroll_abort == NULL) {
                return -ENOSYS;
        }
 
        return api->enroll_abort(dev);
}

__syscall int biometric_template_store(const struct device *dev, uint16_t id, const uint8_t *data,
                                       size_t size);
 
static inline int z_impl_biometric_template_store(const struct device *dev, uint16_t id,
                                                  const uint8_t *data, size_t size)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
        __ASSERT_NO_MSG(data != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        if (api->template_store == NULL) {
                return -ENOSYS;
        }
 
        return api->template_store(dev, id, data, size);
}

__syscall int biometric_template_read(const struct device *dev, uint16_t id, uint8_t *data,
                                      size_t size);
 
static inline int z_impl_biometric_template_read(const struct device *dev, uint16_t id,
                                                 uint8_t *data, size_t size)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
        __ASSERT_NO_MSG(data != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        if (api->template_read == NULL) {
                return -ENOSYS;
        }
 
        return api->template_read(dev, id, data, size);
}

__syscall int biometric_template_delete(const struct device *dev, uint16_t id);
 
static inline int z_impl_biometric_template_delete(const struct device *dev, uint16_t id)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        return api->template_delete(dev, id);
}

__syscall int biometric_template_delete_all(const struct device *dev);
 
static inline int z_impl_biometric_template_delete_all(const struct device *dev)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        if (api->template_delete_all == NULL) {
                return -ENOSYS;
        }
 
        return api->template_delete_all(dev);
}

__syscall int biometric_template_list(const struct device *dev, uint16_t *ids, size_t max_count,
                                      size_t *actual_count);
 
static inline int z_impl_biometric_template_list(const struct device *dev, uint16_t *ids,
                                                 size_t max_count, size_t *actual_count)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
        __ASSERT_NO_MSG(ids != NULL);
        __ASSERT_NO_MSG(actual_count != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        if (api->template_list == NULL) {
                return -ENOSYS;
        }
 
        return api->template_list(dev, ids, max_count, actual_count);
}

__syscall int biometric_match(const struct device *dev, enum biometric_match_mode mode,
                              uint16_t template_id, k_timeout_t timeout,
                              struct biometric_match_result *result);
 
static inline int z_impl_biometric_match(const struct device *dev, enum biometric_match_mode mode,
                                         uint16_t template_id, k_timeout_t timeout,
                                         struct biometric_match_result *result)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        return api->match(dev, mode, template_id, timeout, result);
}

__syscall int biometric_led_control(const struct device *dev, enum biometric_led_state state);
 
static inline int z_impl_biometric_led_control(const struct device *dev,
                                               enum biometric_led_state state)
{
        const struct biometric_driver_api *api;
 
        __ASSERT_NO_MSG(dev != NULL);
 
        api = (const struct biometric_driver_api *)dev->api;
 
        if (api->led_control == NULL) {
                return -ENOSYS;
        }
 
        return api->led_control(dev, state);
}
 
#ifdef __cplusplus
}
#endif

 
#include <zephyr/syscalls/biometrics.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_BIOMETRICS_H_ */