source: rtems/c/src/lib/libbsp/m68k/mcf5206elite/include/i2c.h @ 296846a

4.115
Last change on this file since 296846a was 296846a, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 14, 2015 at 10:23:53 PM

mcf5206elite/include/i2c.h: Fix spelling error

  • Property mode set to 100644
File size: 7.7 KB
Line 
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,
44    I2C_TIMEOUT,
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 */
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 */
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 */
84rtems_device_driver
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 */
104rtems_status_code
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 */
123rtems_status_code
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
Note: See TracBrowser for help on using the repository browser.