soniclib.h

Go to the documentation of this file.

 
/*
 Copyright 2016-2023, InvenSense, Inc.  All rights reserved.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED.
 
 */
 
#ifndef __SONICLIB_H_
#define __SONICLIB_H_
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*==============  SonicLib Version Info ===================*/
/* SonicLib API/Driver version */
#define SONICLIB_VER_MAJOR  (4) 
#define SONICLIB_VER_MINOR  (9) 
#define SONICLIB_VER_REV    (0) 
#define SONICLIB_VER_SUFFIX ""  
/***** DO NOT MODIFY ANY VALUES BEYOND THIS POINT! *****/
 
#ifdef INVN_SONICLIB_INTERNAL_BOARD_CONFIG
#include <invn/soniclib/details/chirp_board_config.h> /* Header from board support package containing h/w params */
#else
// Support external board config by default. This was previously assumed to be
// directly on the include path.
#include "chirp_board_config.h"
#endif
 
/* Preliminary structure type definitions to resolve include order */
typedef struct ch_dev_t ch_dev_t;
typedef struct ch_group_t ch_group_t;
typedef struct fw_info_st fw_info_t;
 
/* ICU (second generation) Firmware  */
#ifdef INCLUDE_SHASTA_SUPPORT
#include <invn/icu_interface/shasta_external_regs.h> /* Shasta firmware interface */
#include <invn/soniclib/details/icu.h>
#include <invn/icu_interface/icu_algo_info.h> /* ICU sensor algorithm interface */
#endif
 
/* Miscellaneous header files */
 
#include <invn/soniclib/details/ch_driver.h>     /* Internal Chirp driver defines */
#include <invn/soniclib/details/ch_math_utils.h> /* math utility functions */
 
#include <stdint.h>
#include <stdlib.h>
#include <math.h>
#include <string.h>
 
/* Chirp sensor part numbers */
#define CH101_PART_NUMBER       (101)   
#define CH201_PART_NUMBER       (201)   
#define ICU10201_PART_NUMBER    (10201) 
#define ICU20201_PART_NUMBER    (20201) 
#define ICU30201_PART_NUMBER    (30201) 
#define ICU_UNKNOWN_PART_NUMBER (0)     
/* Max expected number of samples per measurement (actual value depends on sensor f/w used) */
#ifdef INCLUDE_WHITNEY_SUPPORT
 
#define CH101_MAX_NUM_SAMPLES (225) 
#define CH201_MAX_NUM_SAMPLES (450) 
#define MAX_NUM_SAMPLES       CH201_MAX_NUM_SAMPLES
 
#endif
#ifdef INCLUDE_SHASTA_SUPPORT
 
#define ICU_MAX_NUM_SAMPLES (IQ_SAMPLES_MAX) 
#define MAX_NUM_SAMPLES     ICU_MAX_NUM_SAMPLES
 
#endif
 
/* Misc definitions */
#define CH_NO_TARGET     (0xFFFFFFFF) 
#define CH_MIN_RANGE_VAL (0x0001)     
#define CH_DEFAULT_MEAS_NUM   (0) 
#define CH_DEFAULT_TARGET_NUM (0) 
#define CH_I2C_ADDR_PROG (0x45) 
#define CH_SIG_BYTE_0    (0x0a) 
#define CH_SIG_BYTE_1    (0x02) 
#define CH_RTC_FREQ_TYPICAL     (29000) 
#define CH_PMUT_TICKS_PER_CYCLE (16)    
#define CH_OP_FREQ_USE_AVG (0) 
#ifdef MAXTARG
#define CH_MAX_NUM_TARGETS (MAXTARG) 
#else
#define CH_MAX_NUM_TARGETS (1) 
#endif
 
#define CH_SPEEDOFSOUND_MPS (343) 
#define CH_WINDOW_MAX_SAMPLES (64) 
typedef enum { RET_OK = 0, RET_ERR = 1 } ch_retval;
 
typedef enum {
    CH_PROD_CODE_ICU20201 = 1,    
    CH_PROD_CODE_ICU10201 = 2,    
    CH_PROD_CODE_ICU30201 = 3,    
    CH_PROD_CODE_UNKNOWN  = 0xFF, 
} ch_prod_code_t;
 
typedef enum {
    CH_ASIC_GEN_1_WHITNEY = 1, 
    CH_ASIC_GEN_2_SHASTA  = 2, 
} ch_asic_gen_t;
 
typedef enum {
    CH_RANGE_ECHO_ONE_WAY    = 0, 
    CH_RANGE_ECHO_ROUND_TRIP = 1, 
    CH_RANGE_DIRECT          = 2, 
} ch_range_t;
 
typedef enum {
    CH_MODE_IDLE    = 0x00,           
    CH_MODE_FREERUN = 0x02,           
    CH_MODE_TRIGGERED_TX_RX = 0x10,   
    CH_MODE_TRIGGERED_RX_ONLY = 0x20, 
 
    CH_MODE_CONTINUOUS_RX = 0x40
} ch_mode_t;
 
typedef enum ch_group_status {
    CH_GROUP_STAT_NOT_INIT     = 0, 
    CH_GROUP_STAT_INIT_PENDING = 1, 
    CH_GROUP_STAT_INIT_OK      = 2  
} ch_group_status_t;
 
typedef enum {
    CH_MEAS_STATUS_UNKNOWN = 0, 
    CH_MEAS_STATUS_INIT    = 1, 
    CH_MEAS_STATUS_TX_OPT  = 2, 
    CH_MEAS_STATUS_OK      = 3, 
    CH_MEAS_STATUS_PENDING = 4, 
    CH_MEAS_STATUS_DONE    = 5, 
} ch_meas_status_t;
 
typedef enum {
    CH_MEAS_MODE_ACTIVE  = 0, 
    CH_MEAS_MODE_STANDBY = 1  
} ch_meas_mode_t;
 
typedef enum {
    CH_RESET_HARD = 0, 
    CH_RESET_SOFT = 1  
} ch_reset_t;
 
