///
/// @file i2cx-mcc.h
/// @authors k. headley
/// @date 05 dec 2019

/// I2C  definitions for MCC  implementation

/// @sa doxygen-examples.c for more examples of Doxygen markup


/////////////////////////
// Terms of use
/////////////////////////
/*
 Copyright Information
  
 Copyright 2002-2019 MBARI
 Monterey Bay Aquarium Research Institute, all rights reserved.
 
 Terms of Use
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 3 of the License, or
 (at your option) any later version. You can access the GPLv3 license at
 http://www.gnu.org/licenses/gpl-3.0.html
 
 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
 (http://www.gnu.org/licenses/gpl-3.0.html)
 
 MBARI provides the documentation and software code "as is", with no warranty,
 express or implied, as to the software, title, non-infringement of third party
 rights, merchantability, or fitness for any particular purpose, the accuracy of
 the code, or the performance or results which you may obtain from its use. You
 assume the entire risk associated with use of the code, and you agree to be
 responsible for the entire cost of repair or servicing of the program with
 which you are using the code.
 
 In no event shall MBARI be liable for any damages, whether general, special,
 incidental or consequential damages, arising out of your use of the software,
 including, but not limited to, the loss or corruption of your data or damages
 of any kind resulting from use of the software, any prohibited use, or your
 inability to use the software. You agree to defend, indemnify and hold harmless
 MBARI and its officers, directors, and employees against any claim, loss,
 liability or expense, including attorneys' fees, resulting from loss of or
 damage to property or the injury to or death of any person arising out of the
 use of the software.
 
 The MBARI software is provided without obligation on the part of the
 Monterey Bay Aquarium Research Institute to assist in its use, correction,
 modification, or enhancement.
 
 MBARI assumes no responsibility or liability for any third party and/or
 commercial software required for the database or applications. Licensee agrees
 to obtain and maintain valid licenses for any additional third party software
 required.
 */

// Always do this
#ifndef I2CX_MCC_H
#define I2CX_MCC_H

/////////////////////////
// Includes 
/////////////////////////
#ifdef WITH_PIC24F_CURIOSITY
#include "bbcommon.h"
#endif // WITH_PIC24F_CURIOSITY
#include <xc.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include "libpic30.h"
#include "pic24.h"
#include "mcc_generated_files/i2c1.h"

/////////////////////////
// Macros
/////////////////////////

///@def TRB_BUFFER_BYTES
///@brief MCC transaction data buffer size
#define TRB_BUFFER_BYTES 8

///@def TRB_LEN_VALID
///@brief validate buffer size
#define TRB_LEN_VALID(nbytes) (nbytes<=TRB_BUFFER_BYTES ? true : false)

/////////////////////////
// Type Definitions
/////////////////////////

///@typedef enum i2c_status_t
///@brief I2C generic transaction status values
/// NOTE: must match definition in MCC headers i2c<n>.h
typedef enum
{
    I2C_MESSAGE_FAIL,
    I2C_MESSAGE_PENDING,
    I2C_MESSAGE_COMPLETE,
    I2C_STUCK_START,
    I2C_MESSAGE_ADDRESS_NO_ACK,
    I2C_DATA_NO_ACK,
    I2C_LOST_STATE
} i2c_status_t;

///@typedef struct i2c_trb_s i2c_trb_t
///@brief I2C generiic transaction request block
typedef struct i2c_trb_s{
    /// @var i2c_trb_s::address
    /// @brief i2c device address
    /// Bits <10:1> are the 10 bit address.
    i2c_addr_t  address;
    /// @var i2c_trb_s::length
    /// @brief i2c request length (bytes)
    /// the # of bytes in the buffer
    uint8_t   length;
    /// @var i2c_trb_s::pbuffer
    /// @brief i2c data buffer pointer
    ///  a pointer to a buffer of length bytes
    uint8_t   *pbuffer;
}i2c_trb_t;

// PIC24 MCC I2C bus (state)
#pragma pack(push,1)
///@typedef struct i2cbus_s bus_id
///@brief PIC24  I2C bus
typedef struct i2c_mcc_bus_s{
    /// @var i2cbus_s::hnd
    /// @brief i2c handle, index into function table, resources
    uint16_t hnd;
    /// @var i2cbus_s::trb
    /// @brief i2c transaction resource block (generic)
    i2c_trb_t trb;
    /// @var i2cbus_s::status
    /// @brief i2c status (generic)
    i2c_status_t status;
    /// @var i2cbus_s::flags
    /// @brief i2c flags
    i2cx_flags_t flags;
}i2c_mcc_bus_t;
#pragma pack(pop)

///@typedef void (* i2c_init_fn)(void)
///@brief I2C API generic init function
typedef void (* i2c_init_fn)(void);
///@typedef void (* i2c_primary_write_fn)(uint8_t *pdata, uint8_t length, i2c_addr_t address, i2c_status_t *pstatus)
///@brief I2C API generic write function
typedef void (* i2c_primary_write_fn)(uint8_t *pdata, uint8_t length, i2c_addr_t address, i2c_status_t *pstatus);
///@typedef void (* i2c_primary_read_fn)(uint8_t *pdata, uint8_t length, i2c_addr_t address, i2c_status_t *pstatus)
///@brief I2C API generic read function
typedef void (* i2c_primary_read_fn)(uint8_t *pdata, uint8_t length, i2c_addr_t address, i2c_status_t *pstatus);
///@typedef void (* i2c_primary_trb_insert_fn)(uint8_t count, i2c_trb_t *ptrb_list, i2c_status_t *pstatus)
///@brief I2C API generic TRB insert build function
typedef void (* i2c_primary_trb_insert_fn)(uint8_t count, i2c_trb_t *ptrb_list, i2c_status_t *pstatus);
///@typedef void (* i2c_primary_read_trb_build_fn)(i2c_trb_t *ptrb, uint8_t *pdata, uint8_t length, i2c_addr_t address)
///@brief I2C API generic read/TRB build function
typedef void (* i2c_primary_read_trb_build_fn)(i2c_trb_t *ptrb, uint8_t *pdata, uint8_t length, i2c_addr_t address);
///@typedef void (* i2c_primary_write_trb_build_fn)(i2c_trb_t *ptrb, uint8_t *pdata, uint8_t length, i2c_addr_t address)
///@brief I2C API generic write/TRB build function
typedef void (* i2c_primary_write_trb_build_fn)(i2c_trb_t *ptrb, uint8_t *pdata, uint8_t length, i2c_addr_t address);
///@typedef void (* i2c_queue_is_empty_fn)(void)
///@brief I2C API generic queue empty check function
typedef void (* i2c_queue_is_empty_fn)(void);
///@typedef void (* i2c_queue_is_full_fn)(void)
///@brief I2C API generic queue full check function
typedef void (* i2c_queue_is_full_fn)(void);


/////////////////////////
// Exports
/////////////////////////

#endif // THIS_FILE
