I2C_0.c

Go to the documentation of this file.

 
/// \file
 
#include "tutti_gli_header.h"
 
// DOCUMENTAZIONE DOXYGEN  
 
 
/*! \page I2C_0_page I2C_0
*\brief  <span style="color:red;"> <b> This is the hw for the I2C_0 fw  </b> </span>
*\tableofcontents
 
 \b SUMMARY:
*\arg \ref I2C_0_section
 
 
*\section I2C_0_section User use of the I2C_0
<hr width="75%" size="10" align="left">
 
\n The I2C fw exploits the CMSIS functions, in particular to \b Driver_I2C.h,. Two functions are developed on purpose for each I2C,
I2C_0 and I2C_1.. 
The first is the initalization function I2C_0_Initialize(void), while the other is the function 
called from the interrupt, 
I2C_0_SignalEvent_t(uint32_t event). This last function can be exploited, or considered exploting the 
variable #evento_I2C. Its flags ar listed in \ref Table_interrupt_event.
\n The transmission speed is set at #ARM_I2C_BUS_SPEED_STANDARD, that correspond to 100 KHz.
 
\n 
<center>
\anchor Table_interrupt_event  \b Table \b Interrput: Flags of the mask #evento_I2C. <span style="color:red;"> 
The row highlighted in red marks the bit expected after a successfully communication. </span>
Parameter event                   | Bit      | Description                                                                               |
:-------------------------------  | :-----:  | :-----------------------------------------------------------------------------------------|
<span style="color:red;"> ARM_I2C_EVENT_TRANSFER_DONE </span>       | <span style="color:red;"> 1UL << 0 </span> | <span style="color:red;"> Occurs after Master/Slave Transmit/Receive operation has finished. </span>                        |
ARM_I2C_EVENT_TRANSFER_INCOMPLETE | 1UL << 1 | Occurs together with ARM_I2C_EVENT_TRANSFER_DONE when <br /> less data is transferred then requested.                                                                                                 |
ARM_I2C_EVENT_SLAVE_TRANSMIT      | 1UL << 2 | Occurs when addressed as Slave Transmitter and ARM_I2C_SlaveTransmit has not been started.|
ARM_I2C_EVENT_SLAVE_RECEIVE       | 1UL << 3 | Occurs when addressed as Slave Receiver and ARM_I2C_SlaveReceive has not been started.    |
ARM_I2C_EVENT_ADDRESS_NACK        | 1UL << 4 | Occurs in master mode when address is not acknowledged from slave.                        |
ARM_I2C_EVENT_GENERAL_CALL        | 1UL << 5 | Indicates General Call in slave mode together with ARM_I2C_EVENT_TRANSFER_DONE, <br /> ARM_I2C_EVENT_SLAVE_TRANSMIT and ARM_I2C_EVENT_SLAVE_RECEIVE. |
ARM_I2C_EVENT_ARBITRATION_LOST    | 1UL << 6 | Occurs in master mode when arbitration is lost.                                           |
ARM_I2C_EVENT_BUS_ERROR           | 1UL << 7 | Occurs when bus error is detected.                                                        |
ARM_I2C_EVENT_BUS_CLEAR           | 1UL << 8 | Occurs after ARM_I2C_BUS_CLEAR Control operation has finished.                            |
</center>
 
\n Let's consider the way the I2C can transmit and receive data exploiting the CMSIS functions. There is a structure 
of functions committed to manage the I22C communication. They are these:
 
<span style="color:orange;"> <I>
\code {.c}
typedef struct _ARM_DRIVER_I2C {
  ARM_DRIVER_VERSION   (*GetVersion)     (void);
  ARM_I2C_CAPABILITIES (*GetCapabilities)(void);
  int32_t              (*Initialize)     (ARM_I2C_SignalEvent_t cb_event);
  int32_t              (*Uninitialize)   (void);
  int32_t              (*PowerControl)   (ARM_POWER_STATE state);
  int32_t              (*MasterTransmit) (uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending);
  int32_t              (*MasterReceive)  (uint32_t addr,       uint8_t *data, uint32_t num, bool xfer_pending);
  int32_t              (*SlaveTransmit)  (               const uint8_t *data, uint32_t num);
  int32_t              (*SlaveReceive)   (                     uint8_t *data, uint32_t num);
  int32_t              (*GetDataCount)   (void);
  int32_t              (*Control)        (uint32_t control, uint32_t arg);
  ARM_I2C_STATUS       (*GetStatus)      (void);
} const ARM_DRIVER_I2C;
\endcode
</I> </span>
 
\n I2C_0 and I2C_1 have the propoer set of functions. Here we consider that committed to I2C_0:
<span style="color:orange;"> <I>
\code {.c}
// I2C0 Driver Control Block
ARM_DRIVER_I2C Driver_I2C0 = {
  I2C_GetVersion,
  I2C_GetCapabilities,
  I2C0_Initialize,
  I2C0_Uninitialize,
  I2C0_PowerControl,
  I2C0_MasterTransmit,  //This is the function we use most of the time
  I2C0_MasterReceive,       //We use this function, too, when we need to check, or read back some parameters
  I2C0_SlaveTransmit,
  I2C0_SlaveReceive,
  I2C0_GetDataCount,
  I2C0_Control,
  I2C0_GetStatus        //This function is exploited to poll the bus
};
\endcode
</I> </span>
 
\n We mainly use the \b I2C0_MasterTransmit, for transmission, \b I2C0_MasterReceive, for reception, and \b I2C0_GetStatus for polling. 
In particular from \b I2C0_GetStatus we get a struct with the following meaning:
 
\n 
<center>
\anchor Table_global_status_struct \b Table \b Global \b Status: Retruned struct from \b I2C0_GetStatus. 
<span style="color:red;"> The row highlighted in red marks the field  exploited in polling operation. </span>
Data                          | Fields                                                               |
:--------------------------   | :--------------------------------------------------------------------|
<span style="color:red;"> uint32_t  busy: 1 </span>             |<span style="color:red;"> Busy flag. </span>
uint32_t    mode: 1             | Mode: 0=Slave, 1=Master.
uint32_t    direction: 1          | Direction: 0=Transmitter, 1=Receiver.
uint32_t    general_call: 1     | General Call indication (cleared on start of next Slave operation)
uint32_t    arbitration_lost: 1 | Master lost arbitration (cleared on start of next Master operation)
uint32_t    bus_error: 1          | Bus error detected (cleared on start of next Master/Slave operation)
uint32_t    reserved: 26        |                                                                        |
</center>
 
\n 
\remark The suggestion is to create a pointer to the structure that identifies the I2C to use. As an instance:
<span style="color:orange;"> <I>
\code {.c}
extern ARM_DRIVER_I2C Driver_I2C0;      // Viene inclusa la Periferica I2C0
ARM_DRIVER_I2C * I2C_mux;  //Define a pointer to structure of functions
 
I2C_mux = &Driver_I2C0;  //Assign the pointer to the I2C to be selected, I2C_0 in this case
 
I2C_mux->MasterTransmit( I2C_mux_address_mainboard, &canale_da_abilitare, 1,false);  //Example of the use of 1 byte transmission
 
while( I2C_mux->GetStatus().busy);  // Wait transmission completes, if we need to wait
 
I2C_mux->MasterReceive( I2C_mux_address_mainboard, &tappo, 1,false);  //Example of the receiving of one byte
 
while( I2C_mux->GetStatus().busy);  // Wait reception completes, if we need to wait
\endcode
</I> </span>
 
\n
\n
\sa That shown above is an extraction of the documentation from CMSIS drivers. 
For a complete reference to the I2C driver from CMSIS see the webs at Keil or ARM (in case of failure of either): 
- <a href="https://arm-software.github.io/CMSIS_5/Driver/html/group__i2c__interface__gr.html"  target=_blank><b>CMSIS doc for I2C from ARM</b></a>, 
- <a href="https://www.keil.com/pack/doc/CMSIS/Driver/html/group__i2c__interface__gr.html"  target=_blank><b>CMSIS doc for I2C from KEIL</b></a>
 
\n The codes for I2C_0 is at: 
- \ref I2C_0.c
- \ref I2C_0.h
 
<!-- pappa -->  
*/
 