typedef enum {
    CH_TRIGGER_TYPE_HW = 0, 
    CH_TRIGGER_TYPE_SW = 1  
} ch_trigger_type_t;
 
typedef enum {
    CH_INTERRUPT_MODE_PULSE = 0, 
    CH_INTERRUPT_MODE_LATCH = 1  
} ch_interrupt_mode_t;
 
typedef enum {
    CH_INTERRUPT_DRIVE_OPEN_DRAIN = 0, 
    CH_INTERRUPT_DRIVE_PUSH_PULL  = 1  
} ch_interrupt_drive_t;
 
#ifdef INCLUDE_SHASTA_SUPPORT
typedef enum {
    CH_INTERRUPT_TYPE_UNKNOWN     = INT_SRC_NONE,            
    CH_INTERRUPT_TYPE_DATA_RDY    = INT_SRC_DATA_RDY,        
    CH_INTERRUPT_TYPE_MUT_FCOUNT  = INT_SRC_MUT_FCOUNT_RDY,  
    CH_INTERRUPT_TYPE_CPU_FCOUNT  = INT_SRC_CPU_FCOUNT_RDY,  
    CH_INTERRUPT_TYPE_BIST_RDY    = INT_SRC_BIST_RDY,        
    CH_INTERRUPT_TYPE_TX_OPTIMIZE = INT_SRC_TX_OPTIMIZE,     
    CH_INTERRUPT_TYPE_RTC_CAL_RDY = INT_SRC_RTC_CAL_RDY,     
    CH_INTERRUPT_TYPE_OTP_COPY    = INT_SRC_COPY_OTP_TO_RAM, 
    CH_INTERRUPT_TYPE_OTP_WR_STEP = INT_SRC_OTP_WR_STEP,     
    CH_INTERRUPT_TYPE_WATCHDOG    = INT_SRC_WDT_EXPIRY,      
    CH_INTERRUPT_TYPE_PGM_LOADED  = INT_SRC_PGM_LOADED,      
    CH_INTERRUPT_TYPE_ALGO_ERROR  = INT_SRC_ALGO_ERROR,      
    CH_INTERRUPT_TYPE_DEBUG       = INT_SRC_DEBUG,           
    CH_INTERRUPT_TYPE_ERROR       = INT_SRC_ERROR            
} ch_interrupt_type_t;
 
typedef enum {
    CH_OUTPUT_IQ         = IQ_OUTPUT_NORMAL,     
    CH_OUTPUT_AMP_THRESH = IQ_OUTPUT_MAG_THRESH, 
    CH_OUTPUT_AMP        = IQ_OUTPUT_MAG         
} ch_output_type_t;
#else
typedef enum {
    CH_INTERRUPT_TYPE_UNKNOWN  = 0x0000,
    CH_INTERRUPT_TYPE_DATA_RDY = 0x0001,
} ch_interrupt_type_t;
 
typedef enum {
    CH_OUTPUT_IQ  = 0, 
    CH_OUTPUT_AMP = 2  
} ch_output_type_t;
#endif
 
typedef enum {
    CH_TGT_INT_FILTER_OFF     = 0, 
    CH_TGT_INT_FILTER_ANY     = 1, 
    CH_TGT_INT_FILTER_COUNTER = 4, 
} ch_tgt_int_filter_t;
 
#define CH_TARGET_INT_HIST_MAX       (15) 
#define CH_TARGET_INT_HIST_DEFAULT   (5)  
#define CH_TARGET_INT_THRESH_DEFAULT (3)  
typedef enum {
    CH_ODR_FREQ_DIV_32 = 2,                
    CH_ODR_FREQ_DIV_16 = 3,                
    CH_ODR_FREQ_DIV_8  = 4,                
    CH_ODR_FREQ_DIV_4  = 5,                
    CH_ODR_FREQ_DIV_2  = 6,                
    CH_ODR_DEFAULT     = CH_ODR_FREQ_DIV_8 
} ch_odr_t;
 
typedef enum {
    CH_RTC_SRC_INTERNAL = 0, 
    CH_RTC_SRC_EXTERNAL = 1  
} ch_rtc_src_t;
 
typedef enum {
    CH_RTC_STATUS_INIT          = 0, 
    CH_RTC_STATUS_CAL_DONE      = 1, 
    CH_RTC_STATUS_CAL_FACTORY   = 2, 
    CH_RTC_STATUS_CAL_ESTIMATED = 3, 
    CH_RTC_STATUS_CAL_BUS       = 4, 
    CH_RTC_STATUS_EXTERNAL      = 5, 
} ch_rtc_status_t;
 
#define CH_RTC_USE_BUS_SPEED (UINT16_MAX) 
typedef enum {
    CH_RTC_CAL_STD    = 0, 
    CH_RTC_CAL_MANUAL = 1, 
    CH_RTC_CAL_BUS    = 2, 
} ch_rtc_cal_t;
 
typedef enum {
    CH_PMUT_CLK_DEFAULT = 0, 
    CH_PMUT_CLK_OUTPUT_ENABLE =
            1, 
    CH_PMUT_CLK_SRC_EXTERNAL = 2, 
    CH_PMUT_CLK_OUTPUT_AUTO =
            3, 
} ch_pmut_clk_cfg_t;
 
typedef enum {
    CH_IO_MODE_BLOCK    = 0, 
    CH_IO_MODE_NONBLOCK = 1  
} ch_io_mode_t;
 
typedef enum {
    CH_DECIMATION_0_25 = -2,
    CH_DECIMATION_0_50 = -1,
    CH_DECIMATION_NONE = 1,
    CH_DECIMATION_2    = 2,
    CH_DECIMATION_3    = 3,
    CH_DECIMATION_4    = 4
} ch_decimation_t;
 
typedef enum { CH_RESET_STATE_OK = 0, CH_RESET_STATE_ACTIVE = 1 } ch_sensor_reset_state_t;
 
typedef enum { CH_LOG_FMT_REDSWALLOW = 0 } ch_log_fmt_t;
 
