source: rtems/cpukit/libi2c/libi2c.h @ 55a685b

4.104.114.9
Last change on this file since 55a685b was 55a685b, checked in by Thomas Doerfler <Thomas.Doerfler@…>, on Oct 25, 2007 at 4:17:56 PM

added SPI support to libi2c
added IRQ support to MPC83xx i2c driver
added mpc83xx spi driver

  • Property mode set to 100644
File size: 12.9 KB
Line 
1#ifndef RTEMS_LIBI2C_H
2#define RTEMS_LIBI2C_H
3/*$Id$*/
4
5/*
6 * Authorship
7 * ----------
8 * This software was created by
9 *     Till Straumann <strauman@slac.stanford.edu>, 2005,
10 *         Stanford Linear Accelerator Center, Stanford University.
11 *
12 * Acknowledgement of sponsorship
13 * ------------------------------
14 * This software was produced by
15 *     the Stanford Linear Accelerator Center, Stanford University,
16 *         under Contract DE-AC03-76SFO0515 with the Department of Energy.
17 *
18 * Government disclaimer of liability
19 * ----------------------------------
20 * Neither the United States nor the United States Department of Energy,
21 * nor any of their employees, makes any warranty, express or implied, or
22 * assumes any legal liability or responsibility for the accuracy,
23 * completeness, or usefulness of any data, apparatus, product, or process
24 * disclosed, or represents that its use would not infringe privately owned
25 * rights.
26 *
27 * Stanford disclaimer of liability
28 * --------------------------------
29 * Stanford University makes no representations or warranties, express or
30 * implied, nor assumes any liability for the use of this software.
31 *
32 * Stanford disclaimer of copyright
33 * --------------------------------
34 * Stanford University, owner of the copyright, hereby disclaims its
35 * copyright and all other rights in this software.  Hence, anyone may
36 * freely use it for any purpose without restriction. 
37 *
38 * Maintenance of notices
39 * ----------------------
40 * In the interest of clarity regarding the origin and status of this
41 * SLAC software, this and all the preceding Stanford University notices
42 * are to remain affixed to any copy or derivative of this software made
43 * or distributed by the recipient and are to be affixed to any copy of
44 * software made or distributed by the recipient that contains a copy or
45 * derivative of this software.
46 *
47 * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
48 */ 
49
50#include <rtems.h>
51
52#include <rtems/io.h>
53
54#ifdef __cplusplus
55extern "C" {
56#endif
57
58/* Simple I2C driver API */
59
60/* Initialize the libary - may fail if no semaphore or no driver slot is available */
61int rtems_libi2c_initialize ();
62
63/* Bus Driver API
64 *
65 * Bus drivers provide access to low-level i2c functions
66 * such as 'send start', 'send address', 'get bytes' etc.
67 */
68
69/* first field must be a pointer to ops; driver
70 * may add its own fields after this.
71 * the struct that is registered with the library
72 * is not copied; a pointer will we passed
73 * to the callback functions (ops).
74 */
75typedef struct rtems_libi2c_bus_t_
76{
77  struct rtems_libi2c_bus_ops_ *ops;
78  int size;                     /* size of whole structure */
79} rtems_libi2c_bus_t;
80
81/* Access functions a low level driver must provide;
82 *
83 * All of these, except read_bytes and write_bytes
84 * return RTEMS_SUCCESSFUL on success and an error status
85 * otherwise. The read and write ops return the number
86 * of chars read/written or -(status code) on error.
87 */
88typedef struct rtems_libi2c_bus_ops_
89{
90  /* Initialize the bus; might be called again to reset the bus driver */
91  rtems_status_code (*init) (rtems_libi2c_bus_t * bushdl);
92  /* Send start condition */
93  rtems_status_code (*send_start) (rtems_libi2c_bus_t * bushdl);
94  /* Send stop  condition */
95  rtems_status_code (*send_stop) (rtems_libi2c_bus_t * bushdl);
96  /* initiate transfer from (rw!=0) or to a device */
97  rtems_status_code (*send_addr) (rtems_libi2c_bus_t * bushdl,
98                                  uint32_t addr, int rw);
99  /* read a number of bytes */
100  int (*read_bytes) (rtems_libi2c_bus_t * bushdl, unsigned char *bytes,
101                     int nbytes);
102  /* write a number of bytes */
103  int (*write_bytes) (rtems_libi2c_bus_t * bushdl, unsigned char *bytes,
104                      int nbytes);
105  /* ioctl misc functions */
106  int (*ioctl) (rtems_libi2c_bus_t * bushdl, 
107                int   cmd,
108                void *buffer;
109                );
110} rtems_libi2c_bus_ops_t;
111
112
113/*
114 * Register a lowlevel driver
115 *
116 * TODO: better description
117 *
118 * This  allocates a major number identifying *this* driver
119 * (i.e., libi2c) and the minor number encodes a bus# and a i2c address.
120 *
121 * The name will be registered in the filesystem (parent
122 * directories must exist, also IMFS filesystem must exist see
123 * CONFIGURE_USE_IMFS_AS_BASE_FILESYSTEM). It may be NULL in which case
124 * the library will pick a default.
125 *
126 * RETURNS: bus # (>=0) or -1 on error (errno set).
127 */
128
129int rtems_libi2c_register_bus (char *name, rtems_libi2c_bus_t * bus);
130
131extern rtems_device_major_number rtems_libi2c_major;
132
133#define RTEMS_LIBI2C_MAKE_MINOR(busno, i2caddr) \
134        ((((busno)&((1<<3)-1))<<10) | ((i2caddr)&((1<<10)-1)))
135
136/* After the library is initialized, a major number is available.
137 * As soon as a low-level bus driver is registered (above routine
138 * returns a 'busno'), a device node can be created in the filesystem
139 * with a major/minor number pair of
140 *
141 *    rtems_libi2c_major / RTEMS_LIBI2C_MAKE_MINOR(busno, i2caddr)
142 *
143 * and a 'raw' hi-level driver is then attached to this device
144 * node.
145 * This 'raw' driver has very simple semantics:
146 *
147 *   'open'         sends a start condition
148 *   'read'/'write' address the device identified by the i2c bus# and address
149 *                  encoded in the minor number and read or write, respectively
150 *                  a stream of bytes from or to the device. Every time the
151 *                  direction is changed, a 're-start' condition followed by
152 *                  an 'address' cycle is generated on the i2c bus.
153 *   'close'        sends a stop condition.
154 *
155 * Hence, using the 'raw' driver, e.g., 100 bytes at offset 0x200 can be
156 * read from an EEPROM by the following pseudo-code:
157 *
158 *   mknod("/dev/i2c-54", mode, MKDEV(rtems_libi2c_major, RTEMS_LIBI2C_MAKE_MINOR(0,0x54)))
159 *
160 *   int fd;
161 *   char off[2]={0x02,0x00};
162 *
163 *   fd = open("/dev/i2c-54",O_RDWR);
164 *   write(fd,off,2);
165 *   read(fd,buf,100);
166 *   close(fd);
167 *
168 */
169
170/* Higher Level Driver API
171 *
172 * Higher level drivers know how to deal with specific i2c
173 * devices (independent of the bus interface chip) and provide
174 * an abstraction, i.e., the usual read/write/ioctl access.
175 *
176 * Using the above example, such a high level driver could
177 * prevent the user from issuing potentially destructive write
178 * operations (the aforementioned EEPROM interprets any 3rd
179 * and following byte written to the device as data, i.e., the
180 * contents could easily be changed!).
181 * The correct 'read-pointer offset' programming could be
182 * implemented in 'open' and 'ioctl' of a high-level driver and
183 * the user would then only have to perform harmless read
184 * operations, e.g.,
185 *
186 *    fd = open("/dev/i2c.eeprom",O_RDONLY) / * opens and sets EEPROM read pointer * /
187 *    ioctl(fd, IOCTL_SEEK, 0x200)                      / * repositions the read pointer       * /
188 *    read(fd, buf, 100)
189 *    close(fd)
190 *
191 */
192
193/* struct provided at driver registration. The driver may store
194 * private data behind the mandatory first fields but the size
195 * must be set to the size of the entire struct, e.g.,
196 *
197 * struct driver_pvt {
198 *      rtems_libi2c_drv_t pub;
199 *      struct {  ...    } pvt;
200 * } my_driver = {
201 *              {  ops: my_ops,
202 *                size: sizeof(my_driver)
203 *              },
204 *              { ...};
205 * };
206 *
207 * A pointer to this struct is passed to the callback ops.
208 */
209
210typedef struct rtems_libi2c_drv_t_
211{
212  rtems_driver_address_table *ops;      /* the driver ops */
213  int size;                     /* size of whole structure (including appended private data) */
214} rtems_libi2c_drv_t;
215
216/*
217 * The high level driver must be registered with a particular
218 * bus number and i2c address.
219 *
220 * The registration procedure also creates a filesystem node,
221 * i.e., the returned minor number is not really needed.
222 *
223 * If the 'name' argument is NULL, no filesystem node is
224 * created (but this can be done 'manually' using rtems_libi2c_major
225 * and the return value of this routine).
226 *
227 * RETURNS minor number (FYI) or -1 on failure
228 */
229int
230rtems_libi2c_register_drv (char *name, rtems_libi2c_drv_t * drvtbl,
231                           unsigned bus, unsigned i2caddr);
232
233/* Operations available to high level drivers */
234
235/* NOTES: The bus a device is attached to is LOCKED from the first send_start
236 *        until send_stop is executed!
237 *
238 *        Bus tenure MUST NOT span multiple system calls - otherwise, a single
239 *        thread could get into the protected sections (or would deadlock if the
240 *                mutex was not nestable).
241 *                E.g., consider what happens if 'open' sends a 'start' and 'close'
242 *                sends a 'stop' (i.e., the bus mutex would be locked in 'open' and
243 *        released in 'close'. A single thread could try to open two devices
244 *        on the same bus and would either deadlock or nest into the bus mutex
245 *        and potentially mess up the i2c messages.
246 *
247 *        The correct way is to *always* relinquish the i2c bus (i.e., send 'stop'
248 *                from any driver routine prior to returning control to the caller.
249 *                Consult the implementation of the generic driver routines (open, close, ...)
250 *                below or the examples in i2c-2b-eeprom.c and i2c-2b-ds1621.c
251 *
252 * Drivers just pass the minor number on to these routines...
253 */
254rtems_status_code rtems_libi2c_send_start (rtems_device_minor_number minor);
255
256rtems_status_code rtems_libi2c_send_stop (rtems_device_minor_number minor);
257
258rtems_status_code
259rtems_libi2c_send_addr (rtems_device_minor_number minor, int rw);
260
261/* the read/write routines return the number of bytes transferred
262 * or -(status_code) on error.
263 */
264int
265rtems_libi2c_read_bytes (rtems_device_minor_number minor,
266                         unsigned char *bytes, int nbytes);
267
268int
269rtems_libi2c_write_bytes (rtems_device_minor_number minor,
270                          unsigned char *bytes, int nbytes);
271
272/* Send start, send address and read bytes */
273int
274rtems_libi2c_start_read_bytes (rtems_device_minor_number minor, 
275                               unsigned char *bytes,
276                               int nbytes);
277
278/* Send start, send address and write bytes */
279int
280rtems_libi2c_start_write_bytes (rtems_device_minor_number minor, 
281                                unsigned char *bytes,
282                                int nbytes);
283
284
285/* call misc iocontrol function */
286int
287rtems_libi2c_ioctl (rtems_device_minor_number minor,
288                    int cmd,
289                    ...);
290/*
291 * NOTE: any low-level driver ioctl returning a negative
292 * result for release the bus (perform a STOP condition)
293 */
294/*******************************
295 * defined IOCTLs:
296 *******************************/
297#define RTEMS_LIBI2C_IOCTL_READ_WRITE  1
298/*
299 * retval = rtems_libi2c_ioctl(rtems_device_minor_number minor,
300 *                             RTEMS_LIBI2C_IOCTL_READ_WRITE,
301 *                              rtems_libi2c_read_write_t *arg);
302 *
303 * This call performs a simultanous read/write transfer,
304 * which is possible (and sometimes needed) for SPI devices
305 *
306 *   arg is a pointer to a rd_wr info data structure
307 *
308 * This call is only needed for SPI devices
309 */
310#define RTEMS_LIBI2C_IOCTL_START_TFM_READ_WRITE  2
311/*
312 * retval = rtems_libi2c_ioctl(rtems_device_minor_number minor,
313 *                             RTEMS_LIBI2C_IOCTL_START_READ_WRITE,
314 *                             unsigned char *rd_buffer,
315 *                             const unsigned char *wr_buffer,
316 *                             int byte_cnt,
317 *                             const rtems_libi2c_tfr_mode_t *tfr_mode_ptr);
318 *
319 * This call addresses a slave and then:
320 * - sets the proper transfer mode,
321 *  - performs a simultanous  read/write transfer,
322 *    (which is possible and sometimes needed for SPI devices)
323 *    NOTE: - if rd_buffer is NULL, receive data will be dropped
324 *          - if wr_buffer is NULL, bytes with content 0 will transmitted
325 *
326 *   rd_buffer is a pointer to a receive buffer (or NULL)
327 *   wr_buffer is a pointer to the data to be sent (or NULL)
328 *
329 * This call is only needed for SPI devices
330 */
331
332#define RTEMS_LIBI2C_IOCTL_SET_TFRMODE 3
333/*
334 * retval = rtems_libi2c_ioctl(rtems_device_minor_number minor,
335 *                             RTEMS_LIBI2C_IOCTL_SET_TFRMODE,
336 *                             const rtems_libi2c_tfr_mode_t *tfr_mode_ptr);
337 *
338 * This call sets an SPI device to the transfer mode needed (baudrate etc.)
339 *
340 *   tfr_mode is a pointer to a structure defining the SPI transfer mode needed
341 *   (see below).
342 *
343 * This call is only needed for SPI devices
344 */
345
346/*
347 * arguemtn data structures for IOCTLs defined above
348 */
349typedef struct {
350  unsigned char       *rd_buf;
351  const unsigned char *wr_buf;
352  int                  byte_cnt;
353} rtems_libi2c_read_write_t;
354
355typedef struct {
356  uint32_t baudrate;       /* maximum bits per second               */
357                           /* only valid for SPI drivers:           */
358  uint8_t  bits_per_char;  /* how many bits per byte/word/longword? */
359  boolean  lsb_first;      /* TRUE: send LSB first                  */
360  boolean  clock_inv;      /* TRUE: inverted clock (high active)    */
361  boolean  clock_phs;      /* TRUE: clock starts toggling at start of data tfr */
362} rtems_libi2c_tfr_mode_t;
363
364typedef struct {
365  rtems_libi2c_tfr_mode_t   tfr_mode;
366  rtems_libi2c_read_write_t rd_wr;
367} rtems_libi2c_tfm_read_write_t;
368
369
370#ifdef __cplusplus
371}
372#endif
373
374#endif
Note: See TracBrowser for help on using the repository browser.