I2CTarget.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023, Texas Instruments Incorporated
 * 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 Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 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       I2CTarget.h
 *
 *  @brief      I2CTarget driver interface
 *
 *  To use the I2CTarget driver, ensure that the correct driver library for your
 *  device is linked in and include this header file as follows:
 *  @code
 *  #include <ti/drivers/I2CTarget.h>
 *  @endcode
 *
 *  # Overview
 *
 *  The I2CTarget driver operates the I2C peripheral as a target on an I2C bus.
 *  The I2CTarget driver is event driven. When an  @ref I2CTarget_Event occurs,
 *  the I2CTarget driver will call a user-specified callback function
 *  (from HWI context). It is the user-specified callback's responsibility to
 *  process the @ref I2CTarget_Event events, and to manipulate and interperet
 *  the data.
 *
 *  <hr>
 *  @anchor ti_drivers_I2CTARGET_Usage
 *  # Usage
 *
 *  This documentation provides a basic @ref ti_drivers_I2CTARGET_Synopsis
 *  "usage summary" and a set of @ref ti_drivers_I2CTARGET_Examples "examples"
 *  in the form of commented code fragments.  Detailed descriptions of the
 *  APIs are provided in subsequent sections.
 *
 *  @anchor ti_drivers_I2CTARGET_Synopsis
 *  ## Synopsis
 *  @anchor ti_drivers_I2CTARGET_Synopsis_Code
 *  @code
 *  // Import the I2CTarget driver definitions
 *  #include <ti/drivers/I2CTarget.h>
 *
 *  // Define own I2C bus address
 *  #define OWN_ADDRESS     42
 *
 *  // Initialize I2CTarget driver
 *  I2CTarget_init();
 *
 *  // Initialize I2CTarget parameters
 *  I2CTarget_Params params;
 *  I2CTarget_Params_init(&params);
 *  params.eventCallbackFxn = myEventCallbackFunction;
 *  params.targetAddress = OWN_ADDRESS;
 *
 *  // Open the I2CTarget driver
 *  I2CTarget_Handle i2c;
 *  i2c = I2CTarget_open(CONFIG_I2CTARGET_0, &params);
 *  if (i2C == NULL) {
 *      // Error opening I2CTarget
 *      while (1) {}
 *  }
 *
 *  // Start I2C Target operation. The driver will send
 *  // events to the user-specified event callback function
 *  I2CTarget_start(i2c);
 *
 *  // Transmitting and receiving bytes is handled by the
 *  // user-specified callback function. It is up to the user
 *  // to implement the appropriate state machine for its I2C
 *  // protocol.
 *
 *  // Stop operation. The I2CTarget driver will no longer trigger
 *  // events and the device can enter low-power modes.
 *  I2CTarget_stop(i2c);
 *
 *  // Close the I2CTarget driver
 *  I2CTarget_close(i2c);
 *  @endcode
 *
 *  <hr>
 *  @anchor ti_drivers_I2CTARGET_Examples
 *  # Examples
 *  @anchor ti_drivers_I2CTARGET_Example_open
 *  ## Opening the I2CTarget Driver
 *
 *  Opening a I2CTarget requires four steps:
 *  1.  Create and initialize a @ref I2CTarget_Params structure.
 *  2.  Fill in the desired parameters.
 *  3.  Call @ref I2CTarget_open(), passing the index of the I2C in the
 *      @ref I2CTarget_config structure, and the address of the @ref I2CTarget_Params
 *      structure.  The I2C peripheral instance is specified by the index in
 *      the @ref I2CTarget_config structure.
 *  4.  Check that the I2CTarget handle returned by @ref I2CTarget_open() is non-NULL,
 *      and save it.  The handle will be used to start and stop I2C Target operation
 *      of the I2C instance you just opened.
 *
 * @code
 *  I2CTarget_Handle i2c;
 *  I2CTarget_Params params;
 *  params.eventCallbackFxn = myEventCallbackFunction;
 *  params.targetAddress = 42;
 *
 *  i2c = I2CTarget_open(CONFIG_I2CTARGET_0, NULL);
 *
 *  if (i2c == NULL) {
 *      // Error opening I2CTarget
 *      while (1) {}
 *  }
 * @endcode
 *
 *  Only one I2CTarget index can be used at a time; calling @ref I2CTarget_open() a
 *  second time with the same index previosly passed to @ref I2CTarget_open() will
 *  result in an error.  You can, though, re-use the index if the instance is closed
 *  via @ref I2CTarget_close().
 *  In the previous example code, CONFIG_I2CTARGET_0 is passed to @ref I2CTarget_open().
 *  This macro is defined in the example's ti_drivers_config.h file.
 *
 *  @anchor ti_drivers_I2CTARGET_Example_start_stop_operation
 *  ## Start/Stop I2C Operation #
 *  The I2CTarget driver will start operation when calling @ref I2CTarget_start().
 *  It is the application's responsibility to process all incoming
 *  @ref I2CTarget_Event events in the @ref I2CTarget_Params.eventCallbackFxn and
 *  implement the necessary state machine for the I2C protocol used.
 *
 *  @code
 *  I2CTarget_start(i2cTargetHandle);
 *  @endcode
 *
 *  The I2CTarget driver operation is stopped by calling @ref I2CTarget_stop().
 *
 *  @code
 *  I2CTarget_stop(i2cTargetHandle);
 *  @endcode
 *
 *  @anchor ti_drivers_I2CTARGET_Example_receive_byte
 *  ## Transferring data
 *  This example shows a simplified example on how to transmit and receive data.
 *
 *  @code
 *  // No command input
 *  #define NO_COMMAND          0x00
 *  // Define command to reset value of txData
 *  #define CMD_RESET_TXDATA    0x55
 *
 *  // Variable storing data to transmit
 *  volatile uint8_t txData = 0;
 *
 *  // Variable storing command received from an I2C controller
 *  volatile uint8_t command = 0;
 *
 *  // User callback function
 *  int_fast16_t targetCallbackFxn(I2CTarget_Handle handle, I2CTarget_Event event, uint8_t *val) {
 *      if (event == I2CTarget_Event_WRITE_REQUESTED)
 *      {
 *          // Early event (before data is received) that the controller wants
 *          //  to write a byte to us (target-receiver).
 *          // This event may be used to set up receive buffers, or other
 *          // preparations.
 *      }
 *
 *      if (event == I2CTarget_Event_WRITE_RECEIVED) {
 *          // Controller has written a byte to the target (target-receiver)
 *          command = *data;
 *
 *          // Tell driver data has been read
 *          return I2CTarget_STATUS_SUCCESS;
 *      }
 *
 *      if (event  == I2CTarget_Event_READ_REQUESTED || event == I2CTarget_Event_READ_PROCESSED) {
 *          // Controller wants to read from target (target-transmitter)
 *          *data = txData++;
 *
 *          // Tell driver that data has been provided.
 *          return I2CTarget_STATUS_SUCCESS;
 *
 *          // If the user callback does not have data, return
 *          // I2CTarget_STATUS_ERROR and the I2CTarget driver will
 *          // NACK the request (if supported by the device-specific driver implementation).
 *      }
 *
 *      if (event == I2CTarget_Event_STOP) {
 *          // Stop condition received. Here we could, for example, reset
 *          // our I2C protocol state machine.
 *      }
 *
 *      // Return success by default
 *      return I2CTarget_STATUS_SUCCESS;
 * }
 *
 *  // Main thread
 *  void *mainThread(void *arg0) {
 *      // Call driver init functions
 *      I2CTarget_init();
 *
 *      // Open I2CTarget driver
 *      I2CTarget_Params params;
 *      I2CTarget_Params_init(&params);
 *      params.eventCallbackFxn = targetCallbackFxn;
 *      params.targetAddress = 42;
 *      I2CTarget_Handle handle = I2CTarget_open(CONFIG_I2CTARGET_0, &params);
 *      if (handle == NULL) {
 *          // Error
 *          while (1) {}
 *      }
 *
 *      // Start operation
 *      I2CTarget_start(handle);
 *
 *      // Data transfers happens in targetCallbackFxn
 *      while (1) {
 *          if (command == CMD_RESET_TXDATA) {
 *              command = NO_COMMAND;
 *             txData = 0;
 *          }
 *      }
 *  }
 *  @endcode
 *
 *  <hr>
 *  @anchor ti_drivers_I2CTarget_Configuration
 *  # Configuration
 *
 *  Refer to the @ref driver_configuration "Driver's Configuration" section
 *  for driver configuration information.
 *  <hr>
 *
 *  ============================================================================
 */