typedef enum {
    CH_DATA_VALIDATION_DISABLE = 0,
    CH_DATA_VALIDATION_COUNTER = 1,
    CH_DATA_VALIDATION_PRNG    = 2,
} ch_data_validation_mode_t;
 
typedef struct {
    uint8_t major; 
    uint8_t minor; 
    uint8_t rev;   
} ch_version_t;
 
typedef struct {
    uint8_t address;    
    uint8_t bus_num;    
    uint16_t drv_flags; 
} ch_i2c_info_t;
 
#define I2C_DRV_FLAG_RESET_AFTER_NB (0x00000001) 
#define I2C_DRV_FLAG_USE_PROG_NB    (0x00000002) 
typedef struct {
    int16_t q; 
    int16_t i; 
} ch_iq_sample_t;
 
typedef struct {
    uint16_t thresh; 
    uint16_t amp;    
} ch_amp_thresh_t;
 
typedef struct {
    uint16_t start_sample;
    uint16_t level;
} ch_thresh_t;
 
typedef struct {
    uint16_t dco_period;
    uint16_t rev_cycles;
} ch_cal_result_t;
 
typedef struct {
    uint16_t rtc_freq;    
    uint16_t pmut_fcount; 
    uint16_t pmut_trim;   
    uint8_t cpu_trim;     
} ch_clock_cal_t;
 
typedef struct {
    ch_mode_t mode;                     
    uint16_t max_range;                 
    uint16_t sample_interval;           
    ch_tgt_int_filter_t tgt_int_filter; 
} ch_config_t;
 
typedef struct {
    ch_output_type_t output_type;      
    ch_decimation_t decimation_factor; 
} ch_output_t;
 
typedef struct {
    uint16_t interval_ms;              
    ch_output_type_t output_type;      
    ch_decimation_t decimation_factor; 
    uint16_t start_sample;             
} ch_log_cfg_t;
 
typedef struct {
    uint8_t tx_sensor_id;         
    uint8_t rx_sensor_id;         
    uint32_t range;               
    uint16_t amplitude;           
    uint8_t annotation;           
    ch_output_type_t output_type; 
    union {
        ch_iq_sample_t *iq_sample_ptr; 
        uint16_t *mag_data_ptr;        
    } raw_data;
    uint16_t start_sample; 
    uint16_t num_samples;  
} ch_log_data_t;
 
typedef struct {
    ch_odr_t odr;
    uint16_t meas_period;
    ch_meas_mode_t mode;  // 1 if meas initially in standby mode (inactive), 0 if active
} ch_meas_config_t;
 
#ifdef INCLUDE_SHASTA_SUPPORT
/* Definitions for ICU-x0201 sensors (Shasta architecture) */
 
#define CH_MEAS_MAX_SEGMENTS (INST_BUF_LENGTH)     
#define CH_MEAS_MAX_MEAS     (MEAS_QUEUE_MAX_MEAS) 
#define CH_SENSOR_ID_LENGTH 8 
typedef enum {
    CH_MEAS_SEG_TYPE_COUNT = 0,  // must match PMUT cmd values
    CH_MEAS_SEG_TYPE_TX    = 1,
    CH_MEAS_SEG_TYPE_RX    = 2,
    CH_MEAS_SEG_TYPE_EOF   = 3
} ch_meas_seg_type_t;
 
typedef struct {
    pmut_transceiver_inst_t inst;  // PMUT instruction
 
} ch_meas_segment_t;
 
typedef struct {
    uint32_t num_cycles;
    uint16_t num_tx_segments;
    uint16_t num_rx_samples;
    uint8_t num_segments; 
    ch_odr_t odr;
    uint16_t meas_period; 
    ch_meas_mode_t mode;  
} ch_meas_info_t;
 
typedef struct {
    ch_meas_seg_type_t type;
    uint16_t num_rx_samples;
    uint16_t num_cycles;
    uint8_t rdy_int_en;
    uint8_t done_int_en;
    uint8_t tx_phase;
    uint8_t tx_pulse_width;
    uint8_t rx_gain;
    uint8_t rx_atten;
} ch_meas_seg_info_t;
 
typedef struct {
    uint8_t int_config;    // interrupt pin selection
    uint8_t meas_start;    // which measurement do we start on
    uint8_t meas_stop;     // which measurement do we stop on
    uint8_t current_meas;  // which measurement do we do next
    uint8_t trig_src;      // trigger source: falling edge of INT1 or INT2, or internal timer
    uint8_t last_meas;     // last completed measurement
} ch_meas_queue_info_t;
 
typedef struct {
    uint16_t mfg_year;
    uint8_t mfg_week;
    uint8_t mfg_site;
    uint8_t product_code;  // numeric value for product type (e.g. ICU-20201, ICU-10201, etc)
    uint8_t package_code;  // numeric value for package type (e.g. added microcap, changed bondwires)
    uint8_t mems_code;     // numeric value for mems transducer type (e.g. CH101/201/CypressZ1/A1)
    uint8_t module_code;   // numeric value for module type
} ch_mfg_info_t;
 
#endif  // INCLUDE_SHASTA_SUPPORT
 
typedef uint8_t (*ch_get_config_func_t)(ch_dev_t *dev_ptr, ch_config_t *config_ptr);
typedef uint8_t (*ch_set_config_func_t)(ch_dev_t *dev_ptr, ch_config_t *config_ptr);
typedef uint8_t (*ch_set_num_samples_func_t)(ch_dev_t *dev_ptr, uint16_t num_samples);
typedef uint8_t (*ch_set_sample_window_func_t)(ch_dev_t *dev_ptr, uint16_t start_sample, uint16_t end_sample);
typedef uint32_t (*ch_get_range_func_t)(ch_dev_t *dev_ptr, ch_range_t range_type);
typedef uint16_t (*ch_get_amplitude_func_t)(ch_dev_t *dev_ptr);
typedef uint16_t (*ch_get_amplitude_avg_func_t)(ch_dev_t *dev_ptr);
typedef uint8_t (*ch_set_frequency_func_t)(ch_dev_t *dev_ptr, uint32_t target_freq_Hz);
typedef uint8_t (*ch_get_iq_data_func_t)(ch_dev_t *dev_ptr, ch_iq_sample_t *buf_ptr, uint16_t start_sample,
                                         uint16_t num_samples, ch_io_mode_t io_mode);
