ChibiOS/HAL 9.0.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 * @brief Slave mode API enable switch.
67 * @note The low level driver must support this capability.
68 */
69#if !defined(I2C_ENABLE_SLAVE_MODE)
70#define I2C_ENABLE_SLAVE_MODE FALSE
71#endif
72
73/*===========================================================================*/
74/* Derived constants and error checks. */
75/*===========================================================================*/
76
77/*===========================================================================*/
78/* Driver data structures and types. */
79/*===========================================================================*/
80
81/**
82 * @brief Driver state machine possible states.
83 */
84typedef enum {
85 I2C_UNINIT = 0, /**< @brief Not initialized. */
86 I2C_STOP = 1, /**< @brief Stopped. */
87 I2C_READY = 2, /**< @brief Ready. */
88 I2C_ACTIVE_TX = 3, /**< @brief Transmitting. */
89 I2C_ACTIVE_RX = 4, /**< @brief Receiving. */
90 I2C_LOCKED = 5 /**< @brief Bus locked. */
92
93#include "hal_i2c_lld.h"
94
95/* For compatibility, some LLDs could not export this.*/
96#if !defined(I2C_SUPPORTS_SLAVE_MODE)
97#define I2C_SUPPORTS_SLAVE_MODE FALSE
98#endif
99
100#if (I2C_SUPPORTS_SLAVE_MODE == FALSE) && (I2C_ENABLE_SLAVE_MODE == TRUE)
101#error "I2C slave mode not supported"
102#endif
103
104/*===========================================================================*/
105/* Driver macros. */
106/*===========================================================================*/
107
108/**
109 * @name Macro Functions
110 * @{
111 */
112/**
113 * @brief Wakes up the waiting thread notifying no errors.
114 *
115 * @param[in] i2cp pointer to the @p I2CDriver object
116 *
117 * @notapi
118 */
119#define _i2c_wakeup_isr(i2cp) do { \
120 osalSysLockFromISR(); \
121 osalThreadResumeI(&(i2cp)->thread, MSG_OK); \
122 osalSysUnlockFromISR(); \
123} while (0)
124
125/**
126 * @brief Wakes up the waiting thread notifying errors.
127 *
128 * @param[in] i2cp pointer to the @p I2CDriver object
129 *
130 * @notapi
131 */
132#define _i2c_wakeup_error_isr(i2cp) do { \
133 osalSysLockFromISR(); \
134 osalThreadResumeI(&(i2cp)->thread, MSG_RESET); \
135 osalSysUnlockFromISR(); \
136} while (0)
137
138/**
139 * @brief Wrap i2cMasterTransmitTimeout function with TIME_INFINITE timeout.
140 * @api
141 */
142#define i2cMasterTransmit(i2cp, addr, txbuf, txbytes, rxbuf, rxbytes) \
143 (i2cMasterTransmitTimeout(i2cp, addr, txbuf, txbytes, rxbuf, rxbytes, \
144 TIME_INFINITE))
145
146/**
147 * @brief Wrap i2cMasterReceiveTimeout function with TIME_INFINITE timeout.
148 * @api
149 */
150#define i2cMasterReceive(i2cp, addr, rxbuf, rxbytes) \
151 (i2cMasterReceiveTimeout(i2cp, addr, rxbuf, rxbytes, TIME_INFINITE))
152
153#if (I2C_ENABLE_SLAVE_MODE == TRUE) || defined(__DOXYGEN__)
154/**
155 * @brief Answer required.
156 * @note This function is meant to be called after slave receive only.
157 *
158 * @param[in] i2cp pointer to the @p I2CDriver object
159 * @return Slave answer required.
160 * @retval false if the slave must not answer.
161 * @retval true if the slave must answer.
162 *
163 * @special
164 */
165#define i2cSlaveIsAnswerRequired(i2cp) (((i2cp)->reply_required))
166#endif
167/** @} */
168
169/*===========================================================================*/
170/* External declarations. */
171/*===========================================================================*/
172
173#ifdef __cplusplus
174extern "C" {
175#endif
176 void i2cInit(void);
177 void i2cObjectInit(I2CDriver *i2cp);
178 msg_t i2cStart(I2CDriver *i2cp, const I2CConfig *config);
179 void i2cStop(I2CDriver *i2cp);
182 i2caddr_t addr,
183 const uint8_t *txbuf, size_t txbytes,
184 uint8_t *rxbuf, size_t rxbytes,
185 sysinterval_t timeout);
187 i2caddr_t addr,
188 uint8_t *rxbuf, size_t rxbytes,
189 sysinterval_t timeout);
190#if I2C_USE_MUTUAL_EXCLUSION == TRUE
191 void i2cAcquireBus(I2CDriver *i2cp);
192 void i2cReleaseBus(I2CDriver *i2cp);
193#endif
194#if I2C_ENABLE_SLAVE_MODE == TRUE
196 msg_t i2cSlaveReceiveTimeout(I2CDriver *i2cp, uint8_t *rxbuf,
197 size_t rxbytes, sysinterval_t timeout);
198 msg_t i2cSlaveTransmitTimeout(I2CDriver *i2cp, const uint8_t *txbuf,
199 size_t txbytes, sysinterval_t timeout);
200#endif
201#ifdef __cplusplus
202}
203#endif
204
205#endif /* HAL_USE_I2C == TRUE */
206
207#endif /* HAL_I2C_H */
208
209/** @} */
msg_t i2cSlaveTransmitTimeout(I2CDriver *i2cp, const uint8_t *txbuf, size_t txbytes, sysinterval_t timeout)
Transmits data via the I2C bus as slave.
Definition hal_i2c.c:398
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:237
void i2cInit(void)
I2C Driver initialization.
Definition hal_i2c.c:59
void i2cObjectInit(I2CDriver *i2cp)
Initializes the standard part of a I2CDriver structure.
Definition hal_i2c.c:71
uint32_t i2cflags_t
Type of I2C Driver condition flags.
Definition hal_i2c_lld.h:68
msg_t i2cStart(I2CDriver *i2cp, const I2CConfig *config)
Configures and activates the I2C peripheral.
Definition hal_i2c.c:94
struct hal_i2c_config I2CConfig
Type of a structure representing an I2C configuration.
Definition hal_i2c_lld.h:83
i2cflags_t i2cGetErrors(I2CDriver *i2cp)
Returns the errors mask associated to the previous operation.
Definition hal_i2c.c:155
msg_t i2cSlaveReceiveTimeout(I2CDriver *i2cp, uint8_t *rxbuf, size_t rxbytes, sysinterval_t timeout)
Receive data via the I2C bus as slave and call handler.
Definition hal_i2c.c:347
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:187
void i2cReleaseBus(I2CDriver *i2cp)
Releases exclusive access to the I2C bus.
Definition hal_i2c.c:293
i2cstate_t
Driver state machine possible states.
Definition hal_i2c.h:84
uint16_t i2caddr_t
Type representing an I2C address.
Definition hal_i2c_lld.h:63
void i2cStop(I2CDriver *i2cp)
Deactivates the I2C peripheral.
Definition hal_i2c.c:131
msg_t i2cSlaveMatchAddress(I2CDriver *i2cp, i2caddr_t addr)
Listen I2C bus for address match.
Definition hal_i2c.c:315
void i2cAcquireBus(I2CDriver *i2cp)
Gains exclusive access to the I2C bus.
Definition hal_i2c.c:277
struct hal_i2c_driver I2CDriver
Type of a structure representing an I2C driver.
Definition hal_i2c_lld.h:88
@ I2C_ACTIVE_TX
Transmitting.
Definition hal_i2c.h:88
@ I2C_UNINIT
Not initialized.
Definition hal_i2c.h:85
@ I2C_STOP
Stopped.
Definition hal_i2c.h:86
@ I2C_READY
Ready.
Definition hal_i2c.h:87
@ I2C_LOCKED
Bus locked.
Definition hal_i2c.h:90
@ I2C_ACTIVE_RX
Receiving.
Definition hal_i2c.h:89
int32_t msg_t
Type of a message.
Definition osal.h:159
uint32_t sysinterval_t
Type of system time interval.
Definition osal.h:169
PLATFORM I2C subsystem low level driver header.