haptics.h

Go to the documentation of this file.

/*
 * Copyright 2024 Cirrus Logic, Inc.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_HAPTICS_H_
#define ZEPHYR_INCLUDE_DRIVERS_HAPTICS_H_

 
#include <zephyr/audio/codec.h>
#include <zephyr/device.h>
#include <zephyr/drivers/sensor.h>
#include <zephyr/sys/__assert.h>
 
#ifdef __cplusplus
extern "C" {
#endif

enum haptics_error_type {
        HAPTICS_ERROR_OVERCURRENT = BIT(0),     
        HAPTICS_ERROR_OVERTEMPERATURE = BIT(1), 
        HAPTICS_ERROR_UNDERVOLTAGE = BIT(2),    
        HAPTICS_ERROR_OVERVOLTAGE = BIT(3),     
        HAPTICS_ERROR_DC = BIT(4),              
 
        /* Device-specific error codes can follow, refer to the device’s header file */
        HAPTICS_ERROR_PRIV_START = BIT(5),
};

enum haptics_monitor {
        HAPTICS_MONITOR_BEMF,         
        HAPTICS_MONITOR_CURRENT,      
        HAPTICS_MONITOR_F0,           
        HAPTICS_MONITOR_RE,           
        HAPTICS_MONITOR_AMBIENT_TEMP, 
        HAPTICS_MONITOR_DIE_TEMP,     
        HAPTICS_MONITOR_VBAT,         
        HAPTICS_MONITOR_VBST,         
        HAPTICS_MONITOR_VOUT,         
        HAPTICS_MONITOR_ALL,          
 
        /* Device-specific sensing options, refer to the device's header file */
        HAPTICS_MONITOR_PRIV_START,
};

enum haptics_monitor_type {
        HAPTICS_MONITOR_TYPE_MIN,    
        HAPTICS_MONITOR_TYPE_MAX,    
        HAPTICS_MONITOR_TYPE_MEAN,   
        HAPTICS_MONITOR_TYPE_SINGLE, 
 
        /* Device-specific monitor sample types, refer to the device's header file */
        HAPTICS_MONITOR_TYPE_PRIV_START,
};

enum haptics_source {
        HAPTICS_SOURCE_ROM,          
        HAPTICS_SOURCE_RAM,          
        HAPTICS_SOURCE_DAI,          
        HAPTICS_SOURCE_ANALOG,       
        HAPTICS_SOURCE_PWM,          
        HAPTICS_SOURCE_CONTROL_PORT, 
        HAPTICS_SOURCE_ALL,          
 
        /* Device-specific playback sources, refer to the device’s header file */
        HAPTICS_SOURCE_PRIV_START,
};

enum haptics_trigger_type {
        HAPTICS_TRIGGER_NONE,             
        HAPTICS_TRIGGER_RISING = BIT(0),  
        HAPTICS_TRIGGER_FALLING = BIT(1), 
        HAPTICS_TRIGGER_HIGH = BIT(2),    
        HAPTICS_TRIGGER_LOW = BIT(3),     
 
        /* Device-specific GPIO trigger options can follow, refer to the device’s header file */
        HAPTICS_TRIGGER_PRIV_START = BIT(4),
};

union haptics_config {
        uint32_t idx; 
        struct {
                audio_dai_type_t type; 
                audio_dai_cfg_t cfg;   
        } dai; 
};

typedef void (*haptics_error_callback_t)(const struct device *dev, const uint32_t errors,
                                         void *const user_data);


typedef int (*haptics_calibrate_t)(const struct device *dev, const uint32_t routine);

typedef int (*haptics_monitor_get_t)(const struct device *dev, const enum haptics_monitor monitor,
                                     const enum haptics_monitor_type type,
                                     struct sensor_value *const val);

typedef int (*haptics_monitor_set_t)(const struct device *dev, const enum haptics_monitor monitor,
                                     const bool enable);

typedef int (*haptics_register_error_callback_t)(const struct device *dev,
                                                 haptics_error_callback_t cb,
                                                 void *const user_data);

typedef int (*haptics_select_source_t)(const struct device *dev, const enum haptics_source src,
                                       const union haptics_config *const cfg);

typedef int (*haptics_set_level_t)(const struct device *dev, const enum haptics_source src,
                                   const union haptics_config *const cfg, const uint32_t level);

typedef int (*haptics_set_trigger_t)(const struct device *dev, const uint32_t trigger,
                                     const uint32_t types, const enum haptics_source src,
                                     const union haptics_config *const cfg, const uint32_t level);

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

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

typedef int (*haptics_stream_samples_t)(const struct device *dev, const uint8_t *const samples,
                                        const size_t len);

typedef int (*haptics_trigger_t)(const struct device *dev, const uint32_t trigger,
                                 const enum haptics_trigger_type type);

__subsystem struct haptics_driver_api {
        haptics_calibrate_t calibrate;
        haptics_monitor_get_t monitor_get;
        haptics_monitor_set_t monitor_set;
        haptics_register_error_callback_t register_error_callback;
        haptics_select_source_t select_source;
        haptics_set_level_t set_level;
        haptics_set_trigger_t set_trigger;
        haptics_start_output_t start_output;
        haptics_stop_output_t stop_output;
        haptics_stream_samples_t stream_samples;
        haptics_trigger_t trigger;
};


__syscall int haptics_calibrate(const struct device *dev, const uint32_t routine);
 