typedef uint8_t (*ch_get_amplitude_data_func_t)(ch_dev_t *dev_ptr, uint16_t *buf_ptr, uint16_t start_sample,
                                                uint16_t num_samples, ch_io_mode_t io_mode);
typedef uint16_t (*ch_mm_to_samples_func_t)(ch_dev_t *dev_ptr, uint16_t num_mm);
typedef uint8_t (*ch_set_target_interrupt_func_t)(ch_dev_t *dev_ptr, ch_tgt_int_filter_t tgt_int_filter);
typedef ch_tgt_int_filter_t (*ch_get_target_interrupt_func_t)(ch_dev_t *dev_ptr);
typedef uint8_t (*ch_set_target_int_counter_func_t)(ch_dev_t *dev_ptr, uint8_t meas_hist, uint8_t thresh_count,
                                                    uint8_t reset);
typedef uint8_t (*ch_get_target_int_counter_func_t)(ch_dev_t *dev_ptr, uint8_t *meas_hist_ptr,
                                                    uint8_t *thresh_count_ptr, uint8_t *reset_ptr);
typedef uint8_t (*ch_set_rx_low_gain_func_t)(ch_dev_t *dev_ptr, uint16_t num_samples);
typedef uint16_t (*ch_get_rx_low_gain_func_t)(ch_dev_t *dev_ptr);
typedef uint8_t (*ch_set_tx_length_func_t)(ch_dev_t *dev_ptr, uint16_t tx_length);
typedef uint16_t (*ch_get_tx_length_func_t)(ch_dev_t *dev_ptr);
typedef uint8_t (*ch_set_cal_result_func_t)(ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr);
typedef uint8_t (*ch_get_cal_result_func_t)(ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr);
typedef uint8_t (*ch_set_data_output_func_t)(ch_dev_t *dev_ptr, const ch_output_t *output);
typedef void (*ch_trigger_soft_func_t)(ch_dev_t *dev_ptr);
typedef uint8_t (*ch_set_data_ready_delay_func_t)(ch_dev_t *dev_ptr, uint8_t num_cycles);
typedef uint8_t (*ch_get_data_ready_delay_func_t)(ch_dev_t *dev_ptr);
typedef ch_meas_status_t (*ch_meas_get_status_func_t)(ch_dev_t *dev_ptr, uint8_t meas_num);
 
#ifdef INCLUDE_SHASTA_SUPPORT
typedef ch_output_type_t (*ch_meas_get_iq_output_func_t)(ch_dev_t *dev_ptr, uint8_t meas_num);
typedef uint8_t (*ch_meas_set_iq_output_func_t)(ch_dev_t *dev_ptr, uint8_t meas_num, ch_output_type_t output_format);
#endif
 
typedef struct {
    ch_set_num_samples_func_t set_num_samples;
    ch_set_sample_window_func_t set_sample_window;
    ch_get_range_func_t get_range;
    ch_get_amplitude_func_t get_amplitude;
    ch_get_amplitude_avg_func_t get_amplitude_avg;
    ch_set_frequency_func_t set_frequency;
    ch_get_iq_data_func_t get_iq_data;
    ch_get_amplitude_data_func_t get_amplitude_data;
    ch_mm_to_samples_func_t mm_to_samples;
    ch_set_target_interrupt_func_t set_target_interrupt;
    ch_get_target_interrupt_func_t get_target_interrupt;
    ch_set_target_int_counter_func_t set_target_int_counter;
    ch_get_target_int_counter_func_t get_target_int_counter;
    ch_set_rx_low_gain_func_t set_rx_low_gain;
    ch_get_rx_low_gain_func_t get_rx_low_gain;
    ch_set_tx_length_func_t set_tx_length;
    ch_get_tx_length_func_t get_tx_length;
    ch_set_cal_result_func_t set_cal_result;
    ch_get_cal_result_func_t get_cal_result;
    ch_set_data_output_func_t set_data_output;
    ch_trigger_soft_func_t trigger_soft;
    ch_set_data_ready_delay_func_t set_data_ready_delay;
    ch_get_data_ready_delay_func_t get_data_ready_delay;
    ch_meas_get_status_func_t meas_get_status;
#ifdef INCLUDE_SHASTA_SUPPORT
    ch_meas_get_iq_output_func_t meas_get_iq_output;
    ch_meas_set_iq_output_func_t meas_set_iq_output;
#endif
    // Range finding specific
    const void *algo_specific_api;
} ch_api_funcs_t;
 
typedef struct {
    void (*prepare_pulse_timer)(ch_dev_t *dev_ptr); 
    void (*store_pt_result)(ch_dev_t *dev_ptr);     
    void (*store_op_freq)(ch_dev_t *dev_ptr);       
    void (*store_bandwidth)(ch_dev_t *dev_ptr);     
    void (*store_scalefactor)(ch_dev_t *dev_ptr);   
    uint8_t (*get_locked_state)(ch_dev_t *dev_ptr); 
} ch_calib_funcs_t;
 
struct fw_info_st {
    /* Sensor Firmware-specific Linkage Definitions */
    const char *fw_version_string;          
    const uint8_t *fw_text;                 
    const uint8_t *fw_vec;                  
    const uint8_t *ram_init;                
    uint16_t (*get_fw_ram_init_size)(void); 
    uint16_t (*get_fw_ram_init_addr)(void); 
    /* Functions used for sensor calibration */
    const ch_calib_funcs_t *const calib_funcs;
    /* API and callback functions */
    const ch_api_funcs_t *const api_funcs; 
    uint16_t fw_text_size;                 
    uint16_t fw_vec_size;                  
    uint16_t max_samples;             
    const uint16_t freqCounterCycles; 
    const uint8_t freqLockValue;      
    const int8_t oversample;          
    const uint8_t max_num_thresholds; 
    /* Sensor Firmware infos */
    const uint8_t fw_includes_sensor_init : 1;     
    const uint8_t fw_includes_tx_optimization : 1; 
    const uint8_t reserved : 6;
};
 
