1 /*
2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6 
7 #ifndef R_I2C_MASTER_API_H
8 #define R_I2C_MASTER_API_H
9 
10 /*******************************************************************************************************************//**
11  * @ingroup RENESAS_CONNECTIVITY_INTERFACES
12  * @defgroup I2C_MASTER_API I2C Master Interface
13  * @brief Interface for I2C master communication.
14  *
15  * @section I2C_MASTER_API_SUMMARY Summary
16  * The I2C master interface provides a common API for I2C HAL drivers. The I2C master interface supports:
17  *        - Interrupt driven transmit/receive processing
18  *        - Callback function support which can return an event code
19  *
20  *
21  * @{
22  **********************************************************************************************************************/
23 
24 /***********************************************************************************************************************
25  * Includes
26  **********************************************************************************************************************/
27 
28 /* Register definitions, common services and error codes. */
29 #include "bsp_api.h"
30 #include "r_transfer_api.h"
31 
32 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */
33 FSP_HEADER
34 
35 /**********************************************************************************************************************
36  * Macro definitions
37  **********************************************************************************************************************/
38 
39 /**********************************************************************************************************************
40  * Typedef definitions
41  **********************************************************************************************************************/
42 
43 /** Communication speed options */
44 typedef enum e_i2c_master_rate
45 {
46     I2C_MASTER_RATE_STANDARD = 100000, ///< 100 kHz
47     I2C_MASTER_RATE_FAST     = 400000, ///< 400 kHz
48     I2C_MASTER_RATE_FASTPLUS = 1000000 ///< 1 MHz
49 } i2c_master_rate_t;
50 
51 /** Addressing mode options */
52 typedef enum e_i2c_master_addr_mode
53 {
54     I2C_MASTER_ADDR_MODE_7BIT  = 1,    ///< Use 7-bit addressing mode
55     I2C_MASTER_ADDR_MODE_10BIT = 2,    ///< Use 10-bit addressing mode
56 } i2c_master_addr_mode_t;
57 
58 /** Callback events */
59 typedef enum e_i2c_master_event
60 {
61     I2C_MASTER_EVENT_ABORTED     = 1,  ///< A transfer was aborted
62     I2C_MASTER_EVENT_RX_COMPLETE = 2,  ///< A receive operation was completed successfully
63     I2C_MASTER_EVENT_TX_COMPLETE = 3   ///< A transmit operation was completed successfully
64 } i2c_master_event_t;
65 
66 /** I2C callback parameter definition */
67 typedef struct st_i2c_master_callback_args
68 {
69     void const       * p_context;      ///< Pointer to user-provided context
70     i2c_master_event_t event;          ///< Event code
71 } i2c_master_callback_args_t;
72 
73 /** I2C status indicators */
74 typedef struct st_i2c_master_status
75 {
76     bool open;                         ///< True if driver is open
77 } i2c_master_status_t;
78 
79 /** I2C configuration block */
80 typedef struct st_i2c_master_cfg
81 {
82     /** Generic configuration */
83     uint8_t                channel;                           ///< Identifier recognizable by implementation
84     i2c_master_rate_t      rate;                              ///< Device's maximum clock rate from enum i2c_rate_t
85     uint32_t               slave;                             ///< The address of the slave device
86     i2c_master_addr_mode_t addr_mode;                         ///< Indicates how slave fields should be interpreted
87     uint8_t                ipl;                               ///< Interrupt priority level. Same for RXI, TXI, TEI and ERI.
88     IRQn_Type              rxi_irq;                           ///< Receive IRQ number
89     IRQn_Type              txi_irq;                           ///< Transmit IRQ number
90     IRQn_Type              tei_irq;                           ///< Transmit end IRQ number
91     IRQn_Type              eri_irq;                           ///< Error IRQ number
92 
93     /** Transfer API support */
94     transfer_instance_t const * p_transfer_tx;                ///< Transfer instance for I2C transmit. Set to NULL if unused.
95     transfer_instance_t const * p_transfer_rx;                ///< Transfer instance for I2C receive. Set to NULL if unused.
96 
97     /** Parameters to control software behavior */
98     void (* p_callback)(i2c_master_callback_args_t * p_args); ///< Pointer to callback function
99     void const * p_context;                                   ///< Pointer to the user-provided context
100 
101     /** Implementation-specific configuration */
102     void const * p_extend;                                    ///< Any configuration data needed by the hardware
103 } i2c_master_cfg_t;
104 
105 /** I2C control block.  Allocate an instance specific control block to pass into the I2C API calls.
106  */
107 typedef void i2c_master_ctrl_t;
108 
109 /** Interface definition for I2C access as master */
110 typedef struct st_i2c_master_api
111 {
112     /** Opens the I2C Master driver and initializes the hardware.
113      *
114      * @param[in] p_ctrl    Pointer to control block. Must be declared by user. Elements are set here.
115      * @param[in] p_cfg     Pointer to configuration structure.
116      */
117     fsp_err_t (* open)(i2c_master_ctrl_t * const p_ctrl, i2c_master_cfg_t const * const p_cfg);
118 
119     /** Performs a read operation on an I2C Master device.
120      *
121      * @param[in] p_ctrl    Pointer to control block set in i2c_master_api_t::open call.
122      * @param[in] p_dest    Pointer to the location to store read data.
123      * @param[in] bytes     Number of bytes to read.
124      * @param[in] restart   Specify if the restart condition should be issued after reading.
125      */
126     fsp_err_t (* read)(i2c_master_ctrl_t * const p_ctrl, uint8_t * const p_dest, uint32_t const bytes,
127                        bool const restart);
128 
129     /** Performs a write operation on an I2C Master device.
130      *
131      * @param[in] p_ctrl    Pointer to control block set in i2c_master_api_t::open call.
132      * @param[in] p_src     Pointer to the location to get write data from.
133      * @param[in] bytes     Number of bytes to write.
134      * @param[in] restart   Specify if the restart condition should be issued after writing.
135      */
136     fsp_err_t (* write)(i2c_master_ctrl_t * const p_ctrl, uint8_t * const p_src, uint32_t const bytes,
137                         bool const restart);
138 
139     /** Performs a reset of the peripheral.
140      *
141      * @param[in] p_ctrl    Pointer to control block set in i2c_master_api_t::open call.
142      */
143     fsp_err_t (* abort)(i2c_master_ctrl_t * const p_ctrl);
144 
145     /** Sets address of the slave device without reconfiguring the bus.
146      *
147      * @param[in] p_ctrl            Pointer to control block set in i2c_master_api_t::open call.
148      * @param[in] slave_address     Address of the slave device.
149      * @param[in] address_mode      Addressing mode.
150      */
151     fsp_err_t (* slaveAddressSet)(i2c_master_ctrl_t * const p_ctrl, uint32_t const slave,
152                                   i2c_master_addr_mode_t const addr_mode);
153 
154     /**
155      * Specify callback function and optional context pointer and working memory pointer.
156      *
157      * @param[in]   p_ctrl                   Pointer to the IIC Master control block.
158      * @param[in]   p_callback               Callback function
159      * @param[in]   p_context                Pointer to send to callback function
160      * @param[in]   p_working_memory         Pointer to volatile memory where callback structure can be allocated.
161      *                                       Callback arguments allocated here are only valid during the callback.
162      */
163     fsp_err_t (* callbackSet)(i2c_master_ctrl_t * const p_ctrl, void (* p_callback)(i2c_master_callback_args_t *),
164                               void const * const p_context, i2c_master_callback_args_t * const p_callback_memory);
165 
166     /** Gets the status of the configured I2C device.
167      *
168      * @param[in]   p_ctrl             Pointer to the IIC Master control block.
169      * @param[out]  p_status           Pointer to store current status.
170      */
171     fsp_err_t (* statusGet)(i2c_master_ctrl_t * const p_ctrl, i2c_master_status_t * p_status);
172 
173     /** Closes the driver and releases the I2C Master device.
174      *
175      * @param[in] p_ctrl    Pointer to control block set in i2c_master_api_t::open call.
176      */
177     fsp_err_t (* close)(i2c_master_ctrl_t * const p_ctrl);
178 } i2c_master_api_t;
179 
180 /** This structure encompasses everything that is needed to use an instance of this interface. */
181 typedef struct st_i2c_master_instance
182 {
183     i2c_master_ctrl_t      * p_ctrl;   ///< Pointer to the control structure for this instance
184     i2c_master_cfg_t const * p_cfg;    ///< Pointer to the configuration structure for this instance
185     i2c_master_api_t const * p_api;    ///< Pointer to the API structure for this instance
186 } i2c_master_instance_t;
187 
188 /******************************************************************************************************************//**
189  * @} (end defgroup I2C_MASTER_API)
190  *********************************************************************************************************************/
191 
192 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */
193 FSP_FOOTER
194 
195 #endif
196