File content as of revision 32:262fc8aeb486:

/*
CONFIDENTIAL AND PROPRIETARY INFORMATION

Copyright (c) 2018 Emutex Ltd. All rights reserved.
This software and documentation contain confidential and
proprietary information that is the property of
Emutex Ltd. The software and documentation are
furnished under a license agreement and may be used
or copied only in accordance with the terms of the license
agreement. No part of the software and documentation
may be reproduced, transmitted, or translated, in any
form or by any means, electronic, mechanical, manual,
optical, or otherwise, without prior written permission
of Emutex Ltd., or as expressly provided by the license agreement.
Reverse engineering is prohibited, and reproduction,
disclosure or use without specific written authorization
of Emutex Ltd. is strictly forbidden.
 */

/*
Copyright 2017 (c) Analog Devices, Inc.

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
  - Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
  - Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
  - Neither the name of Analog Devices, Inc. nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.
  - The use of this software may or may not infringe the patent rights
    of one or more patent holders. This license does not release you
    from the requirement that you obtain separate licenses from these
    patent holders to use this software.
  - Use of the software either in source or binary form, must be run
    on or directly connected to an Analog Devices Inc. component.

THIS SOFTWARE IS PROVIDED BY ANALOG DEVICES "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, NON-INFRINGEMENT,
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL ANALOG DEVICES BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, INTELLECTUAL PROPERTY RIGHTS, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

/*!
 ******************************************************************************
 * @file:   adi_sense_api.h
 * @brief:  ADSNS1000 Host Library Application Programming Interface (API)
 *-----------------------------------------------------------------------------
 */

#ifndef __ADI_SENSE_1000_API_H__
#define __ADI_SENSE_1000_API_H__

#include "inc/adi_sense_types.h"
#include "inc/adi_sense_config_types.h"
#include "inc/adi_sense_platform.h"
#include "adi_sense_1000_config.h"
#include "adi_sense_1000_lut_data.h"

/*! @ingroup ADISENSE_Api */

/*! @defgroup ADSNS1000_Api ADSNS1000 Host Library API
 *  ADSNS1000 device-specific API function prototypes.
 *  These are supplementary to the common ADISENSE Host Library API.
 *  @{
 */