typedef uint8_t (*ch_fw_init_func_t)(ch_dev_t *dev_ptr, fw_info_t **fw_info);
 
typedef void (*ch_io_int_callback_t)(ch_group_t *grp_ptr, uint8_t io_index, ch_interrupt_type_t int_type);
 
typedef void (*ch_io_complete_callback_t)(ch_group_t *grp_ptr);
 
typedef void (*ch_timer_callback_t)(void);
 
 
struct ch_group_t {
    ch_group_status_t status;                       
    uint8_t num_ports;                              
    uint8_t sensor_int_pin;                         
    uint8_t sensor_trig_pin;                        
    uint8_t num_buses;                              
    uint8_t sensor_count;                           
    ch_rtc_cal_t rtc_cal_type;                      
    uint32_t op_frequency;                          
    uint32_t pmut_clock_freq;                       
    uint32_t io_bus_speed_hz;                       
    uint16_t i2c_drv_flags;                         
    uint16_t rtc_cal_pulse_ms;                      
    uint16_t pretrig_delay_us;                      
    ch_io_int_callback_t io_int_callback;           
    ch_io_complete_callback_t io_complete_callback; 
    ch_dev_t *device[CHIRP_MAX_NUM_SENSORS];        
#ifdef INCLUDE_WHITNEY_SUPPORT
    uint8_t num_connected[CHIRP_NUM_BUSES]; 
#endif
    chdrv_queue_t queue[CHIRP_NUM_BUSES]; 
};
 
struct ch_dev_t {
    ch_group_t *group; 
#ifdef INCLUDE_SHASTA_SUPPORT
    char id_string[CH_SENSOR_ID_LENGTH]; 
    shasta_config_t *sens_cfg_addr;      
#endif
    ch_asic_gen_t asic_gen;         
    ch_mode_t mode;                 
    uint16_t max_range;             
    uint16_t static_range;          
    uint32_t freerun_intvl_us;      
    ch_rtc_status_t rtc_status;     
    uint16_t rtc_cal_result;        
    ch_pmut_clk_cfg_t pmut_clk_cfg; 
    uint32_t orig_pmut_freq;        
    uint32_t op_frequency;          
    uint32_t cpu_frequency;         
    uint16_t rtc_frequency;         
#ifdef INCLUDE_SHASTA_SUPPORT
    uint16_t fcount_cycles;     
    uint16_t pmut_clock_fcount; 
    uint8_t cpu_trim;           
    uint16_t pmut_trim;         
#endif
    uint16_t bandwidth;        
    uint16_t amp_scale_factor; 
    uint16_t tof_scale_factor; 
#ifdef INCLUDE_WHITNEY_SUPPORT
    uint8_t i2c_address;     
    uint8_t app_i2c_address; 
    uint16_t i2c_drv_flags;  
#endif
    uint8_t bus_index;         
    uint16_t part_number;      
    uint8_t sensor_connected;  
    uint8_t io_index;          
    uint16_t num_rx_samples;   
    uint16_t win_start_sample; 
    uint16_t num_win_samples;  
    ch_meas_status_t meas_status;       
    ch_trigger_type_t trig_type;        
    ch_interrupt_mode_t int_mode;       
    ch_interrupt_drive_t int_drive;     
    ch_tgt_int_filter_t tgt_int_filter; 
    fw_info_t *main_fw_info;            
    fw_info_t *current_fw;              
#ifdef INCLUDE_SHASTA_SUPPORT
    fw_info_t *init_fw_info;       
    uint8_t main_fw_init_done;     
    uint8_t asic_ready;            
    ch_clock_cal_t test_clock_cal; 
    int16_t data_validation_counter; 
    int16_t mq_sanitize_enabled;     /* !< Perform mq sanitization step when non-zero */
 
    uint8_t reg_fmt_ver_major; 
    uint8_t reg_fmt_ver_minor; 
    /* Sensor measurement queue */
    measurement_queue_t meas_queue; 
    uint8_t meas_num_segments[CH_MEAS_MAX_MEAS];      // number of active segments per measurement
    uint32_t meas_num_cycles[CH_MEAS_MAX_MEAS];       // total number of sensor cycles per measurement
    uint16_t meas_num_tx_segments[CH_MEAS_MAX_MEAS];  // total number of transmit segments per measurement
    uint16_t meas_pre_rx_cycles[CH_MEAS_MAX_MEAS];    // total number of sensor cycles in segments before first read
    uint16_t meas_num_rx_samples[CH_MEAS_MAX_MEAS];   // total number of receive samples per measurement
    uint16_t meas_max_range_mm[CH_MEAS_MAX_MEAS];     // max range setting based on num_rx_samples (millimeters)
 
    uint8_t last_measurement; 
    uint8_t is_continuous;    
    uint8_t odr_out;          
    uint8_t iq_output_format; 
    uint16_t num_iq_bytes;    
    uint16_t buf_addr;        
    /* Sensor algorithm */
    ICU_ALGO_SHASTA_INFO *sens_algo_info_addr; 
    ICU_ALGO_SHASTA_INFO algo_info;            
    void *algo_cfg_ptr; 
#endif  // INCLUDE_SHASTA_SUPPORT
};
 
/*==============  API function prototypes and documentation ===================*/
 
uint8_t ch_group_init(ch_group_t *grp_ptr, uint8_t num_devices, uint8_t num_buses, uint16_t rtc_cal_pulse_ms);
 
uint8_t ch_init(ch_dev_t *dev_ptr, ch_group_t *grp_ptr, uint8_t dev_num, ch_fw_init_func_t fw_init_func);
 