/*! <!-- La funzione driver I2C0 -->
<!-- ************************************************************************************************ -->
 
\fn I2C0_Initialize(ARM_I2C_SignalEvent_t cb_event)
 
\param[in]  cb_event    Pointer to \b ARM_I2C_SignalEvent()
\return #Status_Error_Codes_I2C
 
\brief The function \b ARM_I2C_Initialize() initializes the I2C interface. It is called when the middleware component 
starts operation.
 
The function performs the following operations:
 
Initializes and the I/O resources for the I2C interface.
Registers the \b ARM_I2C_SignalEvent() callback function.
The parameter cb_event is a pointer to the \b ARM_I2C_SignalEvent() callback function. 
Use a NULL pointer when no callback events are required.
 
Can be called multiple times. If the peripheral is already initialized the function performs no 
operation and returns with \b ARM_DRIVER_OK. Refer to Function Call Sequence for more information.
 
<!-- ************************************************************************************************ -->
 
\fn  I2C0_Uninitialize(void)
 
\return #Status_Error_Codes_I2C
 
\brief De-initialize I2C Interface.
The function \b ARM_I2C_Uninitialize() releases the I/O resources of I2C interface.
 
It is called when the middleware component stops operation and releases the I/O resources used by the I2C interface. 
Refer to Function Call Sequence for more information.
 
\fn  I2C0_PowerControl(ARM_POWER_STATE state)
 
\param[in]  state   Power state
\return #Status_Error_Codes_I2C
\brief The function \b ARM_I2C_PowerControl() operates the power modes of the I2C interface.
 
The parameter state can have the following values:
- \b ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA. Can be called multiple times. 
If the peripheral is already in this mode, then the function performs no operation and returns with \b ARM_DRIVER_OK.
- \b ARM_POWER_LOW : may use power saving. Returns \b ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
- \b ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
 
<!-- ************************************************************************************************ -->
 
\fn  I2C0_MasterTransmit(uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending)  
 
\param[in]  addr    Slave address (7-bit or 10-bit)
\param[in]  data    Pointer to buffer with data to transmit to I2C Slave
\param[in]  num Number of data bytes to transmit
\param[in]  xfer_pending    Transfer operation is pending - Stop condition will not be generated
\return #Status_Error_Codes_I2C
 
\brief Start transmitting data as I2C Master.
This function ARM_I2C_MasterTransmit transmits data as Master to the selected Slave.
 
The operation consists of:
 
Master generates START condition
Master addresses the Slave as Master Transmitter
Master transmits data to the addressed Slave
Master generates STOP condition (if xfer_pending is "false")
The parameter addr is the address of the slave to transmit the data to. The value can be ORed with #ARM_I2C_ADDRESS_10BIT 
to identify a 10-bit address value.
The parameter data and num specify the address of a data buffer and the number of bytes to transmit.
Set the parameter xfer_pending to 'true' if another transfer operation follows. 
With xfer_pending set to 'false' a STOP condition is generated.
 
The function is non-blocking and returns as soon as the driver has started the operation. 
During the operation it is not allowed to call any Master function again. 
Also the data buffer must stay allocated and the contents of data must not be modified. 
When transmit operation has finished the #ARM_I2C_EVENT_TRANSFER_DONE event is generated. 
When not all the data is transferred then the #ARM_I2C_EVENT_TRANSFER_INCOMPLETE flag is set at the same time.
 
Number of data bytes transmitted and acknowledged is returned by the function \b ARM_I2C_GetDataCount 
during and after the operation has finished.
 
The operation is aborted in the following cases (#ARM_I2C_EVENT_TRANSFER_DONE event is generated together with):
 
selected slave has not acknowledged the address: #ARM_I2C_EVENT_ADDRESS_NACK event
arbitration has been lost: #ARM_I2C_EVENT_ARBITRATION_LOST event
bus error has been detected: #ARM_I2C_EVENT_BUS_ERROR event
Status can be monitored by calling the \b ARM_I2C_GetStatus and checking the flags.
 
Transmit operation can be aborted also by calling \b ARM_I2C_Control with the parameter control #ARM_I2C_ABORT_TRANSFER.
 
<!-- ************************************************************************************************ -->
 
\fn  I2C0_MasterReceive(uint32_t addr, uint8_t *data, uint32_t num, bool xfer_pending) 
 
\param[in]  addr    Slave address (7-bit or 10-bit)
\param[out] data    Pointer to buffer for data to receive from I2C Slave
\param[in]  num Number of data bytes to receive
\param[in]  xfer_pending    Transfer operation is pending - Stop condition will not be generated
\return #Status_Error_Codes_I2C
\brief This function ARM_I2C_MasterReceive is used to receive data as Master from the selected Slave.
 
The operation consists of:
 
Master generates START condition
Master addresses the Slave as Master Receiver
Master receives data from the addressed Slave
Master generates STOP condition (if xfer_pending is "false")
The parameter addr is the address of the slave to receive the data from. The value can be ORed with #ARM_I2C_ADDRESS_10BIT to identify a 10-bit address value.
The parameter data and num specify the address of a data buffer and the number of bytes to receive.
Set the parameter xfer_pending to 'true' if another transfer operation follows. With xfer_pending set to 'false' a STOP condition is generated.
 
The function is non-blocking and returns as soon as the driver has started the operation. During the operation it is not allowed to call any Master function again. Also the data buffer must stay allocated. 
When receive operation has finished the #ARM_I2C_EVENT_TRANSFER_DONE event is generated. When not all the data is transferred 
then the #ARM_I2C_EVENT_TRANSFER_INCOMPLETE flag is set at the same time.
 
Number of data bytes received is returned by the function #ARM_I2C_GetDataCount during and after the operation has finished.
 
The operation is aborted in the following cases (#ARM_I2C_EVENT_TRANSFER_DONE event is generated together with):
 
selected slave has not acknowledged the address: #ARM_I2C_EVENT_ADDRESS_NACK event
arbitration has been lost: #ARM_I2C_EVENT_ARBITRATION_LOST event
bus error has been detected: #ARM_I2C_EVENT_BUS_ERROR event
Status can be monitored by calling the ARM_I2C_GetStatus and checking the flags.
 
Receive operation can be aborted also by calling #ARM_I2C_Control with the parameter control = #ARM_I2C_ABORT_TRANSFER.
 
<!-- ************************************************************************************************ -->
 
\fn  I2C0_GetStatus(void)
 
\return I2C status \ref Table_global_status_struct "ARM_I2C_STATUS"
\brief Get I2C status.
The function  I2C0_GetStatus() returns the current I2C interface status.
*/
 
