/**
 * Copyright (c) 2017 - 2018, Nordic Semiconductor ASA
 * 
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 * 
 * 1. Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 * 
 * 2. Redistributions in binary form, except as embedded into a Nordic
 *    Semiconductor ASA integrated circuit in a product or a software update for
 *    such product, 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.
 * 
 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
 *    contributors may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 * 
 * 4. This software, with or without modification, must only be used with a
 *    Nordic Semiconductor ASA integrated circuit.
 * 
 * 5. Any software provided in binary form under this license must not be reverse
 *    engineered, decompiled, modified and/or disassembled.
 * 
 * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 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
 *
 * @defgroup nrf_twi_sensor TWI Sensor module.
 * @{
 * @ingroup app_common
 */

#ifndef NRF_TWI_SENSOR_H
#define NRF_TWI_SENSOR_H

#include "nrf_twi_mngr.h"
#include "nrf_balloc.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Internal write operation buffer length.
 *
 * Defines how many bytes can be stored internally.
 * 16 bytes were selected so that nrf_twi_sensor_write_cmd_t size
 * matches nrf_twi_sensor_read_cmd_t size.
 */
#define NRF_TWI_SENSOR_SEND_BUF_SIZE   16

/**
 * @brief Register read callback prototype.
 *
 * @param[in] result            Return error code from TWI manager and underlying drivers.
 * @param[in] p_register_data   Pointer to register value.
 */
typedef void (* nrf_twi_sensor_reg_cb_t)(ret_code_t result, void * p_register_data);


/**
 * @brief Structure holding sensor instance
 */
typedef struct
{
    nrf_twi_mngr_t const * const p_twi_mngr;
    nrf_balloc_t const * const   p_pool;


} nrf_twi_sensor_t;

/**
 * @brief Struct describing sensor read command.
 *
 * @note For internal use only.
 */
typedef struct
{
    uint8_t                     reg_address;
    nrf_twi_mngr_transfer_t     transfers[2];
    nrf_twi_mngr_transaction_t  transaction;
    nrf_twi_sensor_reg_cb_t     user_cb;
    nrf_twi_sensor_t const *    p_instance;
} nrf_twi_sensor_read_cmd_t;

/**
 * @brief Struct describing sensor write command.
 *
 * @note  For internal use only.
 */
typedef struct
{
    uint8_t                     send_msg[NRF_TWI_SENSOR_SEND_BUF_SIZE];
    nrf_twi_mngr_transfer_t     transfer;
    nrf_twi_mngr_transaction_t  transaction;
    nrf_twi_sensor_t const *    p_instance;
} nrf_twi_sensor_write_cmd_t;

/**
 * @brief Union for sensor commands. Needed in buffer definition.
 *
 * @note For internal use only.
 */
typedef union
{
    nrf_twi_sensor_read_cmd_t  read;
    nrf_twi_sensor_write_cmd_t write;
} nrf_twi_sensor_cmd_t;


/**
 * @brief Macro creating common twi sensor instance.
 *
 * Data in structure is used for basic communication with sensors.
 * THere should be one instance per TWI bus.
 *
 * @param[in] twi_sensor_name   TWI common sensor instance name.
 * @param[in] p_nrf_twi_mngr    Pointer to TWI Manager instance. @ref NRF_TWI_MNGR_DEF
 * @param[in] msg_buff_size     Size of buffer used in communication
 *
 * @note Buffer size should be less or equal to TWI manager queue size.
 *       Minimum buffer size can be found after checking utilization of sensor buffer.
 */
#define NRF_TWI_SENSOR_DEF(twi_sensor_name, p_nrf_twi_mngr, msg_buff_size) \
    NRF_BALLOC_DEF(CONCAT_2(twi_sensor_name,_pool), sizeof(nrf_twi_sensor_cmd_t), msg_buff_size);\
    static nrf_twi_sensor_t twi_sensor_name =                                                    \
    {                                                                                            \
        .p_twi_mngr = p_nrf_twi_mngr,                                                            \
        .p_pool     = &CONCAT_2(twi_sensor_name,_pool)                                           \
    }

/**
 * @brief Macro for defining TWI manager read transfer.
 *
 * @note  For internal use only.
 */
#define NRF_TWI_SENSOR_READ(p_reg_addr, p_buffer, byte_cnt) \
    NRF_TWI_MNGR_WRITE(0x00, p_reg_addr, 1,        NRF_TWI_MNGR_NO_STOP), \
    NRF_TWI_MNGR_READ (0x00, p_buffer,   byte_cnt, 0)

/**
 * @brief Macro for defining TWI manager write transfer.
 *
 * @note  For internal use only.
 */
#define NRF_TWI_SENSOR_WRITE(p_buffer, byte_cnt) \
    NRF_TWI_MNGR_WRITE(0x00, p_buffer, byte_cnt, 0)


/**
 * @brief Macro for assigning sensor address to transfers.
 *
 * @param[in] _transfers   Transfers array.
 * @param[in] _sensor_addr Desired sensor address.
 *
 * @note  For internal use only.
 */
#define NRF_TWI_SENSOR_ADDRESS_SET(_transfers, _sensor_addr)                                \
    for (uint8_t i = 0; i < ARRAY_SIZE(_transfers); i++)                                    \
    {                                                                                       \
        if (i % 2 == 0)                                                                     \
        {                                                                                   \
            transfers[i].operation = NRF_TWI_MNGR_WRITE_OP(_sensor_addr);                   \
        }                                                                                   \
        else                                                                                \
        {                                                                                   \
            transfers[i].operation = NRF_TWI_MNGR_READ_OP(_sensor_addr);                    \
        }                                                                                   \
    }