uint8_t ch_set_init_firmware(ch_dev_t *dev_ptr, ch_fw_init_func_t fw_init_func);
 
uint8_t ch_group_start(ch_group_t *grp_ptr);
 
uint8_t ch_restart(ch_dev_t *dev_ptr);
 
uint8_t ch_group_restart(ch_group_t *grp_ptr);
 
uint8_t ch_get_config(ch_dev_t *dev_ptr, ch_config_t *config_ptr);
 
uint8_t ch_set_config(ch_dev_t *dev_ptr, ch_config_t *config_ptr);
 
void ch_trigger(ch_dev_t *dev_ptr);
 
void ch_group_trigger(ch_group_t *grp_ptr);
 
void ch_reset(ch_dev_t *dev_ptr, ch_reset_t reset_type);
 
void ch_group_reset(ch_group_t *grp_ptr, ch_reset_t reset_type);
 
uint8_t ch_sensor_is_connected(ch_dev_t *dev_ptr);
 
uint16_t ch_get_part_number(ch_dev_t *dev_ptr);
 
uint8_t ch_get_dev_num(ch_dev_t *dev_ptr);
 
ch_dev_t *ch_get_dev_ptr(ch_group_t *grp_ptr, uint8_t dev_num);
 
uint8_t ch_get_num_ports(ch_group_t *grp_ptr);
 
uint8_t ch_get_i2c_address(ch_dev_t *dev_ptr);
 
uint8_t ch_get_bus(ch_dev_t *dev_ptr);
 
void ch_get_version(ch_version_t *version_ptr);
 
const char *ch_get_fw_version_string(ch_dev_t *dev_ptr);
 
ch_mode_t ch_get_mode(ch_dev_t *dev_ptr);
 
uint8_t ch_set_mode(ch_dev_t *dev_ptr, ch_mode_t mode);
 
uint16_t ch_get_sample_interval(ch_dev_t *dev_ptr);
 
uint16_t ch_get_freerun_interval(ch_dev_t *dev_ptr);
 
uint32_t ch_get_freerun_interval_us(ch_dev_t *dev_ptr);
 
uint16_t ch_get_freerun_interval_ticks(ch_dev_t *dev_ptr);
 
uint8_t ch_set_sample_interval(ch_dev_t *dev_ptr, uint16_t interval_ms);
 
uint8_t ch_set_freerun_interval(ch_dev_t *dev_ptr, uint16_t interval_ms);
 
uint8_t ch_set_freerun_interval_us(ch_dev_t *dev_ptr, uint32_t interval_us);
 
uint8_t ch_set_freerun_interval_ticks(ch_dev_t *dev_ptr, uint32_t interval_ticks);
 
uint8_t ch_freerun_time_hop_enable(ch_dev_t *dev_ptr);
 
uint8_t ch_freerun_time_hop_disable(ch_dev_t *dev_ptr);
 
uint16_t ch_get_num_samples(ch_dev_t *dev_ptr);
 
uint8_t ch_set_num_samples(ch_dev_t *dev_ptr, uint16_t num_samples);
 
uint16_t ch_get_max_samples(ch_dev_t *dev_ptr);
 
uint16_t ch_get_max_range(ch_dev_t *dev_ptr);
 
uint8_t ch_set_max_range(ch_dev_t *dev_ptr, uint16_t max_range);
 
uint8_t ch_get_sample_window(ch_dev_t *dev_ptr, uint16_t *start_sample_ptr, uint16_t *num_samples_ptr);
 
uint8_t ch_set_sample_window(ch_dev_t *dev_ptr, uint16_t start_sample, uint16_t num_samples);
 
uint32_t ch_get_range(ch_dev_t *dev_ptr, ch_range_t range_type);
 
uint16_t ch_get_amplitude(ch_dev_t *dev_ptr);
 
uint16_t ch_get_amplitude_avg(ch_dev_t *dev_ptr);
 
uint16_t ch_get_bandwidth(ch_dev_t *dev_ptr);
 
uint8_t ch_set_frequency(ch_dev_t *dev_ptr, uint32_t request_op_freq_hz);
 
uint32_t ch_get_frequency(ch_dev_t *dev_ptr);
 
uint8_t ch_group_set_frequency(ch_group_t *grp_ptr, uint32_t request_op_freq_hz);
 
uint32_t ch_group_get_frequency(ch_group_t *grp_ptr);
 
uint16_t ch_get_rtc_cal_result(ch_dev_t *dev_ptr);
 
uint16_t ch_get_rtc_cal_pulselength(ch_dev_t *dev_ptr);
 
uint16_t ch_get_scale_factor(ch_dev_t *dev_ptr);
 
uint8_t ch_get_iq_data(ch_dev_t *dev_ptr, ch_iq_sample_t *buf_ptr, uint16_t start_sample, uint16_t num_samples,
                       ch_io_mode_t mode);
 
uint8_t ch_get_amplitude_data(ch_dev_t *dev_ptr, uint16_t *buf_ptr, uint16_t start_sample, uint16_t num_samples,
                              ch_io_mode_t mode);
 
uint8_t ch_get_amp_thresh_data(ch_dev_t *dev_ptr, ch_amp_thresh_t *buf_ptr, uint16_t start_sample, uint16_t num_samples,
                               ch_io_mode_t mode);
 
uint16_t ch_samples_to_mm(ch_dev_t *dev_ptr, uint16_t num_samples);
 
uint16_t ch_mm_to_samples(ch_dev_t *dev_ptr, uint16_t num_mm);
 
uint16_t ch_iq_to_amplitude(ch_iq_sample_t *iq_sample_ptr);
 
uint8_t ch_io_start_nb(ch_group_t *grp_ptr);
 
uint8_t ch_minimal_int_handler(ch_group_t *grp_ptr, uint8_t dev_num);
 
void ch_interrupt(ch_group_t *grp_ptr, uint8_t dev_num);
 
void ch_io_int_callback_set(ch_group_t *grp_ptr, ch_io_int_callback_t callback_func_ptr);
 