// <!-- ************************************************************************************************ -->
// <!-- Definizione solo per creare un commento -->
/*! \brief 
Macros
- \b ARM_DRIVER_OK   0
    Operation succeeded.  
- \b ARM_DRIVER_ERROR   -1
    Unspecified error.  
- \b ARM_DRIVER_ERROR_BUSY   -2
    Driver is busy.  
- \b ARM_DRIVER_ERROR_TIMEOUT   -3
    Timeout occurred. 
- \b ARM_DRIVER_ERROR_UNSUPPORTED   -4
    Operation not supported.  
- \b ARM_DRIVER_ERROR_PARAMETER   -5
    Parameter error.  
- \b ARM_DRIVER_ERROR_SPECIFIC   -6
    Start of driver specific errors.
    
Description
Negative return values of functions indicate errors occurred during execution.
 
Most functions return a status information using negative return values. 
The following list provides the status error codes that are common in all drivers. 
The drivers may return also status error codes that are specific to the peripheral.
*/
int8_t Status_Error_Codes_I2C;  //Creata solo per generare un commento
 
uint32_t  evento_I2C; ///< This is the variable which resembles the flags from the communication
extern ARM_DRIVER_I2C Driver_I2C0;                                                  // Viene inclusa la Periferica I2C0
ARM_DRIVER_I2C * I2CBdrv = &Driver_I2C0;                            // Viene creato un puntatore a Driver_I2C0
 
