RTEMS  5.0.0
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 */
36 typedef uint32_t i2c_bus_number;
37 
38 /* I2C device address */
39 typedef uint16_t i2c_address;
40 
41 /* I2C error codes generated during message transfer */
42 typedef 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 */
53 typedef 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 */
59 } i2c_message;
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 */
68 typedef 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  */
85 i2c_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  */
105 i2c_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  */
124 i2c_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  */
143 i2c_message_status
144 i2c_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  */
156 void
157 i2c_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  */
172 i2c_message_status
173 i2c_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  */
187 i2c_message_status
188 i2c_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  */
203 i2c_message_status
204 i2c_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  */
221 i2c_message_status
222 i2c_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  */
239 i2c_message_status
240 i2c_wbrd(i2c_bus_number bus, i2c_address addr, uint8_t cmd,
241  void *bufr, int sizer);
242 
243 #endif
rtems_status_code
Classic API Status.
Definition: status.h:43
Definition: b1553brm.c:75
Definition: i2c.h:53
Global BSP definitions.
unsigned size
Definition: tte.h:74
#define I2C_TIMEOUT
Sets the transfer timeout in 10ms units.
Definition: i2c-dev.h:53