/**
 * @brief Macro for setting parameters in sensor register.
 *
 * @param[in,out] _register Register to be altered.
 * @param[in]     _msk      Parameter mask.
 * @param[in]     _pos      Parameter position.
 * @param[in]     _val      Parameter value to be set.
 */
#define NRF_TWI_SENSOR_REG_SET(_register, _msk, _pos, _val)   \
    _register &= ~(_msk);                                  \
    _register |= ((_msk) & ((_val) << (_pos)))


/**
 * @brief Macro for getting parameters from sensor register.
 *
 * @param[in] _register Register to be processed.
 * @param[in] _msk      Parameter mask.
 * @param[in] _pos      Parameter position.
 *
 * @note For usage with registers read using nrf_twi_sensor_register_read function.
 *
 * @return  Parameter value
 */
#define NRF_TWI_SENSOR_REG_VAL_GET(_register, _msk, _pos) \
    (((_register) & (_msk)) >> (_pos))

/**
 * @brief Function for initialization of sensor common instance.
 *
 * @note TWI Manager should be initialized before @ref nrf_twi_mngr_init
 * @param[in] p_twi_sensor Pointer to sensor common instance.
 *
 * @return Error code from nrf_balloc @ref nrf_balloc_init
 */
ret_code_t nrf_twi_sensor_init(nrf_twi_sensor_t * p_twi_sensor);

/**
 * @brief Function for reading sensor register.
 *
 * @param[in]  p_instance       Pointer to sensor instance.
 * @param[in]  sensor_addr      Sensor address.
 * @param[in]  reg_address      Register address.
 * @param[in]  user_cb          User callback.
 * @param[out] p_data           Pointer to data save location.
 * @param[in]  length           Number of bytes to read.
 *
 * @retval NRF_ERROR_NO_MEM         If there is no memory in sensor buffer
 * @retval NRF_SUCCESS              If the operation was successful.
 * @retval other                    Error code from TWI manager @ref nrf_twi_mngr_schedule.
 */
ret_code_t nrf_twi_sensor_reg_read(nrf_twi_sensor_t const * p_instance,
                                   uint8_t                  sensor_addr,
                                   uint8_t                  reg_address,
                                   nrf_twi_sensor_reg_cb_t  user_cb,
                                   uint8_t *                p_data,
                                   uint8_t                  length);

/**
 * @brief Function for writing to sensor.
 *
 * @param[in] p_instance    Pointer to sensor instance.
 * @param[in] sensor_addr   Sensor address.
 * @param[in] p_data        Pointer to data to be written.
 * @param[in] length        Number of bytes to write.
 * @param[in] copy_flag     If true, p_data is copied into internal static buffer.
 *
 * @note   Most of the time, to write to sensors register, first byte in p_data has to be
 *         register address.
 *
 * @retval NRF_ERROR_NO_MEM         If there is no memory in sensor buffer
 * @retval NRF_ERROR_INVALID_LENGTH If trying to copy more bytes than
 *                                  NRF_TWI_SENSOR_SEND_BUF_SIZE.
 * @retval NRF_SUCCESS              If the operation was successful.
 * @retval other                    Error code from TWI manager @ref nrf_twi_mngr_schedule.
 */
ret_code_t nrf_twi_sensor_write(nrf_twi_sensor_t const * p_instance,
                                uint8_t                  sensor_addr,
                                uint8_t const *          p_data,
                                uint8_t                  length,
                                bool                     copy_flag);
                                
/**
 * @brief Function for writing to sensor register.
 *
 * @param[in] p_instance    Pointer to sensor instance.
 * @param[in] sensor_addr   Sensor address.
 * @param[in] reg_address   Register address.
 * @param[in] p_data        Pointer to data to be written.
 * @param[in] length        Number of bytes to write.
 *
 * @note   Data is copied into internal buffer.
 *         Length has to be less than NRF_TWI_SENSOR_SEND_BUF_SIZE.
 *
 * @retval NRF_ERROR_NO_MEM         If there is no memory in sensor buffer
 * @retval NRF_ERROR_INVALID_LENGTH If trying to copy more bytes than
 *                                  NRF_TWI_SENSOR_SEND_BUF_SIZE - 1.
 *                                  One byte reserved for register address.
 * @retval NRF_SUCCESS              If the operation was successful.
 * @retval other                    Error code from TWI manager @ref nrf_twi_mngr_schedule.
 */
ret_code_t nrf_twi_sensor_reg_write(nrf_twi_sensor_t const * p_instance,
                                    uint8_t                  sensor_addr,
                                    uint8_t                  reg_address,
                                    uint8_t *                p_data,
                                    uint8_t                  length);

/**
 * @brief Function for getting maximum utilization of sensor buffer.
 *
 * @param[in] p_twi_sensor Pointer to sensor buffer.
 *
 * @return Maximum utilization.
 */
__STATIC_INLINE uint8_t nrf_twi_sensor_max_util_get(nrf_twi_sensor_t const * p_twi_sensor);
#ifndef SUPPRESS_INLINE_IMPLEMENTATION
__STATIC_INLINE uint8_t nrf_twi_sensor_max_util_get(nrf_twi_sensor_t const * p_twi_sensor)
{
    return nrf_balloc_max_utilization_get(p_twi_sensor->p_pool);
}
#endif //SUPPRESS_INLINE_IMPLEMENTATION

#ifdef __cplusplus
}
#endif

#endif // NRF_SENSOR_COMMON_H

/** @} */
