cs40l5x.h

Go to the documentation of this file.

/*
 * Copyright (c) 2025 Cirrus Logic, Inc.
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_DRIVERS_HAPTICS_CS40L5X_H_
#define ZEPHYR_INCLUDE_DRIVERS_HAPTICS_CS40L5X_H_
 
#include <zephyr/drivers/gpio.h>
#include <zephyr/drivers/i2c.h>
#include <zephyr/drivers/spi.h>
#include <zephyr/drivers/haptics.h>
#include <zephyr/kernel.h>
#include <zephyr/logging/log_instance.h>
#include <sys/types.h>
 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */


enum cs40l5x_attenuation {
        CS40L5X_ATTENUATION_7DB = -7, 
        CS40L5X_ATTENUATION_6DB,      
        CS40L5X_ATTENUATION_5DB,      
        CS40L5X_ATTENUATION_4DB,      
        CS40L5X_ATTENUATION_3DB,      
        CS40L5X_ATTENUATION_2DB,      
        CS40L5X_ATTENUATION_1DB,      
        CS40L5X_ATTENUATION_0DB,      
};

enum cs40l5x_bank {
        CS40L5X_ROM_BANK,    
        CS40L5X_CUSTOM_BANK, 
        CS40L5X_BUZ_BANK,    
        CS40L5X_NO_BANK,     
};

struct cs40l5x_calibration {
        uint32_t redc;
        uint32_t f0;
};

enum cs40l5x_custom_index {
        CS40L5X_CUSTOM_0,           
        CS40L5X_CUSTOM_1,           
        CS40L5X_NUM_CUSTOM_EFFECTS, 
};

enum cs40l5x_error_type {
        CS40L5X_ERROR_AMPLIFIER_SHORT = BIT(0),      
        CS40L5X_ERROR_OVERTEMPERATURE = BIT(1),      
        CS40L5X_ERROR_UNDERVOLTAGE = BIT(2),         
        CS40L5X_ERROR_INDUCTOR_SHORT = BIT(3),       
        CS40L5X_ERROR_OVERCURRENT = BIT(4),          
        CS40L5X_ERROR_BATTERY_UNDERVOLTAGE = BIT(4), 
};

enum cs40l5x_logger {
        CS40L5X_LOGGER_DISABLE,   
        CS40L5X_LOGGER_ENABLE,    
        CS40L5X_LOGGER_NO_CHANGE, 
};

enum cs40l5x_logger_source {
        CS40L5X_LOGGER_BEMF, 
        CS40L5X_LOGGER_VBST, 
        CS40L5X_LOGGER_VMON, 
};

enum cs40l5x_logger_source_type {
        CS40L5X_LOGGER_MIN,  
        CS40L5X_LOGGER_MAX,  
        CS40L5X_LOGGER_MEAN, 
};

struct cs40l5x_pwle_section {
        uint16_t duration;
        uint16_t frequency;
        uint16_t level;
        uint8_t flags;
};

enum cs40l5x_trigger_edge {
        CS40L5X_RISING_EDGE,  
        CS40L5X_FALLING_EDGE, 
};

struct cs40l5x_trigger_config {
        enum cs40l5x_bank bank;
        uint8_t index;
        int attenuation;
        uint8_t address;
};

struct cs40l5x_trigger_gpios {
        struct gpio_dt_spec *gpio;
        const uint8_t num_gpio;
        struct cs40l5x_trigger_config *rising_edge;
        struct cs40l5x_trigger_config *falling_edge;
        bool *ready;
};

typedef struct device *(*cs40l5x_io_bus_get_device)(const struct device *const dev);

typedef bool (*cs40l5x_io_bus_is_ready)(const struct device *const dev);

typedef int (*cs40l5x_io_bus_read)(const struct device *const dev, const uint32_t addr,
                                   uint32_t *const rx, const uint32_t len);

typedef int (*cs40l5x_io_bus_write)(const struct device *const dev, uint32_t *const tx,
                                    const uint32_t len);

