RTEMS 5.2
All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
i2c.h
1/*
2 * Generic I2C bus interface for RTEMS
3 *
4 * Copyright (C) 2000 OKTET Ltd., St.-Petersburg, Russia
5 * Author: Victor V. Vengerov <vvv@oktet.ru>
6 *
7 * The license and distribution terms for this file may be
8 * found in the file LICENSE in this distribution or at
9 *
10 * http://www.rtems.org/license/LICENSE.
11 */
12
13#ifndef __RTEMS__I2C_H__
14#define __RTEMS__I2C_H__
15
16#include <rtems.h>
17#include <bsp.h>
18/* This header file define the generic interface to i2c buses available in
19 * system. This interface may be used by user applications or i2c-device
20 * drivers (like RTC, NVRAM, etc).
21 *
22 * Functions i2c_initialize and i2c_transfer declared in this header usually
23 * implemented in particular board support package. Usually this
24 * implementation is a simple wrapper or multiplexor to I2C controller
25 * driver which is available in system. It may be generic "software
26 * controller" I2C driver which control SDA and SCL signals directly (if SDA
27 * and SCL is general-purpose I/O pins), or driver for hardware I2C
28 * controller (standalone or integrated with processors: MBus controller in
29 * ColdFire processors, I2C controller in PowerQUICC and so on).
30 *
31 * i2c_transfer is a very generic low-level function. Higher-level function
32 * i2c_write, i2c_read, i2c_wrrd, i2c_wbrd is defined here too.
33 */
34
35/* I2C Bus Number type */
36typedef uint32_t i2c_bus_number;
37
38/* I2C device address */
39typedef uint16_t i2c_address;
40
41/* I2C error codes generated during message transfer */
42typedef enum i2c_message_status {
43 I2C_SUCCESSFUL = 0,
45 I2C_NO_DEVICE,
46 I2C_ARBITRATION_LOST,
47 I2C_NO_ACKNOWLEDGE,
48 I2C_NO_DATA,
49 I2C_RESOURCE_NOT_AVAILABLE
50} i2c_message_status;
51
52/* I2C Message */
53typedef struct i2c_message {
54 i2c_address addr; /* I2C slave device address */
55 uint16_t flags; /* message flags (see below) */
56 i2c_message_status status; /* message transfer status code */
57 uint16_t len; /* Number of bytes to read or write */
58 uint8_t *buf; /* pointer to data array */
60
61/* I2C message flag */
62#define I2C_MSG_ADDR_10 (0x01) /* 10-bit address */
63#define I2C_MSG_WR (0x02) /* transfer direction for this message
64 from master to slave */
65#define I2C_MSG_ERRSKIP (0x04) /* Skip message if last transfered message
66 is failed */
67/* Type for function which is called when transfer over I2C bus is finished */
68typedef void (*i2c_transfer_done) (void *arg);
69
70/* i2c_initialize --
71 * I2C driver initialization. This function usually called on device
72 * driver initialization state, before initialization task. All I2C
73 * buses are initialized; reasonable slow data transfer rate is
74 * selected for each bus.
75 *
76 * PARAMETERS:
77 * major - I2C device major number
78 * minor - I2C device minor number
79 * arg - RTEMS driver initialization argument
80 *
81 * RETURNS:
82 * RTEMS status code
83 */
85i2c_initialize(rtems_device_major_number major,
86 rtems_device_minor_number minor,
87 void *arg);
88
89/* i2c_select_clock_rate --
90 * select I2C bus clock rate for specified bus. Some bus controller do not
91 * allow to select arbitrary clock rate; in this case nearest possible
92 * slower clock rate is selected.
93 *
94 * PARAMETERS:
95 * bus - I2C bus number
96 * bps - data transfer rate for this bytes in bits per second
97 *
98 * RETURNS:
99 * RTEMS_SUCCESSFUL, if operation performed successfully,
100 * RTEMS_INVALID_NUMBER, if wrong bus number is specified,
101 * RTEMS_UNSATISFIED, if bus do not support data transfer rate selection
102 * or specified data transfer rate could not be used.
103 */
105i2c_select_clock_rate(i2c_bus_number bus, int bps);
106
107/* i2c_transfer --
108 * Initiate multiple-messages transfer over specified I2C bus or
109 * put request into queue if bus or some other resource is busy. (This
110 * is non-blocking function).
111 *
112 * PARAMETERS:
113 * bus - I2C bus number
114 * nmsg - number of messages
115 * msg - pointer to messages array
116 * done - function which is called when transfer is finished
117 * done_arg_ptr - arbitrary argument ptr passed to done funciton
118 *
119 * RETURNS:
120 * RTEMS_SUCCESSFUL if transfer initiated successfully, or error
121 * code if something failed.
122 */
124i2c_transfer(i2c_bus_number bus, int nmsg, i2c_message *msg,
125 i2c_transfer_done done, void * done_arg_ptr);
126
127/* i2c_transfer_wait --
128 * Initiate I2C bus transfer and block until this transfer will be
129 * finished. This function wait the semaphore if system in
130 * SYSTEM_STATE_UP state, or poll done flag in other states.
131 *
132 * PARAMETERS:
133 * bus - I2C bus number
134 * msg - pointer to transfer messages array
135 * nmsg - number of messages in transfer
136 *
137 * RETURNS:
138 * I2C_SUCCESSFUL, if transfer finished successfully,
139 * I2C_RESOURCE_NOT_AVAILABLE, if semaphore operations has failed,
140 * value of status field of first error-finished message in transfer,
141 * if something wrong.
142 */
143i2c_message_status
144i2c_transfer_wait(i2c_bus_number bus, i2c_message *msg, int nmsg);
145
146/* i2c_poll --
147 * Poll I2C bus controller for events and hanle it. This function is
148 * used when I2C driver operates in poll-driven mode.
149 *
150 * PARAMETERS:
151 * bus - bus number to be polled
152 *
153 * RETURNS:
154 * none
155 */
156void
157i2c_poll(i2c_bus_number bus);
158
159/* i2c_write --
160 * Send single message over specified I2C bus to addressed device and
161 * wait while transfer is finished.
162 *
163 * PARAMETERS:
164 * bus - I2C bus number
165 * addr - address of I2C device
166 * buf - data to be sent to device
167 * size - data buffer size
168 *
169 * RETURNS:
170 * transfer status
171 */
172i2c_message_status
173i2c_write(i2c_bus_number bus, i2c_address addr, void *buf, int size);
174
175/* i2c_wrbyte --
176 * Send single one-byte long message over specified I2C bus to
177 * addressed device and wait while transfer is finished.
178 *
179 * PARAMETERS:
180 * bus - I2C bus number
181 * addr - address of I2C device
182 * cmd - byte message to be sent to device
183 *
184 * RETURNS:
185 * transfer status
186 */
187i2c_message_status
188i2c_wrbyte(i2c_bus_number bus, i2c_address addr, uint8_t cmd);
189
190/* i2c_read --
191 * receive single message over specified I2C bus from addressed device.
192 * This call will wait while transfer is finished.
193 *
194 * PARAMETERS:
195 * bus - I2C bus number
196 * addr - address of I2C device
197 * buf - buffer for received message
198 * size - receive buffer size
199 *
200 * RETURNS:
201 * transfer status
202 */
203i2c_message_status
204i2c_read(i2c_bus_number bus, i2c_address addr, void *buf, int size);
205
206/* i2c_wrrd --
207 * Send message over I2C bus to specified device and receive message
208 * from the same device during single transfer.
209 *
210 * PARAMETERS:
211 * bus - I2C bus number
212 * addr - address of I2C device
213 * bufw - data to be sent to device
214 * sizew - send data buffer size
215 * bufr - buffer for received message
216 * sizer - receive buffer size
217 *
218 * RETURNS:
219 * transfer status
220 */
221i2c_message_status
222i2c_wrrd(i2c_bus_number bus, i2c_address addr, void *bufw, int sizew,
223 void *bufr, int sizer);
224
225/* i2c_wbrd --
226 * Send one-byte message over I2C bus to specified device and receive
227 * message from the same device during single transfer.
228 *
229 * PARAMETERS:
230 * bus - I2C bus number
231 * addr - address of I2C device
232 * cmd - one-byte message to be sent over I2C bus
233 * bufr - buffer for received message
234 * sizer - receive buffer size
235 *
236 * RETURNS:
237 * transfer status
238 */
239i2c_message_status
240i2c_wbrd(i2c_bus_number bus, i2c_address addr, uint8_t cmd,
241 void *bufr, int sizer);
242
243#endif
Evaluate BSP Related Configuration Options.
rtems_status_code
Classic API Status.
Definition: status.h:43
#define I2C_TIMEOUT
Sets the transfer timeout in 10ms units.
Definition: i2c-dev.h:53
Definition: i2c.h:53
Definition: b1553brm.c:75
unsigned size
Definition: tte.h:1