static inline int z_impl_haptics_calibrate(const struct device *dev, const uint32_t routine)
{
        const struct haptics_driver_api *api = DEVICE_API_GET(haptics, dev);
 
        if (api->calibrate == NULL) {
                return -ENOSYS;
        }
 
        return api->calibrate(dev, routine);
}

__syscall int haptics_monitor_get(const struct device *dev, const enum haptics_monitor monitor,
                                  const enum haptics_monitor_type type,
                                  struct sensor_value *const val);
 
static inline int z_impl_haptics_monitor_get(const struct device *dev,
                                             const enum haptics_monitor monitor,
                                             const enum haptics_monitor_type type,
                                             struct sensor_value *const val)
{
        const struct haptics_driver_api *api = DEVICE_API_GET(haptics, dev);
 
        if (api->monitor_get == NULL) {
                return -ENOSYS;
        }
 
        __ASSERT_NO_MSG(monitor != HAPTICS_MONITOR_ALL);
        __ASSERT_NO_MSG(val != NULL);
 
        return api->monitor_get(dev, monitor, type, val);
}

__syscall int haptics_monitor_set(const struct device *dev, const enum haptics_monitor monitor,
                                  const bool enable);
 
static inline int z_impl_haptics_monitor_set(const struct device *dev,
                                             const enum haptics_monitor monitor, const bool enable)
{
        const struct haptics_driver_api *api = DEVICE_API_GET(haptics, dev);
 
        if (api->monitor_set == NULL) {
                return -ENOSYS;
        }
 
        return api->monitor_set(dev, monitor, enable);
}

static inline int haptics_register_error_callback(const struct device *dev,
                                                  haptics_error_callback_t cb,
                                                  void *const user_data)
{
        const struct haptics_driver_api *api = DEVICE_API_GET(haptics, dev);
 
        if (api->register_error_callback == NULL) {
                return -ENOSYS;
        }
 
        __ASSERT_NO_MSG(cb != NULL);
 
        return api->register_error_callback(dev, cb, user_data);
}

__syscall int haptics_select_source(const struct device *dev, const enum haptics_source src,
                                    const union haptics_config *const cfg);
 
static inline int z_impl_haptics_select_source(const struct device *dev,
                                               const enum haptics_source src,
                                               const union haptics_config *const cfg)
{
        const struct haptics_driver_api *api = DEVICE_API_GET(haptics, dev);
 
        __ASSERT_NO_MSG(api->select_source != NULL);
 
        return api->select_source(dev, src, cfg);
}

__syscall int haptics_set_level(const struct device *dev, const enum haptics_source src,
                                const union haptics_config *const cfg, const uint32_t level);
 
static inline int z_impl_haptics_set_level(const struct device *dev, const enum haptics_source src,
                                           const union haptics_config *const cfg,
                                           const uint32_t level)
{
        const struct haptics_driver_api *api = DEVICE_API_GET(haptics, dev);
 
        if (api->set_level == NULL) {
                return -ENOSYS;
        }
 
        return api->set_level(dev, src, cfg, level);
}

__syscall int haptics_set_trigger(const struct device *dev, const uint32_t trigger,
                                  const uint32_t types, const enum haptics_source src,
                                  const union haptics_config *const cfg, const uint32_t level);
 
static inline int z_impl_haptics_set_trigger(const struct device *dev, const uint32_t trigger,
                                             const uint32_t types, const enum haptics_source src,
                                             const union haptics_config *const cfg,
                                             const uint32_t level)
{
        const struct haptics_driver_api *api = DEVICE_API_GET(haptics, dev);
 
        if (api->set_trigger == NULL) {
                return -ENOSYS;
        }
 
        return api->set_trigger(dev, trigger, types, src, cfg, level);
}

__syscall int haptics_start_output(const struct device *dev);
 
static inline int z_impl_haptics_start_output(const struct device *dev)
{
        const struct haptics_driver_api *api = DEVICE_API_GET(haptics, dev);
 
        __ASSERT_NO_MSG(api->start_output != NULL);
 
        return api->start_output(dev);
}

__syscall int haptics_stop_output(const struct device *dev);
 
static inline int z_impl_haptics_stop_output(const struct device *dev)
{
        const struct haptics_driver_api *api = DEVICE_API_GET(haptics, dev);
 
        __ASSERT_NO_MSG(api->stop_output != NULL);
 
        return api->stop_output(dev);
}

__syscall int haptics_stream_samples(const struct device *dev, const uint8_t *const samples,
                                     const size_t len);
 
static inline int z_impl_haptics_stream_samples(const struct device *dev,
                                                const uint8_t *const samples, const size_t len)
{
        const struct haptics_driver_api *api = DEVICE_API_GET(haptics, dev);
 
        if (api->stream_samples == NULL) {
                return -ENOSYS;
        }
 
        __ASSERT_NO_MSG(samples != NULL);
 
        return api->stream_samples(dev, samples, len);
}

__syscall int haptics_trigger(const struct device *dev, const uint32_t trigger,
                              const enum haptics_trigger_type type);
 
static inline int z_impl_haptics_trigger(const struct device *dev, const uint32_t trigger,
                                         const enum haptics_trigger_type type)
{
        const struct haptics_driver_api *api = DEVICE_API_GET(haptics, dev);
 
        if (api->trigger == NULL) {
                return -ENOSYS;
        }
 
        return api->trigger(dev, trigger, type);
}

 
#ifdef __cplusplus
}
#endif /* __cplusplus */
 
#include <zephyr/syscalls/haptics.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_HAPTICS_H_ */