ChibiOS/HAL  6.1.0
hal_i2c.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3 
4  Licensed under the Apache License, Version 2.0 (the "License");
5  you may not use this file except in compliance with the License.
6  You may obtain a copy of the License at
7 
8  http://www.apache.org/licenses/LICENSE-2.0
9 
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15 */
16 /*
17  Concepts and parts of this file have been contributed by Uladzimir Pylinsky
18  aka barthess.
19  */
20 
21 /**
22  * @file hal_i2c.h
23  * @brief I2C Driver macros and structures.
24  *
25  * @addtogroup I2C
26  * @{
27  */
28 
29 #ifndef HAL_I2C_H
30 #define HAL_I2C_H
31 
32 #if (HAL_USE_I2C == TRUE) || defined(__DOXYGEN__)
33 
34 /*===========================================================================*/
35 /* Driver constants. */
36 /*===========================================================================*/
37 
38 /* TODO: To be reviewed, too STM32-centric.*/
39 /**
40  * @name I2C bus error conditions
41  * @{
42  */
43 #define I2C_NO_ERROR 0x00 /**< @brief No error. */
44 #define I2C_BUS_ERROR 0x01 /**< @brief Bus Error. */
45 #define I2C_ARBITRATION_LOST 0x02 /**< @brief Arbitration Lost. */
46 #define I2C_ACK_FAILURE 0x04 /**< @brief Acknowledge Failure. */
47 #define I2C_OVERRUN 0x08 /**< @brief Overrun/Underrun. */
48 #define I2C_PEC_ERROR 0x10 /**< @brief PEC Error in
49  reception. */
50 #define I2C_TIMEOUT 0x20 /**< @brief Hardware timeout. */
51 #define I2C_SMB_ALERT 0x40 /**< @brief SMBus Alert. */
52 /** @} */
53 
54 /*===========================================================================*/
55 /* Driver pre-compile time settings. */
56 /*===========================================================================*/
57 
58 /**
59  * @brief Enables the mutual exclusion APIs on the I2C bus.
60  */
61 #if !defined(I2C_USE_MUTUAL_EXCLUSION) || defined(__DOXYGEN__)
62 #define I2C_USE_MUTUAL_EXCLUSION TRUE
63 #endif
64 
65 /*===========================================================================*/
66 /* Derived constants and error checks. */
67 /*===========================================================================*/
68 
69 /*===========================================================================*/
70 /* Driver data structures and types. */
71 /*===========================================================================*/
72 
73 /**
74  * @brief Driver state machine possible states.
75  */
76 typedef enum {
77  I2C_UNINIT = 0, /**< Not initialized. */
78  I2C_STOP = 1, /**< Stopped. */
79  I2C_READY = 2, /**< Ready. */
80  I2C_ACTIVE_TX = 3, /**< Transmitting. */
81  I2C_ACTIVE_RX = 4, /**< Receiving. */
82  I2C_LOCKED = 5 /**> Bus or driver locked. */
83 } i2cstate_t;
84 
85 #include "hal_i2c_lld.h"
86 
87 /*===========================================================================*/
88 /* Driver macros. */
89 /*===========================================================================*/
90 
91 /**
92  * @brief Wakes up the waiting thread notifying no errors.
93  *
94  * @param[in] i2cp pointer to the @p I2CDriver object
95  *
96  * @notapi
97  */
98 #define _i2c_wakeup_isr(i2cp) do { \
99  osalSysLockFromISR(); \
100  osalThreadResumeI(&(i2cp)->thread, MSG_OK); \
101  osalSysUnlockFromISR(); \
102 } while(0)
103 
104 /**
105  * @brief Wakes up the waiting thread notifying errors.
106  *
107  * @param[in] i2cp pointer to the @p I2CDriver object
108  *
109  * @notapi
110  */
111 #define _i2c_wakeup_error_isr(i2cp) do { \
112  osalSysLockFromISR(); \
113  osalThreadResumeI(&(i2cp)->thread, MSG_RESET); \
114  osalSysUnlockFromISR(); \
115 } while(0)
116 
117 /**
118  * @brief Wrap i2cMasterTransmitTimeout function with TIME_INFINITE timeout.
119  * @api
120  */
121 #define i2cMasterTransmit(i2cp, addr, txbuf, txbytes, rxbuf, rxbytes) \
122  (i2cMasterTransmitTimeout(i2cp, addr, txbuf, txbytes, rxbuf, rxbytes, \
123  TIME_INFINITE))
124 
125 /**
126  * @brief Wrap i2cMasterReceiveTimeout function with TIME_INFINITE timeout.
127  * @api
128  */
129 #define i2cMasterReceive(i2cp, addr, rxbuf, rxbytes) \
130  (i2cMasterReceiveTimeout(i2cp, addr, rxbuf, rxbytes, TIME_INFINITE))
131 
132 /*===========================================================================*/
133 /* External declarations. */
134 /*===========================================================================*/
135 
136 #ifdef __cplusplus
137 extern "C" {
138 #endif
139  void i2cInit(void);
140  void i2cObjectInit(I2CDriver *i2cp);
141  void i2cStart(I2CDriver *i2cp, const I2CConfig *config);
142  void i2cStop(I2CDriver *i2cp);
145  i2caddr_t addr,
146  const uint8_t *txbuf, size_t txbytes,
147  uint8_t *rxbuf, size_t rxbytes,
148  sysinterval_t timeout);
150  i2caddr_t addr,
151  uint8_t *rxbuf, size_t rxbytes,
152  sysinterval_t timeout);
153 #if I2C_USE_MUTUAL_EXCLUSION == TRUE
154  void i2cAcquireBus(I2CDriver *i2cp);
155  void i2cReleaseBus(I2CDriver *i2cp);
156 #endif
157 
158 #ifdef __cplusplus
159 }
160 #endif
161 
162 #endif /* HAL_USE_I2C == TRUE */
163 
164 #endif /* HAL_I2C_H */
165 
166 /** @} */
PLATFORM I2C subsystem low level driver header.
void i2cInit(void)
I2C Driver initialization.
Definition: hal_i2c.c:59
msg_t i2cMasterTransmitTimeout(I2CDriver *i2cp, i2caddr_t addr, const uint8_t *txbuf, size_t txbytes, uint8_t *rxbuf, size_t rxbytes, sysinterval_t timeout)
Sends data via the I2C bus.
Definition: hal_i2c.c:170
void i2cStart(I2CDriver *i2cp, const I2CConfig *config)
Configures and activates the I2C peripheral.
Definition: hal_i2c.c:93
Type of I2C driver configuration structure.
Definition: hal_i2c_lld.h:75
void i2cAcquireBus(I2CDriver *i2cp)
Gains exclusive access to the I2C bus.
Definition: hal_i2c.c:261
void i2cReleaseBus(I2CDriver *i2cp)
Releases exclusive access to the I2C bus.
Definition: hal_i2c.c:277
msg_t i2cMasterReceiveTimeout(I2CDriver *i2cp, i2caddr_t addr, uint8_t *rxbuf, size_t rxbytes, sysinterval_t timeout)
Receives data from the I2C bus.
Definition: hal_i2c.c:221
i2cflags_t i2cGetErrors(I2CDriver *i2cp)
Returns the errors mask associated to the previous operation.
Definition: hal_i2c.c:137
void i2cObjectInit(I2CDriver *i2cp)
Initializes the standard part of a I2CDriver structure.
Definition: hal_i2c.c:71
int32_t msg_t
Type of a message.
Definition: osal.h:160
void i2cStop(I2CDriver *i2cp)
Deactivates the I2C peripheral.
Definition: hal_i2c.c:113
uint32_t i2cflags_t
Type of I2C Driver condition flags.
Definition: hal_i2c_lld.h:68
Structure representing an I2C driver.
Definition: hal_i2c_lld.h:88
uint32_t sysinterval_t
Type of system time interval.
Definition: osal.h:170
uint16_t i2caddr_t
Type representing an I2C address.
Definition: hal_i2c_lld.h:63
i2cstate_t
Driver state machine possible states.
Definition: hal_i2c.h:77