#ifdef __cplusplus
extern "C" {
#endif

/*!
 * @brief Read one or more device registers at the specified register address.
 *
 * @param[in]  hDevice    ADISENSE device context handle
 * @param[in]  nAddress   Register map address to read from
 * @param[out] pData      Pointer to return the register map data
 * @param[in]  nLength    Number of bytes of data to read from the register map
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Provides direct byte-level read access to the device register map.
 *          The size and format of the register(s) must be known.
 *
 * @note Reads from special "keyhole" or "FIFO" registers will be handled
 *       according to documentation for those registers.
 */
ADI_SENSE_RESULT adi_sense_1000_ReadRegister(
    ADI_SENSE_DEVICE_HANDLE    const hDevice,
    uint16_t                   const nAddress,
    void                     * const pData,
    unsigned                   const nLength);

/*!
 * @brief Write one or more device registers at the specified register address.
 *
 * @param[in]  hDevice    ADISENSE device context handle
 * @param[in]  nAddress   Register map address to read from
 * @param[out] pData      Pointer to return the register map data
 * @param[in]  nLength    Number of bytes of data to read from the register map
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Provides direct byte-level write access to the device register map.
 *          The size and format of the register(s) must be known.
 *
 * @note Writes to read-only registers will be ignored by the device.
 * @note Writes to special "keyhole" registers will be handled according to
 *       documentation for those registers.
 */
ADI_SENSE_RESULT adi_sense_1000_WriteRegister(
    ADI_SENSE_DEVICE_HANDLE    const hDevice,
    uint16_t                   const nAddress,
    void                     * const pData,
    unsigned                   const nLength);

/*!
 * @brief Update power configuration settings on the device.
 *
 * @param[in] hDevice      ADISENSE device context handle
 * @param[in] pPowerConfig Power configuration details
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Translates configuration details provided into device-specific
 *          register settings and updates device configuration registers.
 *
 * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
 */
ADI_SENSE_RESULT adi_sense_1000_SetPowerConfig(
    ADI_SENSE_DEVICE_HANDLE hDevice,
    ADI_SENSE_1000_POWER_CONFIG *pPowerConfig);

/*!
 * @brief Update measurement configuration settings on the device.
 *
 * @param[in] hDevice            ADISENSE device context handle
 * @param[in] pMeasurementConfig Measurement configuration details
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Translates configuration details provided into device-specific
 *          register settings and updates device configuration registers.
 *
 * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
 */
ADI_SENSE_RESULT adi_sense_1000_SetMeasurementConfig(
    ADI_SENSE_DEVICE_HANDLE hDevice,
    ADI_SENSE_1000_MEASUREMENT_CONFIG *pMeasurementConfig);

/*!
 * @brief Update diagnostics configuration settings on the device.
 *
 * @param[in] hDevice            ADISENSE device context handle
 * @param[in] pDiagnosticsConfig Diagnostics configuration details
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Translates configuration details provided into device-specific
 *          register settings and updates device configuration registers.
 *
 * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
 */
ADI_SENSE_RESULT adi_sense_1000_SetDiagnosticsConfig(
    ADI_SENSE_DEVICE_HANDLE hDevice,
    ADI_SENSE_1000_DIAGNOSTICS_CONFIG *pDiagnosticsConfig);

/*!
 * @brief Update channel configuration settings for a specific channel.
 *
 * @param[in] hDevice        ADISENSE device context handle
 * @param[in] eChannelId     Selects the channel to be updated
 * @param[in] pChannelConfig Channel configuration details
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Translates configuration details provided into device-specific
 *          register settings and updates device configuration registers.
 *          Allows individual channel configuration details to be dynamically
 *          adjusted without rewriting the full device configuration.
 *
 * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
 */
ADI_SENSE_RESULT adi_sense_1000_SetChannelConfig(
    ADI_SENSE_DEVICE_HANDLE hDevice,
    ADI_SENSE_1000_CHANNEL_ID eChannelId,
    ADI_SENSE_1000_CHANNEL_CONFIG *pChannelConfig);

/*!
 * @brief Update number of measurements-per-cycle for a specific channel.
 *
 * @param[in] hDevice               ADISENSE device context handle
 * @param[in] eChannelId            Selects the channel to be updated
 * @param[in] nMeasurementsPerCycle Specifies the number of measurements to be
 *                                  obtained from this channel in each
 *                                  measurement cycle.  Set as 0 to disable the
 *                                  channel (omit from measurement cycle).
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Translates configuration details provided into device-specific
 *          register settings and updates device configuration registers.
 *          Allows individual channels to be dynamically enabled/disabled, and
 *          measurements-per-cycle to be adjusted.
 *
 * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
 */
ADI_SENSE_RESULT adi_sense_1000_SetChannelCount(
    ADI_SENSE_DEVICE_HANDLE hDevice,
    ADI_SENSE_1000_CHANNEL_ID eChannelId,
    uint32_t nMeasurementsPerCycle);

/*!
 * @brief Update priority level for a specific channel.
 *
 * @param[in] hDevice    ADI Sense device context handle
 * @param[in] eChannelId Selects the channel to be updated
 * @param[in] ePriority  Specifies the channel priority level
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Translates configuration details provided into device-specific
 *          register settings and updates device configuration registers.
 *          Allows individual channels to be dynamically re-prioritised.
 *
 * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
 */
ADI_SENSE_RESULT adi_sense_1000_SetChannelPriority(
    ADI_SENSE_DEVICE_HANDLE hDevice,
    ADI_SENSE_1000_CHANNEL_ID eChannelId,
    ADI_SENSE_1000_CHANNEL_PRIORITY ePriority);

/*!
 * @brief Update the measurement threshold limits for a specified channel.
 *
 * @param[in] hDevice             ADISENSE device context handle
 * @param[in] eChannelId          Selects the channel to be updated
 * @param[in] fHighThresholdLimit Optional maximum threshold value for each
 *                                processed sample, to be checked prior to
 *                                publishing.  A channel ALERT condition is
 *                                raised if the processed value is higher than
 *                                this threshold.  Set to NaN if not required.
 * @param[in] fLowThresholdLimit  Optional minimum threshold value for each
 *                                processed sample, to be checked prior to
 *                                publishing.  A channel ALERT condition is
 *                                raised if the processed value is lower than
 *                                this threshold.  Set to NaN if not required.
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Translates configuration details provided into device-specific
 *          register settings and updates device configuration registers.
 *          Allows individual channel thresholds to be dynamically adjusted.
 *
 * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
 */
ADI_SENSE_RESULT adi_sense_1000_SetChannelThresholdLimits(
    ADI_SENSE_DEVICE_HANDLE hDevice,
    ADI_SENSE_1000_CHANNEL_ID eChannelId,
    float32_t fHighThresholdLimit,
    float32_t fLowThresholdLimit);


/*!
 * @brief Set a sensor specific parameter for a specified channel.
 *
 * @param[in] hDevice             ADI Sense device context handle
 * @param[in] eChannelId          Selects the channel to be updated
 * @param[in] fSensorParam        Sensor specific parameter
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Translates configuration details provided into device-specific
 *          register settings and updates device configuration registers.
 *          Allows optional sensor-specific parameter to be specified
 *
 * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
 */
ADI_SENSE_RESULT adi_sense_1000_SetSensorParameter(
     ADI_SENSE_DEVICE_HANDLE hDevice,
     ADI_SENSE_1000_CHANNEL_ID eChannelId,
     float32_t fSensorParam);
/*!
 * @brief Update the extra settling time for a specified channel.
 *
 * @param[in] hDevice       ADISENSE device context handle
 * @param[in] eChannelId    Selects the channel to be updated
 * @param[in] nSettlingTime A minimum settling time is applied internally for
 *                          each channel, based on the sensor type.  However,
 *                          additional settling time (microseconds) can
 *                          optionally be specified here.  Set to 0 if not
 *                          required.
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Translates configuration details provided into device-specific
 *          register settings and updates device configuration registers.
 *          Allows individual channel settling times to be dynamically adjusted.
 *
 * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
 */
ADI_SENSE_RESULT adi_sense_1000_SetChannelSettlingTime(
    ADI_SENSE_DEVICE_HANDLE hDevice,
    ADI_SENSE_1000_CHANNEL_ID eChannelId,
    uint32_t nSettlingTime);

/*!
 * @brief Assemble a list of separate Look-Up Tables into a single buffer
 *
 * @param[out] pLutBuffer    Pointer to the Look-Up Table data buffer where
 *                           the assembled Look-Up Table data will be placed
 * @param[in] nLutBufferSize Allocated size, in bytes, of the output data buffer
 * @param[in] nNumTables     Number of tables to add to the Look-Up Table buffer
 * @param[in] ppDesc         Array of pointers to the table descriptors to be added
 * @param[in] ppData         Array of pointers to the table data to be added
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details This utiliity function fills the Look-up Table header fields; then
 *          walks through the array of individual table descriptor and data
 *          pointers provided, appending (copying) each one to the Look-Up Table
 *          data buffer. The length and crc16 fields of each table descriptor
 *          will be calculated and filled by this function, but other fields in
 *          the descriptor structure must be filled by the caller beforehand.
 *
 * @note    The assembled LUT data buffer filled by this function can then be
 *          written to the device memory using @ref adi_sense_1000_SetLutData.
 */
ADI_SENSE_RESULT adi_sense_1000_AssembleLutData(
    ADI_SENSE_1000_LUT                  * pLutBuffer,
    unsigned                              nLutBufferSize,
    unsigned                        const nNumTables,
    ADI_SENSE_1000_LUT_DESCRIPTOR * const ppDesc[],
    ADI_SENSE_1000_LUT_TABLE_DATA * const ppData[]);

/*!
 * @brief Write Look-Up Table data to the device memory
 *
 * @param[in]  hDevice  ADISENSE device context handle
 * @param[out] pLutData Pointer to the Look-Up Table data structure
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Validates the Look-Up Table data format and loads it into
 *          device memory via dedicated keyhole registers.
 *
 * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
 */
ADI_SENSE_RESULT adi_sense_1000_SetLutData(
    ADI_SENSE_DEVICE_HANDLE    const hDevice,
    ADI_SENSE_1000_LUT       * const pLutData);

/*!
 * @brief Write Look-Up Table raw data to the device memory
 *
 * @param[in]  hDevice  ADISENSE device context handle
 * @param[out] pLutData Pointer to the Look-Up Table raw data structure
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details This can be used instead of @ref adi_sense_1000_SetLutData for
 *          loading LUT data from the alternative raw data format.  See
 *          @ref adi_sense_1000_SetLutData for more information.
 *
 * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
 */
ADI_SENSE_RESULT adi_sense_1000_SetLutDataRaw(
    ADI_SENSE_DEVICE_HANDLE    const hDevice,
    ADI_SENSE_1000_LUT_RAW   * const pLutData);

/*!
 * @brief Get the number of samples available when DATAREADY status is asserted.
 *
 * @param[in]  hDevice               ADISENSE device context handle
 * @param[in]  eMeasurementMode      Must be set to the same value used for @ref
 *                                   adi_sense_StartMeasurement().
 * @param[out] peOperatingMode       Pointer to return the configured operating mode
 * @param[out] peDataReadyMode       Pointer to return the configured data publishing mode
 * @param[out] pnSamplesPerDataready Pointer to return the calculated number of samples
 *                                   available when DATAREADY is asserted
 * @param[out] pnSamplesPerCycle     Pointer to return the calculated number of samples
 *                                   produced per measurement cycle
 * @param[out] pnBytesPerSample      Pointer to return the size, in bytes, of each sample
 *
 * @return Status
 *         - #ADI_SENSE_SUCCESS Call completed successfully.
 *
 * @details Examines the current configuration settings in the device registers
 *          to calculate the number of samples available whenever the DATAREADY
 *          signal is asserted, along with other related information.  This may
 *          be used to allocate buffers to store samples and to determine how
 *          many samples to retrieve whenever the DATAREADY status is asserted.
 */
ADI_SENSE_RESULT adi_sense_1000_GetDataReadyModeInfo(
    ADI_SENSE_DEVICE_HANDLE         const hDevice,
    ADI_SENSE_MEASUREMENT_MODE      const eMeasurementMode,
    ADI_SENSE_1000_OPERATING_MODE * const peOperatingMode,
    ADI_SENSE_1000_DATAREADY_MODE * const peDataReadyMode,
    uint32_t                      * const pnSamplesPerDataready,
    uint32_t                      * const pnSamplesPerCycle,
    uint8_t                       * const pnBytesPerSample);

#ifdef __cplusplus
}
#endif

/*!
 * @}
 */

#endif /* __ADI_SENSE_1000_API_H__ */