/*****************************************************************************
  Callback della Periferica I2C_B
 ******************************************************************************/
 
/*! \brief The I2C_0 interrupt function
 
*\return No Parameters
 \showrefby
*\snippet{lineno} I2C_0.c fun_I2C_0_SignalEvent_t
 */
//! <!-- [fun_I2C_0_SignalEvent_t] -->
void I2C_0_SignalEvent_t (uint32_t event)
{
        evento_I2C=event;
        if(event==ARM_I2C_EVENT_TRANSFER_DONE)              // Ricezione e trasmissione finita sia del master che dello slave
        {
            __NOP();
            Error_bad_operation = 0;
        }
        if( event & ARM_I2C_EVENT_TRANSFER_INCOMPLETE)
        {
            Error_bad_operation |= 1;
        }       
        if(event==ARM_I2C_EVENT_SLAVE_TRANSMIT)
        {
            __NOP();
            Error_bad_operation |= 2;
        }
        if(event==ARM_I2C_EVENT_SLAVE_RECEIVE)
        {
            __NOP();
                Error_bad_operation |= 3;           
        }       
        if (event & ARM_I2C_EVENT_ADDRESS_NACK){
            Error_bad_operation = 4;
        }
        if (event & ARM_I2C_EVENT_ARBITRATION_LOST){
            Error_bad_operation |= 6;
        }
        if( event & ARM_I2C_EVENT_BUS_ERROR){
            Error_bad_operation |= 7;
        }
        if( event & ARM_I2C_EVENT_BUS_CLEAR){
            Error_bad_operation |= 8;
        }       
}
//! <!-- [fun_I2C_0_SignalEvent_t] -->
 
 
 
/*****************************************************************************
  I2C INIZIALIZE
 *****************************************************************************/
 
 
 /*! \brief The I2C_0 initialize
 
 *\return No Parameters
 \showrefby
\showrefs
\callgraph  
 *\snippet{lineno} I2C_0.c fun_I2C_0_Initialize
 */
 
//! <!-- [fun_I2C_0_Initialize] -->
void I2C_0_Initialize (void) {
 
  I2CBdrv->Initialize   (I2C_0_SignalEvent_t);                                                  // Viene inizializzata la periferica I2C
  I2CBdrv->PowerControl (ARM_POWER_FULL);                                                               // Viene accesa la periferica
  I2CBdrv->Control      (ARM_I2C_BUS_SPEED, ARM_I2C_BUS_SPEED_STANDARD);        // Viene impostata la velocit\'a del Bus
  I2CBdrv->Control      (ARM_I2C_BUS_CLEAR, 0);                                              
}
//! <!-- [fun_I2C_0_Initialize] -->