Bell Huang / pixart_pah8011

class pah8011 for mbed

pah8011/pah_driver.h@6:d196b612b14a, 2019-01-23 (annotated)

Committer:
bell_huang
Date:
Wed Jan 23 08:01:57 2019 +0000
Revision:
6:d196b612b14a
Parent:
0:242cf8f28bf2 
Remove mbed

Who changed what in which revision?

UserRevisionLine numberNew contents of line
bell_huang 6:d196b612b14a 1 /**
bell_huang 6:d196b612b14a 2 * @file sns_dd_pah_driver.h
bell_huang 6:d196b612b14a 3 *
bell_huang 6:d196b612b14a 4 * Copyright (c) 2016-2017 PixArt Imaging Inc.
bell_huang 6:d196b612b14a 5 * All Rights Reserved.
bell_huang 6:d196b612b14a 6 * Confidential and Proprietary - PixArt Imaging Inc.
bell_huang 6:d196b612b14a 7 **/
bell_huang 6:d196b612b14a 8
bell_huang 0:242cf8f28bf2 9 /*==============================================================================
bell_huang 0:242cf8f28bf2 10 * Edit History
bell_huang 0:242cf8f28bf2 11 *
bell_huang 0:242cf8f28bf2 12 * This section contains comments describing changes made to the module. Notice
bell_huang 0:242cf8f28bf2 13 * that changes are listed in reverse chronological order. Please use ISO format
bell_huang 0:242cf8f28bf2 14 * for dates.
bell_huang 0:242cf8f28bf2 15 *
bell_huang 0:242cf8f28bf2 16 * when who what, where, why
bell_huang 0:242cf8f28bf2 17 * ---------- --- -----------------------------------------------------------
bell_huang 6:d196b612b14a 18 * 2016-10-14 bell - Add functions: pah_init_with_flags().
bell_huang 0:242cf8f28bf2 19 * - Add pah_ppg_led_on_e flag.
bell_huang 6:d196b612b14a 20 * 2016-06-07 bell - Add functions: pah_set_mode(), pah_run_device().
bell_huang 0:242cf8f28bf2 21 * - Add enum: pah_device.
bell_huang 0:242cf8f28bf2 22 * - Add comments.
bell_huang 6:d196b612b14a 23 * 2016-04-29 bell - Add PPG 200Hz modes.
bell_huang 0:242cf8f28bf2 24 * - Add helper functions: pah_is_ppg_mode(), pah_is_ppg_20hz_mode(), pah_fifo_data_num_per_ch().
bell_huang 0:242cf8f28bf2 25 * - Add pah_stop_mode
bell_huang 0:242cf8f28bf2 26 * - Remove pah_suspend_mode.
bell_huang 0:242cf8f28bf2 27 * - Fix setting pah_set_report_sample_num_per_ch() after enter_mode() causes bad behavior.
bell_huang 6:d196b612b14a 28 * 2016-04-20 bell Add pah_stop_mode. pah_none can be regarded as pah_stop_mode.
bell_huang 6:d196b612b14a 29 * 2016-04-12 bell Add license information and revision information.
bell_huang 6:d196b612b14a 30 * 2016-04-07 bell Initial revision.
bell_huang 0:242cf8f28bf2 31 ==============================================================================*/
bell_huang 0:242cf8f28bf2 32
bell_huang 6:d196b612b14a 33 #ifndef __sns_dd_pah_driver_h__
bell_huang 6:d196b612b14a 34 #define __sns_dd_pah_driver_h__
bell_huang 0:242cf8f28bf2 35
bell_huang 6:d196b612b14a 36 #include "pah_platform_types.h"
bell_huang 0:242cf8f28bf2 37 #include "pah_driver_types.h"
bell_huang 6:d196b612b14a 38 #include "pah_ret.h"
bell_huang 0:242cf8f28bf2 39
bell_huang 0:242cf8f28bf2 40
bell_huang 0:242cf8f28bf2 41 typedef struct {
bell_huang 0:242cf8f28bf2 42
bell_huang 0:242cf8f28bf2 43 pah_stream_e stream;
bell_huang 0:242cf8f28bf2 44 pah_intshape_pulse_type_e intshape_pulse_type;
bell_huang 0:242cf8f28bf2 45 pah_powerdown_int_status_e powerdown_int_status;
bell_huang 0:242cf8f28bf2 46 pah_ppg_led_on_e ppg_led_on;
bell_huang 0:242cf8f28bf2 47
bell_huang 0:242cf8f28bf2 48 } pah_flags_s;
bell_huang 0:242cf8f28bf2 49
bell_huang 0:242cf8f28bf2 50
bell_huang 0:242cf8f28bf2 51
bell_huang 0:242cf8f28bf2 52 /**
bell_huang 0:242cf8f28bf2 53 * @brief Initialize the driver.
bell_huang 0:242cf8f28bf2 54 *
bell_huang 0:242cf8f28bf2 55 * It should been called once before any other function calls.
bell_huang 0:242cf8f28bf2 56 *
bell_huang 0:242cf8f28bf2 57 * @return True if successful.
bell_huang 0:242cf8f28bf2 58 */
bell_huang 0:242cf8f28bf2 59 bool pah_init(void);
bell_huang 0:242cf8f28bf2 60
bell_huang 0:242cf8f28bf2 61 /**
bell_huang 6:d196b612b14a 62 * @brief Initialize the driver.
bell_huang 6:d196b612b14a 63 *
bell_huang 6:d196b612b14a 64 * It should been called once before any other function calls.
bell_huang 6:d196b612b14a 65 *
bell_huang 6:d196b612b14a 66 * @param[in] flags Refer to struct pah_flags_s.
bell_huang 6:d196b612b14a 67 *
bell_huang 6:d196b612b14a 68 * @return True if successful.
bell_huang 6:d196b612b14a 69 */
bell_huang 0:242cf8f28bf2 70 bool pah_init_with_flags(const pah_flags_s *flags);
bell_huang 0:242cf8f28bf2 71
bell_huang 0:242cf8f28bf2 72 /**
bell_huang 0:242cf8f28bf2 73 * @brief De-initialize the driver.
bell_huang 0:242cf8f28bf2 74 *
bell_huang 0:242cf8f28bf2 75 * @return None.
bell_huang 0:242cf8f28bf2 76 */
bell_huang 0:242cf8f28bf2 77 void pah_deinit(void);
bell_huang 0:242cf8f28bf2 78
bell_huang 0:242cf8f28bf2 79
bell_huang 0:242cf8f28bf2 80 /**
bell_huang 0:242cf8f28bf2 81 * @brief Set device into a given pah mode and run device.
bell_huang 0:242cf8f28bf2 82 *
bell_huang 0:242cf8f28bf2 83 * It change device into a specific mode(refer to enum pah_mode) and then enable device to run if the mode depends on device.
bell_huang 0:242cf8f28bf2 84 * Equal to the combination of pah_set_mode() and pah_run(), i.e
bell_huang 0:242cf8f28bf2 85 * pah_set_mode(pah_ppg_mode);
bell_huang 0:242cf8f28bf2 86 * pah_run(pah_device_ppg, true);
bell_huang 0:242cf8f28bf2 87 *
bell_huang 0:242cf8f28bf2 88 * @param[in] mode Refer to enum pah_mode.
bell_huang 0:242cf8f28bf2 89 *
bell_huang 0:242cf8f28bf2 90 * @return True if setting successfully.
bell_huang 0:242cf8f28bf2 91 */
bell_huang 0:242cf8f28bf2 92 bool pah_enter_mode(pah_mode mode);
bell_huang 0:242cf8f28bf2 93
bell_huang 0:242cf8f28bf2 94
bell_huang 0:242cf8f28bf2 95 /**
bell_huang 0:242cf8f28bf2 96 * @brief Set device into a given pah mode.
bell_huang 0:242cf8f28bf2 97 *
bell_huang 0:242cf8f28bf2 98 * It change device into a specific mode(refer to enum pah_mode).
bell_huang 0:242cf8f28bf2 99 *
bell_huang 0:242cf8f28bf2 100 * @param[in] mode Refer to enum pah_mode.
bell_huang 0:242cf8f28bf2 101 *
bell_huang 0:242cf8f28bf2 102 * @return True if setting successfully.
bell_huang 0:242cf8f28bf2 103 */
bell_huang 0:242cf8f28bf2 104 bool pah_set_mode(pah_mode mode);
bell_huang 0:242cf8f28bf2 105
bell_huang 0:242cf8f28bf2 106 /**
bell_huang 0:242cf8f28bf2 107 * @brief Enable/Disable device to run.
bell_huang 0:242cf8f28bf2 108 *
bell_huang 0:242cf8f28bf2 109 * It returns false if the current mode isn't activable, such as pah_stop_mode.
bell_huang 0:242cf8f28bf2 110 *
bell_huang 0:242cf8f28bf2 111 * @param[in] device Refer to enum pah_device.
bell_huang 0:242cf8f28bf2 112 * @param[in] enable Enable/Disable the device.
bell_huang 0:242cf8f28bf2 113 *
bell_huang 0:242cf8f28bf2 114 * @return True if setting successfully.
bell_huang 0:242cf8f28bf2 115 */
bell_huang 0:242cf8f28bf2 116 bool pah_run_device(pah_device device, bool enable);
bell_huang 0:242cf8f28bf2 117
bell_huang 0:242cf8f28bf2 118
bell_huang 0:242cf8f28bf2 119 /**
bell_huang 0:242cf8f28bf2 120 * @brief Query current mode.
bell_huang 0:242cf8f28bf2 121 *
bell_huang 0:242cf8f28bf2 122 * @return Refer to enum pah_mode.
bell_huang 0:242cf8f28bf2 123 */
bell_huang 0:242cf8f28bf2 124 pah_mode pah_query_mode(void);
bell_huang 0:242cf8f28bf2 125
bell_huang 0:242cf8f28bf2 126 /**
bell_huang 0:242cf8f28bf2 127 * @brief Check if the device is in PPG mode.
bell_huang 0:242cf8f28bf2 128 *
bell_huang 0:242cf8f28bf2 129 * @return True if the device is in PPG mode.
bell_huang 0:242cf8f28bf2 130 */
bell_huang 0:242cf8f28bf2 131 bool pah_is_ppg_mode(void);
bell_huang 0:242cf8f28bf2 132
bell_huang 0:242cf8f28bf2 133 /**
bell_huang 0:242cf8f28bf2 134 * @brief Check if the device is in PPG(20Hz) mode.
bell_huang 0:242cf8f28bf2 135 *
bell_huang 0:242cf8f28bf2 136 * @return True if the device is in PPG(20Hz) mode.
bell_huang 0:242cf8f28bf2 137 */
bell_huang 0:242cf8f28bf2 138 bool pah_is_ppg_20hz_mode(void);
bell_huang 0:242cf8f28bf2 139
bell_huang 0:242cf8f28bf2 140
bell_huang 0:242cf8f28bf2 141 /**
bell_huang 0:242cf8f28bf2 142 * @brief Process tasks after INT1 interrupt.
bell_huang 0:242cf8f28bf2 143 *
bell_huang 0:242cf8f28bf2 144 * Whenever the device raises INT1 interrupt, this function must be called once to process tasks.
bell_huang 0:242cf8f28bf2 145 * This return pah_ret stands for a erorr code, normally it should been pah_success.
bell_huang 0:242cf8f28bf2 146 *
bell_huang 0:242cf8f28bf2 147 * If it returns pah_success, you can handle with some tasks according to current mode.
bell_huang 0:242cf8f28bf2 148 *
bell_huang 0:242cf8f28bf2 149 * Else if it returns pah_no_interrupt, it means that the device didn't raise INT1 interrupt yet.
bell_huang 0:242cf8f28bf2 150 * Generally there is an extrinsic factor raising the interrupt which has nothing to do with the device.
bell_huang 0:242cf8f28bf2 151 *
bell_huang 0:242cf8f28bf2 152 * @return pah_success if the open operation was done successfully.
bell_huang 0:242cf8f28bf2 153 * pah_no_interrupt if the device didn't raise interrupt yet.
bell_huang 0:242cf8f28bf2 154 * pah_err_fifo_overflow if pah_task() was too late to be called.
bell_huang 0:242cf8f28bf2 155 * Otherwise to indicate an error has occurred.
bell_huang 0:242cf8f28bf2 156 */
bell_huang 0:242cf8f28bf2 157 pah_ret pah_task(void);
bell_huang 0:242cf8f28bf2 158
bell_huang 0:242cf8f28bf2 159
bell_huang 0:242cf8f28bf2 160 /**
bell_huang 0:242cf8f28bf2 161 * @brief Access current fifo data.
bell_huang 0:242cf8f28bf2 162 *
bell_huang 0:242cf8f28bf2 163 * This information is updated after a successful pah_task().
bell_huang 0:242cf8f28bf2 164 *
bell_huang 0:242cf8f28bf2 165 * @return Location where fifo data is stored.
bell_huang 0:242cf8f28bf2 166 */
bell_huang 0:242cf8f28bf2 167 uint8_t* pah_get_fifo_data(void);
bell_huang 0:242cf8f28bf2 168
bell_huang 0:242cf8f28bf2 169 /**
bell_huang 0:242cf8f28bf2 170 * @brief Read current length of fifo data.
bell_huang 0:242cf8f28bf2 171 *
bell_huang 0:242cf8f28bf2 172 * This information is updated after a successful pah_task().
bell_huang 0:242cf8f28bf2 173 *
bell_huang 0:242cf8f28bf2 174 * @return The length(in bytes) of fifo data.
bell_huang 0:242cf8f28bf2 175 */
bell_huang 0:242cf8f28bf2 176 uint32_t pah_fifo_data_num_per_ch(void);
bell_huang 0:242cf8f28bf2 177
bell_huang 0:242cf8f28bf2 178 /**
bell_huang 0:242cf8f28bf2 179 * @brief Check if there are fifo data.
bell_huang 0:242cf8f28bf2 180 *
bell_huang 0:242cf8f28bf2 181 * This information is updated after a successful pah_task().
bell_huang 0:242cf8f28bf2 182 *
bell_huang 0:242cf8f28bf2 183 * @return True if there are fifo data.
bell_huang 0:242cf8f28bf2 184 */
bell_huang 0:242cf8f28bf2 185 bool pah_has_fifo_data(void);
bell_huang 0:242cf8f28bf2 186
bell_huang 0:242cf8f28bf2 187 /**
bell_huang 0:242cf8f28bf2 188 * @brief Check fifo channel number.
bell_huang 0:242cf8f28bf2 189 *
bell_huang 0:242cf8f28bf2 190 * This information is updated after a successful pah_task().
bell_huang 0:242cf8f28bf2 191 *
bell_huang 0:242cf8f28bf2 192 * @return Channel number.
bell_huang 0:242cf8f28bf2 193 */
bell_huang 0:242cf8f28bf2 194 uint32_t pah_get_fifo_ch_num(void);
bell_huang 0:242cf8f28bf2 195
bell_huang 0:242cf8f28bf2 196 /**
bell_huang 0:242cf8f28bf2 197 * @brief Check if the device is on touch.
bell_huang 0:242cf8f28bf2 198 *
bell_huang 0:242cf8f28bf2 199 * This information is updated after a successful pah_task().
bell_huang 0:242cf8f28bf2 200 *
bell_huang 0:242cf8f28bf2 201 * @return True if the device is on touch.
bell_huang 0:242cf8f28bf2 202 */
bell_huang 0:242cf8f28bf2 203 bool pah_is_touched(void);
bell_huang 0:242cf8f28bf2 204
bell_huang 0:242cf8f28bf2 205
bell_huang 0:242cf8f28bf2 206 /**
bell_huang 0:242cf8f28bf2 207 * @brief Set all values of fifo data to 0.
bell_huang 0:242cf8f28bf2 208 *
bell_huang 0:242cf8f28bf2 209 * @return None.
bell_huang 0:242cf8f28bf2 210 */
bell_huang 0:242cf8f28bf2 211 void pah_clear_fifo_data(void);
bell_huang 0:242cf8f28bf2 212
bell_huang 0:242cf8f28bf2 213
bell_huang 0:242cf8f28bf2 214 /**
bell_huang 0:242cf8f28bf2 215 * @brief Set report fifo callback.
bell_huang 0:242cf8f28bf2 216 *
bell_huang 0:242cf8f28bf2 217 * @param[in] fp_handler The callback function to be called when pah_task() receives new fifo data.
bell_huang 0:242cf8f28bf2 218 * @param[in] user_data The user data to be passed as parameter of callback function.
bell_huang 0:242cf8f28bf2 219 *
bell_huang 0:242cf8f28bf2 220 * @return None.
bell_huang 0:242cf8f28bf2 221 */
bell_huang 0:242cf8f28bf2 222 void pah_set_report_fifo_callback(pah_report_fifo_handle fp_handler, void* user_data);
bell_huang 0:242cf8f28bf2 223
bell_huang 0:242cf8f28bf2 224
bell_huang 0:242cf8f28bf2 225 /**
bell_huang 0:242cf8f28bf2 226 * @brief Get the specific I2C slave address of the device.
bell_huang 0:242cf8f28bf2 227 *
bell_huang 0:242cf8f28bf2 228 * @return I2C slave address of the device.
bell_huang 0:242cf8f28bf2 229 */
bell_huang 0:242cf8f28bf2 230 uint16_t pah_get_i2c_slave_addr(void);
bell_huang 0:242cf8f28bf2 231
bell_huang 0:242cf8f28bf2 232
bell_huang 0:242cf8f28bf2 233 /**
bell_huang 0:242cf8f28bf2 234 * @brief Enable or disable INT2 as touch flag.
bell_huang 0:242cf8f28bf2 235 *
bell_huang 0:242cf8f28bf2 236 * Default is disabled.
bell_huang 0:242cf8f28bf2 237 *
bell_huang 0:242cf8f28bf2 238 * By default, touch/no-touch detection raises a pulse interrupt to INT1 which shared with FIFO interrupt.
bell_huang 0:242cf8f28bf2 239 * If INT2 as touch flag is enabled, the device on touch causes INT2 pull-up, otherwise pull-down.
bell_huang 0:242cf8f28bf2 240 *
bell_huang 0:242cf8f28bf2 241 * @param[in] enable True to enable, otherwise to disable.
bell_huang 0:242cf8f28bf2 242 *
bell_huang 0:242cf8f28bf2 243 * @return True if setting successfully.
bell_huang 0:242cf8f28bf2 244 */
bell_huang 0:242cf8f28bf2 245 bool pah_set_int2_as_touch_flag(bool enable);
bell_huang 0:242cf8f28bf2 246
bell_huang 0:242cf8f28bf2 247
bell_huang 0:242cf8f28bf2 248 /**
bell_huang 0:242cf8f28bf2 249 * @brief Set report number per channel.
bell_huang 0:242cf8f28bf2 250 *
bell_huang 0:242cf8f28bf2 251 * The report number determines how many fifo data number the device collects, the device will raise a fifo interrupt.
bell_huang 0:242cf8f28bf2 252 * For example, in PPG(20Hz) the device generates one data per 50ms, thus setting report number 20 makes the device raise fifo interrupts each 50ms*20 = 1000ms.
bell_huang 0:242cf8f28bf2 253 *
bell_huang 0:242cf8f28bf2 254 * @param[in] report_sample_num_per_ch The report number per channel.
bell_huang 0:242cf8f28bf2 255 *
bell_huang 0:242cf8f28bf2 256 * @return None.
bell_huang 0:242cf8f28bf2 257 */
bell_huang 0:242cf8f28bf2 258 void pah_set_report_sample_num_per_ch(uint32_t report_sample_num_per_ch);
bell_huang 0:242cf8f28bf2 259
bell_huang 0:242cf8f28bf2 260 /**
bell_huang 0:242cf8f28bf2 261 * @brief Get report number per channel.
bell_huang 0:242cf8f28bf2 262 *
bell_huang 0:242cf8f28bf2 263 * @return The report number per channel.
bell_huang 0:242cf8f28bf2 264 */
bell_huang 0:242cf8f28bf2 265 uint32_t pah_get_report_sample_num_per_ch(void);
bell_huang 0:242cf8f28bf2 266
bell_huang 0:242cf8f28bf2 267 /**
bell_huang 0:242cf8f28bf2 268 * @brief Get the maximum report number per channel.
bell_huang 0:242cf8f28bf2 269 *
bell_huang 0:242cf8f28bf2 270 * Due to the limit of buffer length, the number passing to pah_set_report_sample_num_per_ch() must be less than a maximum value.
bell_huang 0:242cf8f28bf2 271 *
bell_huang 0:242cf8f28bf2 272 * @return The maximum report number per channel.
bell_huang 0:242cf8f28bf2 273 */
bell_huang 0:242cf8f28bf2 274 uint32_t pah_get_max_report_sample_num_per_ch(void);
bell_huang 0:242cf8f28bf2 275
bell_huang 0:242cf8f28bf2 276 /**
bell_huang 0:242cf8f28bf2 277 * @brief Get how many bytes per fifo sample.
bell_huang 0:242cf8f28bf2 278 *
bell_huang 0:242cf8f28bf2 279 * @return Bytes per fifo sample.
bell_huang 0:242cf8f28bf2 280 */
bell_huang 0:242cf8f28bf2 281 uint32_t pah_get_bytes_per_sample(void);
bell_huang 0:242cf8f28bf2 282
bell_huang 6:d196b612b14a 283
bell_huang 0:242cf8f28bf2 284 /**
bell_huang 0:242cf8f28bf2 285 * @brief Check if the driver is valid to the device.
bell_huang 0:242cf8f28bf2 286 *
bell_huang 0:242cf8f28bf2 287 * This function reads device registers directly.
bell_huang 0:242cf8f28bf2 288 *
bell_huang 0:242cf8f28bf2 289 * @return True if the driver is valid to the device.
bell_huang 0:242cf8f28bf2 290 */
bell_huang 0:242cf8f28bf2 291 bool pah_verify_product_id(void);
bell_huang 0:242cf8f28bf2 292
bell_huang 0:242cf8f28bf2 293 /**
bell_huang 0:242cf8f28bf2 294 * @brief Check if the device is on touch.
bell_huang 0:242cf8f28bf2 295 *
bell_huang 0:242cf8f28bf2 296 * This function reads device registers directly.
bell_huang 0:242cf8f28bf2 297 *
bell_huang 0:242cf8f28bf2 298 * @param[out] is_touched True if the device is on touch.
bell_huang 0:242cf8f28bf2 299 *
bell_huang 0:242cf8f28bf2 300 * @return pah_success if the open operation was done successfully.
bell_huang 0:242cf8f28bf2 301 * Otherwise to indicate an error has occurred.
bell_huang 0:242cf8f28bf2 302 */
bell_huang 0:242cf8f28bf2 303 pah_ret pah_read_touch_flag(bool *is_touched);
bell_huang 0:242cf8f28bf2 304
bell_huang 0:242cf8f28bf2 305
bell_huang 0:242cf8f28bf2 306 #endif // header guard
bell_huang 6:d196b612b14a 307