struct cs40l5x_bus_io {
        cs40l5x_io_bus_get_device get_device;
        cs40l5x_io_bus_is_ready is_ready;
        cs40l5x_io_bus_read read;
        cs40l5x_io_bus_write write;
};
 
#if CONFIG_HAPTICS_CS40L5X_I2C
extern const struct cs40l5x_bus_io cs40l5x_bus_io_i2c;
#endif /* CONFIG_HAPTICS_CS40L5X_I2C */
 
#if CONFIG_HAPTICS_CS40L5X_SPI
extern const struct cs40l5x_bus_io cs40l5x_bus_io_spi;
#endif /* CONFIG_HAPTICS_CS40L5X_SPI */

struct cs40l5x_bus {
#if CONFIG_HAPTICS_CS40L5X_I2C
        struct i2c_dt_spec i2c;
#endif /* CONFIG_HAPTICS_CS40L5X_I2C */
#if CONFIG_HAPTICS_CS40L5X_SPI
        struct spi_dt_spec spi;
#endif /* CONFIG_HAPTICS_CS40L5X_SPI */
};

struct cs40l5x_config {
        const struct device *const dev;
        struct cs40l5x_data *const data;
        LOG_INSTANCE_PTR_DECLARE(log);
        const struct cs40l5x_bus bus;
        const struct cs40l5x_bus_io *const bus_io;
        struct gpio_dt_spec reset_gpio;
        struct gpio_dt_spec interrupt_gpio;
        struct cs40l5x_trigger_gpios trigger_gpios;
        const struct device *flash;
        const off_t flash_offset;
        const struct device *const external_boost;
};

struct cs40l5x_data {
        const struct device *const dev;
        const struct cs40l5x_config *const config;
        struct k_mutex lock;
        uint32_t dev_id;
        uint8_t rev_id;
        struct gpio_callback interrupt_callback;
        struct k_work_delayable interrupt_worker;
        struct gpio_callback trigger_callback;
        void (*error_callback)(const struct device *const haptic_dev, const uint32_t errors);
        struct k_sem calibration_semaphore;
        struct cs40l5x_calibration calibration;
        uint32_t output;
        struct ring_buf rb_mailbox_history;
        struct ring_buf rb_trigger_history;
        uint8_t buf_mailbox_history[CONFIG_HAPTICS_CS40L5X_METADATA_CACHE_LEN];
        uint8_t buf_trigger_history[CONFIG_HAPTICS_CS40L5X_METADATA_CACHE_LEN];
        bool custom_effects[CS40L5X_NUM_CUSTOM_EFFECTS];
        int effects_in_flight;
};

int cs40l5x_calibrate(const struct device *const dev);

int cs40l5x_configure_buzz(const struct device *const dev, const uint32_t frequency,
                           const uint8_t level, const uint32_t duration);

int cs40l5x_configure_trigger(const struct device *const dev, const struct gpio_dt_spec *const gpio,
                              const enum cs40l5x_bank bank, const uint8_t index,
                              const enum cs40l5x_attenuation attenuation,
                              const enum cs40l5x_trigger_edge edge);

int cs40l5x_logger(const struct device *const dev, enum cs40l5x_logger logger_state);

int cs40l5x_logger_get(const struct device *const dev, enum cs40l5x_logger_source source,
                       enum cs40l5x_logger_source_type type, uint32_t *const value);

void cs40l5x_register_error_callback(const struct device *dev,
                                     void (*error_callback)(const struct device *const haptic_dev,
                                                            const uint32_t errors));

int cs40l5x_select_output(const struct device *const dev, const enum cs40l5x_bank bank,
                          const uint8_t index);

int cs40l5x_set_gain(const struct device *const dev, const uint8_t gain);

int cs40l5x_upload_pcm(const struct device *const dev, const enum cs40l5x_custom_index index,
                       const uint16_t redc, const uint16_t f0, const int8_t *const samples,
                       const uint16_t num_samples);

int cs40l5x_upload_pwle(const struct device *const dev, const enum cs40l5x_custom_index index,
                        const struct cs40l5x_pwle_section *const sections,
                        const uint8_t num_sections);

 
#ifdef __cplusplus
}
#endif /* __cplusplus */
 
#endif