#ifndef ti_drivers_I2CTARGET__include
#define ti_drivers_I2CTARGET__include

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>

#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/dpl/SemaphoreP.h>
#define I2CTarget_STATUS_SUCCESS (0)

#define I2CTarget_STATUS_ERROR (-1)

typedef struct I2CTarget_Config_ *I2CTarget_Handle;

typedef enum
{
    I2CTarget_Event_WRITE_REQUESTED,

    I2CTarget_Event_READ_REQUESTED,

    I2CTarget_Event_WRITE_RECEIVED,

    I2CTarget_Event_READ_PROCESSED,

    I2CTarget_Event_STOP
} I2CTarget_Event;

typedef enum
{
    I2CTarget_State_STOPPED, /* I2CTarget driver is not started. */
    I2CTarget_State_IDLE,    /* I2CTarget driver is started, no ongoing transactions */
    I2CTarget_State_RECEIVE, /* I2CTarget driver is receiving data */
    I2CTarget_State_TRANSMIT /* I2CTarget driver is transmitting */
} I2CTarget_State;
typedef int_fast16_t (*I2CTarget_EventCallbackFxn)(I2CTarget_Handle handle, I2CTarget_Event event, uint8_t *val);

typedef struct
{
    I2CTarget_EventCallbackFxn eventCallbackFxn;
    uint_least16_t targetAddress;
    void *custom;
} I2CTarget_Params;

