Vijayaraghavan Narayanan
vlx lib
Diff: common_driver.h
- Revision:
- 0:bc9f26b5dadf
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/common_driver.h Sun Feb 08 14:26:51 2015 +0000
@@ -0,0 +1,576 @@
+/*******************************************************************************
+################################################################################
+# (C) STMicroelectronics 2014
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License version 2 and only version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+# details.
+#
+# You should have received a copy of the GNU General Public License along with
+# this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+#------------------------------------------------------------------------------
+# Imaging Division
+################################################################################
+********************************************************************************/
+
+/*!
+ *\file common_driver.h
+ *\brief Application-level methods used for generic, system or identification operations.
+ */
+
+#ifndef _RANGE_DRIVER
+#define _RANGE_DRIVER
+
+#include "definitions.h"
+#include "platform.h"
+//-----------------------------------------------------------------------------
+// module imports
+//-----------------------------------------------------------------------------
+
+// "circle_types.h" included for following definition :
+//#ifndef __cplusplus
+//typedef enum {FALSE = 0, TRUE = !FALSE} bool;
+//#endif
+
+
+//-----------------------------------------------------------------------------
+// constant definitions
+//-----------------------------------------------------------------------------
+
+// API Version Strings
+#define API_MAJOR_VERSION 01
+#define API_MINOR_VERSION 00
+#define API_BUILD_NUMBER 00
+#define API_CODE_REVISION 1590
+
+// register addresses
+#define SYSTEM_MODE_GPIO0 0x10
+#define SYSTEM_MODE_GPIO1 0x11
+#define SYSTEM_HISTORY_CTRL 0x12
+#define SYSTEM_INTERRUPT_CONFIG_GPIO 0x14
+#define SYSTEM_INTERRUPT_CLEAR 0x15
+#define SYSTEM_FRESH_OUT_OF_RESET 0x16
+#define SYSTEM_GROUPED_PARAMETER_HOLD 0x17
+
+#define RESULT_INTERRUPT_STATUS_GPIO 0x4F
+
+#define PAD_I2C_CONFIG 0x13D
+
+#define I2C_SLAVE_DEVICE_ADDRESS 0x212
+
+#define SYSTEM_FATAL_ERROR_CODE 0x290
+#define SYSTEM_FATAL_ERROR_STATUS 0x291
+
+
+
+// PAD_I2C_CONFIG
+#define I2C_1v2_PAD_VOLTAGE 0x01
+#define I2C_2v8_PAD_VOLTAGE 0x02
+
+// SYSTEM_INTERRUPT_CONFIG_GPIO
+#define CONFIG_GPIO_INTERRUPT_DISABLED 0x00
+#define CONFIG_GPIO_INTERRUPT_LEVEL_LOW 0x01
+#define CONFIG_GPIO_INTERRUPT_LEVEL_HIGH 0x02
+#define CONFIG_GPIO_INTERRUPT_OUT_OF_WINDOW 0x03
+#define CONFIG_GPIO_INTERRUPT_NEW_SAMPLE_READY 0x04
+
+// SYSTEM_MODE_GPIOx
+#define GPIOx_MODE_SELECT_RANGING 0x00
+#define GPIOx_MODE_SELECT_ALS 0x01
+
+#define GPIOx_POLARITY_SELECT_OFF 0x00
+#define GPIOx_POLARITY_SELECT_ON 0x01
+#define GPIOx_POLARITY_SELECT_CLEARED 0xDF
+
+#define GPIOx_MODE_SELECT 0x01
+#define GPIOx_POLARITY_SELECT 0x20
+
+#define GPIOx_SELECT_OFF 0x00
+#define GPIOx_SELECT_MEASURE_READY 0x01
+#define GPIOx_SELECT_THRESHOLD_OUTPUT 0x02
+#define GPIOx_SELECT_BLANK_IN 0x03
+#define GPIOx_SELECT_BLANK_OUT 0x04
+#define GPIOx_SELECT_START_STOP 0x05
+#define GPIOx_SELECT_DISABLED 0x06
+#define GPIOx_SELECT_COMBINED_THRESHOLD_OUTPUT 0x07
+#define GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT 0x08
+
+// SYSTEM_HISTORY_CTRL
+#define HISTORY_BUFFER_ENABLE 0x01
+#define HISTORY_BUFFER_DISABLE 0x00
+
+#define HISTORY_BUFFER_ENABLED 0x01
+#define HISTORY_BUFFER_MODE 0x02
+#define HISTORY_BUFFER_CLEARED 0x04
+
+#define HISTORY_BUFFER_RANGING_MODE 0x00
+#define HISTORY_BUFFER_ALS_MODE 0x01
+
+// SYSTEM_INTERRUPT_CLEAR
+#define INTERRUPT_CLEAR_RANGING 0x01
+#define INTERRUPT_CLEAR_ALS 0x02
+#define INTERRUPT_CLEAR_ERROR 0x04
+
+// RESULT_INTERRUPT_STATUS_GPIO
+#define RES_INT_STAT_GPIO_NO_ERROR 0x00
+#define RES_INT_STAT_GPIO_LOW_LEVEL_THRESHOLD 0x01
+#define RES_INT_STAT_GPIO_HIGH_LEVEL_THRESHOLD 0x02
+#define RES_INT_STAT_GPIO_OUT_OF_WINDOW 0x03
+#define RES_INT_STAT_GPIO_NEW_SAMPLE_READY 0x04
+
+
+//-----------------------------------------------------------------------------
+// global variable declarations
+//-----------------------------------------------------------------------------
+
+//-----------------------------------------------------------------------------
+// method definitions
+//-----------------------------------------------------------------------------
+
+/*!
+ *
+ */
+sensor_error common_initialise(uint8_t device_base_address);
+
+/*!
+ *\brief Device setup for Ranging and ALS operations.\n
+ *
+ * To apply these settings the operation bits (bit 0) in the SYSRANGE_START SYSALS_START Registers must be cleared. \n
+ *
+ *\param[in] device_base_address
+ *\retval sensor_error
+ */
+sensor_error common_set_static_config(uint8_t device_base_address);
+
+/*!
+ *\brief Report device Identification Info.
+ *
+ * Return the contents of the Identification block registers, in the following order : \n
+ *
+ * IDENTIFICATION_MODEL_ID \n
+ * IDENTIFICATION_MODEL_REV_MAJOR \n
+ * IDENTIFICATION_MODEL_REV_MINOR \n
+ * IDENTIFICATION_MODULE_REV_MAJOR \n
+ * IDENTIFICATION_MODULE_REV_MINOR \n
+ * IDENTIFICATION_NVM_REVISION_ID \n
+ * IDENTIFICATION_MASK_REVISION_ID \n
+ * IDENTIFICATION_month \n
+ * IDENTIFICATION_year \n
+ * IDENTIFICATION_phase \n
+ * IDENTIFICATION_day \n
+ * IDENTIFICATION_time \n
+ * IDENTIFICATION_code \n
+ * IDENTIFICATION_FIRMWARE_REVISION_ID\n
+ *\param[in] device_base_address
+ *\retval List
+ */
+sensor_error common_get_identification(uint8_t device_base_address);
+
+/*!
+ *\brief Set Device I2C Base Address.
+ *
+ * Uses I2C_Slave_Device_address register at 0x0212. Can be over-written by a value read from NVM. \n
+ * Defaults to 0x52 (8-bit address)/0x29 (7-bit). Register reports a 7-bit value. \n
+ *\param[in] device_base_address
+ *\param[in] i2c_base_address 8-bit I2C Slave device base address.
+ *\retval sensor_error
+ */
+sensor_error common_set_i2c_base_address(uint8_t device_base_address, uint32_t i2c_base_address);
+
+/*!
+ *\brief Set I2C Pad Voltage.
+ *
+ * I2C Pad External Bus Supply voltage (applies to both pads). Can be overridden by a value read from in NVM. \n
+ *
+ * Possible values are : \n
+ * I2C_1v8_PAD_VOLTAGE = 0x01 \n
+ * I2C_2v8_PAD_VOLTAGE = 0x02 \n
+ *\param[in] device_base_address
+ *\param[in] pad_voltage I2C Pad External Bus Supply voltage.
+ *\retval sensor_error
+ */
+sensor_error common_set_i2c_pad_voltage(uint8_t device_base_address, uint8_t pad_voltage);
+
+/*!
+ *\brief Report I2C Pad Voltage.
+ *
+ * I2C Pad External Bus Supply voltage.
+ * Possible values are : \n
+ * I2C_1v8_PAD_VOLTAGE = 0x01 \n
+ * I2C_2v8_PAD_VOLTAGE = 0x02 \n
+ *\param[in] device_base_address
+ *\retval Integer
+ */
+uint8_t common_get_i2c_pad_voltage(uint8_t device_base_address);
+
+/*!
+ *\brief Set GPIO0 Mode.
+ *
+ * Possible values for mode are : \n
+ * GPIOx_MODE_SELECT_RANGING = 0x00 \n
+ * GPIOx_MODE_SELECT_ALS = 0x01 \n
+ *
+ * Possible settings for select are : \n
+ * GPIOx_SELECT_OFF = 0x00 \n
+ * GPIOx_SELECT_MEASURE_READY = 0x01 \n
+ * GPIOx_SELECT_DISABLED = 0x06 \n
+ * GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT = 0x08 \n
+ *
+ * Possible settings for polarity are : \n
+ * GPIOx_POLARITY_SELECT_OFF = 0x00 \n
+ * GPIOx_POLARITY_SELECT_ON = 0x01 \n
+ *\param[in] device_base_address
+ *\param[in] mode Operating mode to be selected.
+ *\param[in] select
+ *\param[in] polarity
+ *\retval sensor_error
+ */
+sensor_error common_set_system_mode_gpio0(uint8_t device_base_address, uint8_t mode, uint8_t select, uint8_t polarity);
+
+/*!
+ *\brief Set GPIO0 Mode.
+ *
+ * Possible values for mode are : \n
+ * GPIOx_MODE_SELECT_RANGING = 0x00 \n
+ * GPIOx_MODE_SELECT_ALS = 0x01 \n
+ *\param[in] device_base_address
+ *\param[in] mode: Operating mode to be selected.
+ *\retval sensor_error
+ */
+sensor_error common_set_gpio0_mode(uint8_t device_base_address, uint8_t mode);
+
+/*!
+ *\brief Report GPIO0 Mode.
+
+ Possible results are : \n
+ GPIOx_MODE_SELECT_RANGING = 0x00 \n
+ GPIOx_MODE_SELECT_ALS = 0x01 \n
+ *\param[in] device_base_address
+ *\retval Integer
+*/
+uint8_t common_get_gpio0_mode(uint8_t device_base_address);
+
+/*!
+ *\brief Set GPIO0 function configuration.
+
+ Possible settings are : \n
+ GPIOx_SELECT_OFF = 0x00 \n
+ GPIOx_SELECT_MEASURE_READY = 0x01 \n
+ GPIOx_SELECT_THRESHOLD_OUTPUT = 0x02 \n
+ GPIOx_SELECT_BLANK_IN = 0x03 \n
+ GPIOx_SELECT_BLANK_OUT = 0x04 \n
+ GPIOx_SELECT_START_STOP = 0x05 \n
+ GPIOx_SELECT_DISABLED = 0x06 \n
+ GPIOx_SELECT_COMBINED_THRESHOLD_OUTPUT = 0x07 \n
+ GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT = 0x08 \n
+ *\param[in] device_base_address
+ *\param[in] select:
+ *\retval sensor_error
+*/
+sensor_error common_set_gpio0_select(uint8_t device_base_address, uint8_t select);
+
+/*!
+ *\brief Report GPIO0 functional configuration.
+
+ Possible results are : \n
+ GPIOx_SELECT_OFF = 0x00 \n
+ GPIOx_SELECT_MEASURE_READY = 0x01 \n
+ GPIOx_SELECT_THRESHOLD_OUTPUT = 0x02 \n
+ GPIOx_SELECT_BLANK_IN = 0x03 \n
+ GPIOx_SELECT_BLANK_OUT = 0x04 \n
+ GPIOx_SELECT_START_STOP = 0x05 \n
+ GPIOx_SELECT_DISABLED = 0x06 \n
+ GPIOx_SELECT_COMBINED_THRESHOLD_OUTPUT = 0x07 \n
+ GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT = 0x08 \n
+ *\param[in] device_base_address
+ *\retval Integer
+*/
+uint8_t common_get_gpio0_select(uint8_t device_base_address);
+
+/*!
+ *\brief Set GPIO0 Polarity.
+
+ Possible settings are : \n
+ GPIOx_POLARITY_SELECT_OFF = 0x00 \n
+ GPIOx_POLARITY_SELECT_ON = 0x01 \n
+ *\param[in] device_base_address
+ *\param[in] polarity:
+ *\retval sensor_error
+*/
+sensor_error common_set_gpio0_polarity(uint8_t device_base_address, uint8_t polarity);
+
+/*!
+ *\brief Report GPIO0 Polarity.
+ *
+ * Report the status of the GPIO_0 Polarity select bit in SYSTEM_MODE_GPIO0 register. \n
+ *\param[in] device_base_address
+ *\retval Boolean
+*/
+bool_t common_get_gpio0_polarity(uint8_t device_base_address);
+
+/*!
+ *\brief Set GPIO1 Mode.
+
+ Possible values for mode are : \n
+ GPIOx_MODE_SELECT_RANGING = 0x00 \n
+ GPIOx_MODE_SELECT_ALS = 0x01 \n
+
+ Possible settings for select are : \n
+ GPIOx_SELECT_OFF = 0x00 \n
+ GPIOx_SELECT_MEASURE_READY = 0x01 \n
+ GPIOx_SELECT_DISABLED = 0x06 \n
+ GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT = 0x08 \n
+
+ Possible settings for polarity are : \n
+ GPIOx_POLARITY_SELECT_OFF = 0x00 \n
+ GPIOx_POLARITY_SELECT_ON = 0x01 \n
+ *\param[in] device_base_address
+ *\param[in] mode: Operating mode to be selected.
+ *\param[in] select:
+ *\param[in] polarity:
+ *\retval sensor_error
+*/
+sensor_error common_set_system_mode_gpio1(uint8_t device_base_address, uint8_t mode, uint8_t select, uint8_t polarity);
+
+/*!
+ *\brief Set GPIO1 Mode.
+
+ Possible mode settings are : \n
+ GPIOx_MODE_SELECT_RANGING = 0x00 \n
+ GPIOx_MODE_SELECT_ALS = 0x01 \n
+ *\param[in] device_base_address
+ *\param[in] mode:
+ *\retval sensor_error
+*/
+sensor_error common_set_gpio1_mode(uint8_t device_base_address, uint8_t mode);
+
+/*!
+ *\brief Report GPIO1 Mode.
+
+ Possible results are : \n
+ GPIOx_MODE_SELECT_RANGING = 0x00 \n
+ GPIOx_MODE_SELECT_ALS = 0x01 \n
+ *\param[in] device_base_address
+ *\retval Integer
+*/
+uint8_t common_get_gpio1_mode(uint8_t device_base_address);
+
+/*!
+ *\brief Set GPIO1 functional configuration.
+
+ Possible settings are : \n
+ GPIOx_SELECT_OFF = 0x00 \n
+ GPIOx_SELECT_MEASURE_READY = 0x01 \n
+ GPIOx_SELECT_THRESHOLD_OUTPUT = 0x02 \n
+ GPIOx_SELECT_BLANK_IN = 0x03 \n
+ GPIOx_SELECT_BLANK_OUT = 0x04 \n
+ GPIOx_SELECT_START_STOP = 0x05 \n
+ GPIOx_SELECT_DISABLED = 0x06 \n
+ GPIOx_SELECT_COMBINED_THRESHOLD_OUTPUT = 0x07 \n
+ GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT = 0x08 \n
+ *\param[in] device_base_address
+ *\param[in] select:
+ *\retval sensor_error
+*/
+sensor_error common_set_gpio1_select(uint8_t device_base_address, uint8_t select);
+
+/*!
+ *\brief Report GPIO1 functional configuration.
+
+ Possible results are : \n
+ GPIOx_SELECT_OFF = 0x00 \n
+ GPIOx_SELECT_MEASURE_READY = 0x01 \n
+ GPIOx_SELECT_THRESHOLD_OUTPUT = 0x02 \n
+ GPIOx_SELECT_BLANK_IN = 0x03 \n
+ GPIOx_SELECT_BLANK_OUT = 0x04 \n
+ GPIOx_SELECT_START_STOP = 0x05 \n
+ GPIOx_SELECT_DISABLED = 0x06 \n
+ GPIOx_SELECT_COMBINED_THRESHOLD_OUTPUT = 0x07 \n
+ GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT = 0x08 \n
+ *\param[in] device_base_address
+ *\retval Integer
+*/
+uint8_t common_get_gpio1_select(uint8_t device_base_address);
+
+/*!
+ *\brief Set GPIO1 Polarity.
+
+ GPIOx_POLARITY_SELECT_OFF = 0x00 \n
+ GPIOx_POLARITY_SELECT_ON = 0x01 \n
+ *\param[in] device_base_address
+ *\param[in] polarity:
+ *\retval sensor_error
+*/
+sensor_error common_set_gpio1_polarity(uint8_t device_base_address, uint8_t polarity);
+
+/*!
+ *\brief Report GPIO1 Polarity.
+
+ Report the status of the GPIO_0 Polarity select bit in SYSTEM_MODE_GPIO0 register.
+ *\param[in] device_base_address
+ *\retval Boolean
+*/
+bool_t common_get_gpio1_polarity(uint8_t device_base_address);
+
+/*!
+ *\brief Set History Buffer Enable.
+
+ Possible settings are : \n
+ HISTORY_BUFFER_ENABLE = 0x01 \n
+ HISTORY_BUFFER_DISABLE = 0x00 \n
+ *\param[in] device_base_address
+ *\param[in] history_buffer_enable:
+ *\retval sensor_error
+*/
+sensor_error common_set_history_buffer_enable(uint8_t device_base_address, uint8_t history_buffer_enable);
+
+/*!
+ *\brief Report History Buffer Enable status.
+
+ Returns True if the command completes successfully, otherwise False.\n
+ *\param[in] device_base_address
+ *\retval Boolean
+*/
+bool_t common_get_history_buffer_enable(uint8_t device_base_address);
+
+/*!
+ *\brief Set History Buffer Mode.
+
+ Possible modes are : \n
+ HISTORY_BUFFER_RANGING_MODE = 0x00 \n
+ HISTORY_BUFFER_ALS_MODE = 0x01 \n
+ *\param[in] device_base_address
+ *\param[in] history_buffer_mode:
+ *\retval sensor_error
+*/
+sensor_error common_set_history_buffer_mode(uint8_t device_base_address, uint8_t history_buffer_mode);
+
+/*!
+ *\brief Report History Buffer Mode.
+
+ Returns the contents of the SYSTEM_HISTORY_CTRL register. \n
+ Possible values are : \n
+ HISTORY_BUFFER_RANGING_MODE = 0x00 \n
+ HISTORY_BUFFER_ALS_MODE = 0x01 \n
+ *\param[in] device_base_address
+ *\retval Integer
+*/
+uint8_t common_get_history_buffer_mode(uint8_t device_base_address);
+
+/*!
+ *\brief Clear history buffer (mode not cleared)
+ *\param[in] device_base_address
+ *\retval sensor_error
+*/
+sensor_error common_set_history_buffer_clear(uint8_t device_base_address);
+
+/*!
+ *\brief Report History Buffer Clear status.
+ *
+ * Returns True if the SYSTEM_HISTORY_CTRL register is cleared, otherwise False. \n
+ *\param[in] device_base_address
+ *\retval Boolean
+*/
+bool_t common_get_history_buffer_clear(uint8_t device_base_address);
+
+/*!
+ *\brief Clear 'Error' System Interrupt.
+ *\param[in] device_base_address
+ *\retval sensor_error
+*/
+sensor_error common_set_system_interrupt_clear_error(uint8_t device_base_address);
+
+/*!
+ *\brief Report GPIO Interrupt Error Result Status.
+
+ Returns the Error flag portion of the RESULT_INTERRUPT_STATUS_GPIO register. \n
+ Possible returns are : \n
+ 0: No error reported \n
+ 1: Laser Safety Error \n
+ 2: PLL error (either PLL1 or PLL2) \n
+ 3: Measurement error \n
+ *\param[in] device_base_address
+ *\retval Integer
+*/
+uint8_t common_get_error_result_interrupt_status_gpio(uint8_t device_base_address);
+
+/*!
+ *\brief Clear System Fresh Out Of Reset flag.
+ *
+ * The fresh out of reset bit defaults to 1 at boot-up. The user can set this to 0 after initial boot and then use this flag to check for reset conditions.
+ *\param[in] device_base_address
+ *\retval sensor_error
+*/
+sensor_error common_clear_system_fresh_out_of_reset(uint8_t device_base_address);
+
+/*!
+ *\brief Report System Fresh Out Of Reset status.
+ *
+ * Returns True if the SYSTEM_FRESH_OUT_OF_RESET register status is set, otherwise False. \n
+ *\param[in] device_base_address
+ *\retval Boolean
+*/
+bool_t common_get_system_fresh_out_of_reset(uint8_t device_base_address);
+
+/*!
+ *\brief Set System Group Parameter Hold flag.
+
+ The grouped_parameter_hold flag is set to indicate that device data is being updated. \n
+ 0: Data is stable - user is safe to copy. \n
+ 1: Data being updated - user not safe to copy. \n
+ *\param[in] device_base_address
+ *\retval sensor_error
+*/
+sensor_error common_set_system_group_parameter_hold(uint8_t device_base_address);
+
+/*!
+ *\brief Clear System Group Parameter Hold flag.
+
+ The grouped_parameter_hold flag is set to indicate that device data is being updated. \n
+ 0: Data is stable - user is safe to copy. \n
+ 1: Data being updated - user not safe to copy. \n
+ *\param[in] device_base_address
+ *\retval sensor_error
+*/
+sensor_error common_clear_system_group_parameter_hold(uint8_t device_base_address);
+
+/*!
+ *\brief Report System Fatal Error Code flag status.
+ *
+ * Returns the contents of the SYSTEM_FATAL_ERROR_CODE register, which is written to when a fatal error occurs.
+ *\param[in] device_base_address
+ *\retval Integer
+*/
+uint8_t common_get_system_fatal_error_code(uint8_t device_base_address);
+
+/*!
+ *\brief Report System Fatal Error Status.
+
+ Returns the contents of the SYSTEM_FATAL_ERROR_STATUS register, which is written to when a fatal error occurs.\n
+
+ Read Only HW status bit, set high when a 1 is written into FATAL_ERROR_CODE. \n
+ Checked by FW on bootup to ascertain device status. Can only be rest by a main Go2 reset. \n
+ *\param[in] device_base_address
+ *\retval Integer
+*/
+uint8_t common_get_system_fatal_error_status(uint8_t device_base_address);
+
+/*!
+ *\brief Report System Health.
+ *
+ * A combination of fresh_from_reset, fatal_error and laser safety checks
+ *\param[in] device_base_address
+ *\retval Integer. A combined system health flag.
+*/
+uint8_t common_get_system_health_check(uint8_t device_base_address);
+
+#endif
+
+