void ch_io_complete_callback_set(ch_group_t *grp_ptr, ch_io_complete_callback_t callback_func_ptr);
 
void ch_io_notify(ch_group_t *grp_ptr, uint8_t bus_index);
 
uint8_t ch_set_target_interrupt(ch_dev_t *dev_ptr, ch_tgt_int_filter_t tgt_int_filter);
 
ch_tgt_int_filter_t ch_get_target_interrupt(ch_dev_t *dev_ptr);
 
uint8_t ch_set_target_int_counter(ch_dev_t *dev_ptr, uint8_t meas_hist, uint8_t thresh_count, uint8_t reset);
 
uint8_t ch_get_target_int_counter(ch_dev_t *dev_ptr, uint8_t *meas_hist_ptr, uint8_t *thresh_count_ptr,
                                  uint8_t *reset_ptr);
 
uint8_t ch_set_interrupt_mode(ch_dev_t *dev_ptr, ch_interrupt_mode_t mode);
 
ch_interrupt_mode_t ch_get_interrupt_mode(ch_dev_t *dev_ptr);
 
uint8_t ch_set_interrupt_drive(ch_dev_t *dev_ptr, ch_interrupt_drive_t drive);
 
ch_interrupt_drive_t ch_get_interrupt_drive(ch_dev_t *dev_ptr);
 
uint8_t ch_enable_data_validation(ch_dev_t *dev_ptr, int16_t seed, ch_data_validation_mode_t mode);
 
uint16_t ch_data_validation_check(ch_dev_t *dev_ptr, ch_iq_sample_t *data, uint16_t num_samples);
 
uint8_t ch_enable_double_buffer(ch_dev_t *dev_ptr, uint8_t enable);
 
uint8_t ch_enable_metadata_in_iq0(ch_dev_t *dev_ptr, uint8_t enable);
 
uint8_t ch_update_metadata_from_iq0(ch_dev_t *dev_ptr, ch_iq_sample_t *iq_data);
 
uint8_t ch_set_rx_holdoff(ch_dev_t *dev_ptr, uint16_t num_samples);
 
uint16_t ch_get_rx_holdoff(ch_dev_t *dev_ptr);
 
uint8_t ch_set_rx_low_gain(ch_dev_t *dev_ptr, uint16_t num_samples);
 
uint16_t ch_get_rx_low_gain(ch_dev_t *dev_ptr);
 
uint8_t ch_set_tx_length(ch_dev_t *dev_ptr, uint16_t num_cycles);
 
uint16_t ch_get_tx_length(ch_dev_t *dev_ptr);
 
uint8_t ch_set_rx_pretrigger(ch_group_t *grp_ptr, uint8_t enable);
 
uint8_t ch_get_rx_pretrigger(ch_group_t *grp_ptr);
 
uint8_t ch_check_program(ch_dev_t *dev_ptr);
 
uint8_t ch_set_cal_result(ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr);
 
uint8_t ch_get_cal_result(ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr);
 
uint8_t ch_set_data_output(ch_dev_t *dev_ptr, ch_output_t *output_ptr);
 
uint32_t ch_usec_to_cycles(ch_dev_t *dev_ptr, uint32_t num_usec);
 
uint32_t ch_cycles_to_usec(ch_dev_t *dev_ptr, uint32_t num_cycles);
 
uint32_t ch_samples_to_cycles(uint16_t num_samples, ch_odr_t odr);
 
uint16_t ch_cycles_to_samples(uint32_t num_cycles, ch_odr_t odr);
 
uint16_t ch_usec_to_ticks(ch_dev_t *dev_ptr, uint32_t num_usec);
 
uint32_t ch_ticks_to_usec(ch_dev_t *dev_ptr, uint16_t num_ticks);
 
#ifdef INCLUDE_SHASTA_SUPPORT
 
uint8_t ch_meas_init_queue(ch_dev_t *dev_ptr);
 
uint8_t ch_meas_import(ch_dev_t *dev_ptr, measurement_queue_t *meas_queue_ptr, void *algo_cfg_ptr);
 