#define I2CTARGET_BASE_OBJECT                                                              \
    /* I2CTarget control variables */                                                      \
    I2CTarget_EventCallbackFxn eventCallbackFxn; /* Callback function pointer */           \
    uint_least16_t targetAddress;                /* Device's own address on the I2C bus */ \
    I2CTarget_State currentState;                /* Internal state machine */              \
                                                                                           \
    /* I2CTarget RTOS objects */                                                           \
    HwiP_Struct hwi;         /* Hwi object handle */                                       \
    SemaphoreP_Struct mutex; /* Grants exclusive access to I2C module */                   \
                                                                                           \
    bool isOpen; /* Flag to show module is open */                                         \

typedef struct
{
    I2CTARGET_BASE_OBJECT
} I2CTarget_Object;
#define I2CTARGET_BASE_HWATTRS                  \
        \
    uint32_t baseAddr;                          \
    \
    uint32_t intNum;                            \
 \
    uint32_t intPriority;

typedef struct
{
    I2CTARGET_BASE_HWATTRS
} I2CTarget_HWAttrs;
typedef struct I2CTarget_Config_
{
    void *object;

    void const *hwAttrs;
} I2CTarget_Config;

extern const I2CTarget_Config I2CTarget_config[];
extern const uint_least8_t I2CTarget_count;

extern void I2CTarget_init(void);

extern void I2CTarget_Params_init(I2CTarget_Params *params);

extern I2CTarget_Handle I2CTarget_open(uint_least8_t index, I2CTarget_Params *params);

extern void I2CTarget_start(I2CTarget_Handle handle);

extern void I2CTarget_stop(I2CTarget_Handle handle);

extern void I2CTarget_close(I2CTarget_Handle handle);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_I2CTARGET__include */