uint8_t ch_meas_reset(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint8_t ch_meas_init(ch_dev_t *dev_ptr, uint8_t meas_num, const ch_meas_config_t *meas_config_ptr,
                     const void *thresh_ptr);
 
uint8_t ch_meas_write_config(ch_dev_t *dev_ptr);
 
uint8_t ch_meas_optimize(ch_dev_t *dev_ptr, measurement_queue_t *meas_queue_ptr, void *algo_cfg_ptr);
 
void ch_meas_activate(ch_dev_t *dev_ptr, uint8_t meas_num);
 
void ch_meas_standby(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint8_t ch_meas_switch(ch_dev_t *dev_ptr);
 
uint8_t ch_meas_get_last_num(ch_dev_t *dev_ptr);
 
uint16_t ch_get_next_buf_addr(ch_dev_t *dev_ptr);
 
uint8_t ch_meas_get_queue(ch_dev_t *dev_ptr, measurement_queue_t *meas_queue_ptr);
 
uint8_t ch_meas_add_segment(ch_dev_t *dev_ptr, uint8_t meas_num, ch_meas_segment_t *seg_ptr);
 
uint8_t ch_meas_insert_segment(ch_dev_t *dev_ptr, uint8_t meas_num, const ch_meas_segment_t *inst_ptr,
                               uint8_t index_to_insert);
 
uint8_t ch_meas_insert_instruction(ch_dev_t *dev_ptr, uint8_t meas_num, const ch_meas_segment_t *inst_ptr,
                                   uint8_t index_to_insert);
 
uint8_t ch_meas_remove_segment(ch_dev_t *dev_ptr, uint8_t meas_num, uint8_t index_to_remove);
 
uint8_t ch_meas_remove_instruction(ch_dev_t *dev_ptr, uint8_t meas_num, uint8_t index_to_remove);
 
uint8_t ch_meas_add_segment_count(ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_cycles, uint8_t int_enable);
 
uint8_t ch_meas_add_segment_rx(ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_samples, uint8_t gain_reduce,
                               uint8_t atten, uint8_t int_enable);
 
uint8_t ch_meas_add_segment_tx(ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_cycles, uint8_t pulse_width,
                               uint8_t phase, uint8_t int_enable);
 
void ch_meas_init_segment_count(ch_meas_segment_t *seg_ptr, uint16_t num_cycles, uint8_t int_enable);
 
void ch_meas_init_segment_rx(ch_meas_segment_t *seg_ptr, uint16_t num_samples, ch_odr_t odr, uint8_t gain_reduce,
                             uint8_t atten, uint8_t int_enable);
 
void ch_meas_init_segment_tx(ch_meas_segment_t *seg_ptr, uint16_t num_cycles, uint8_t pulse_width, uint8_t phase,
                             uint8_t int_enable);
 
void ch_meas_get_info(ch_dev_t *dev_ptr, uint8_t meas_num, ch_meas_info_t *info_ptr);
 
void ch_meas_get_queue_info(ch_dev_t *dev_ptr, ch_meas_queue_info_t *info_ptr);
 
void ch_meas_get_seg_info(ch_dev_t *dev_ptr, uint8_t meas_num, uint8_t seg_num, ch_meas_seg_info_t *info_ptr);
 
void ch_inst_get_seg_info(pmut_transceiver_inst_t *inst_ptr, uint8_t odr, ch_meas_seg_info_t *info_ptr);
 
uint8_t ch_meas_set_interval(ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t interval_ms);
 
uint8_t ch_meas_set_interval_us(ch_dev_t *dev_ptr, uint8_t meas_num, uint32_t interval_us);
 
uint8_t ch_meas_set_interval_ticks(ch_dev_t *dev_ptr, uint8_t meas_num, uint32_t rtc_ticks);
 
uint16_t ch_meas_get_interval(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint32_t ch_meas_get_interval_us(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint32_t ch_meas_get_interval_ticks(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint8_t ch_meas_time_hop_enable(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint8_t ch_meas_time_hop_disable(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint8_t ch_meas_set_odr(ch_dev_t *dev_ptr, uint8_t meas_num, ch_odr_t odr);
 
ch_odr_t ch_meas_get_odr(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint8_t ch_meas_set_num_samples(ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_samples);
 
uint16_t ch_meas_get_num_samples(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint8_t ch_meas_set_max_range(ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t max_range_mm);
 
uint16_t ch_meas_get_max_range(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint16_t ch_meas_mm_to_samples(ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_mm);
 
uint16_t ch_meas_samples_to_mm(ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_samples);
 
ch_output_type_t ch_meas_get_iq_output(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint8_t ch_meas_set_iq_output(ch_dev_t *dev_ptr, uint8_t meas_num, ch_output_type_t output_format);
 
uint8_t ch_init_algo(ch_dev_t *dev_ptr);
 
uint8_t ch_get_algo_output(ch_dev_t *dev_ptr, void *algo_out_ptr);
 
uint8_t ch_get_algo_state(ch_dev_t *dev_ptr, void *algo_state_ptr);
 
uint8_t ch_get_algo_config(ch_dev_t *dev_ptr, void *algo_cfg_ptr);
 
uint8_t ch_set_algo_config(ch_dev_t *dev_ptr, const void *algo_cfg_ptr);
 
uint8_t ch_get_algo_info(ch_dev_t *dev_ptr, ICU_ALGO_SHASTA_INFO *algo_info_ptr);
 
const char *ch_get_sensor_id(ch_dev_t *dev_ptr);
 
uint8_t ch_get_mfg_info(ch_dev_t *dev_ptr, ch_mfg_info_t *info_ptr);
 
uint32_t ch_measure_pmut_frequency(ch_dev_t *dev_ptr);
 
#endif  // INCLUDE_SHASTA_SUPPORT
 
uint32_t ch_get_cpu_frequency(ch_dev_t *dev_ptr);
 
uint8_t ch_set_rtc(ch_dev_t *dev_ptr, ch_rtc_src_t rtc_source, uint16_t rtc_freq);
 
uint16_t ch_get_rtc_frequency(ch_dev_t *dev_ptr);
 
uint8_t ch_set_pmut_clock(ch_dev_t *dev_ptr, ch_pmut_clk_cfg_t clock_cfg);
 
ch_pmut_clk_cfg_t ch_get_pmut_clock(ch_dev_t *dev_ptr);
 
void ch_group_set_pmut_clock_freq(ch_group_t *grp_ptr, uint32_t pmut_clock_freq);
 
uint32_t ch_group_get_pmut_clock_freq(ch_group_t *grp_ptr);
 
uint8_t ch_set_data_ready_delay(ch_dev_t *dev_ptr, uint8_t delay_ms);
 
uint8_t ch_get_data_ready_delay(ch_dev_t *dev_ptr);
 
uint16_t ch_get_num_output_samples(ch_dev_t *dev_ptr);
 
void ch_trigger_soft(ch_dev_t *dev_ptr);
 
void ch_set_trigger_type(ch_dev_t *dev_ptr, ch_trigger_type_t trig_type);
 
ch_trigger_type_t ch_get_trigger_type(ch_dev_t *dev_ptr);
 
ch_meas_status_t ch_meas_get_status(ch_dev_t *dev_ptr, uint8_t meas_num);
 
uint8_t ch_log_init(ch_group_t *grp_ptr, ch_log_fmt_t format, ch_log_cfg_t *config_ptr);
 
void ch_log_append(uint8_t log_id, ch_log_fmt_t format, uint64_t timestamp, ch_log_data_t *log_data_ptr);
 
uint8_t ch_watchdog_enable(ch_dev_t *dev_ptr);
 
uint8_t ch_watchdog_disable(ch_dev_t *dev_ptr);
 
uint8_t ch_check_reset_state(ch_dev_t *dev_ptr, ch_sensor_reset_state_t *reset_state_ptr);
 
#ifdef __cplusplus
}
#endif
 
#endif /* __SONICLIB_H_ */