1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
#ifndef RTEMS_LIBI2C_H
#define RTEMS_LIBI2C_H
/*$Id$*/
#include <rtems.h>
#include <rtems/io.h>
#ifdef __cplusplus
extern "C" {
#endif
/* Simple I2C driver API */
/* Initialize the libary - may fail if no semaphore or no driver slot is available */
int rtems_libi2c_initialize ();
/* Bus Driver API
*
* Bus drivers provide access to low-level i2c functions
* such as 'send start', 'send address', 'get bytes' etc.
*/
/* first field must be a pointer to ops; driver
* may add its own fields after this.
* the struct that is registered with the library
* is not copied; a pointer will we passed
* to the callback functions (ops).
*/
typedef struct rtems_libi2c_bus_t_
{
struct rtems_libi2c_bus_ops_ *ops;
int size; /* size of whole structure */
} rtems_libi2c_bus_t;
/* Access functions a low level driver must provide;
*
* All of these, except read_bytes and write_bytes
* return RTEMS_SUCCESSFUL on success and an error status
* otherwise. The read and write ops return the number
* of chars read/written or -(status code) on error.
*/
typedef struct rtems_libi2c_bus_ops_
{
/* Initialize the bus; might be called again to reset the bus driver */
rtems_status_code (*init) (rtems_libi2c_bus_t * bushdl);
/* Send start condition */
rtems_status_code (*send_start) (rtems_libi2c_bus_t * bushdl);
/* Send stop condition */
rtems_status_code (*send_stop) (rtems_libi2c_bus_t * bushdl);
/* initiate transfer from (rw!=0) or to a device */
rtems_status_code (*send_addr) (rtems_libi2c_bus_t * bushdl,
uint32_t addr, int rw);
/* read a number of bytes */
int (*read_bytes) (rtems_libi2c_bus_t * bushdl, unsigned char *bytes,
int nbytes);
/* write a number of bytes */
int (*write_bytes) (rtems_libi2c_bus_t * bushdl, unsigned char *bytes,
int nbytes);
} rtems_libi2c_bus_ops_t;
/*
* Register a lowlevel driver
*
* TODO: better description
*
* This allocates a major number identifying *this* driver
* (i.e., libi2c) and the minor number encodes a bus# and a i2c address.
*
* The name will be registered in the filesystem (parent
* directories must exist). It may be NULL in which case
* the library will pick a default.
*
* RETURNS: bus # (>=0) or -1 on error (errno set).
*/
int rtems_libi2c_register_bus (char *name, rtems_libi2c_bus_t * bus);
extern rtems_device_major_number rtems_libi2c_major;
#define RTEMS_LIBI2C_MAKE_MINOR(busno, i2caddr) \
((((busno)&((1<<3)-1))<<10) | ((i2caddr)&((1<<10)-1)))
/* After the library is initialized, a major number is available.
* As soon as a low-level bus driver is registered (above routine
* returns a 'busno'), a device node can be created in the filesystem
* with a major/minor number pair of
*
* rtems_libi2c_major / RTEMS_LIBI2C_MAKE_MINOR(busno, i2caddr)
*
* and a 'raw' hi-level driver is then attached to this device
* node.
* This 'raw' driver has very simple semantics:
*
* 'open' sends a start condition
* 'read'/'write' address the device identified by the i2c bus# and address
* encoded in the minor number and read or write, respectively
* a stream of bytes from or to the device. Every time the
* direction is changed, a 're-start' condition followed by
* an 'address' cycle is generated on the i2c bus.
* 'close' sends a stop condition.
*
* Hence, using the 'raw' driver, e.g., 100 bytes at offset 0x200 can be
* read from an EEPROM by the following pseudo-code:
*
* mknod("/dev/i2c-54", mode, MKDEV(rtems_libi2c_major, RTEMS_LIBI2C_MAKE_MINOR(0,0x54)))
*
* int fd;
* char off[2]={0x02,0x00};
*
* fd = open("/dev/i2c-54",O_RDWR);
* write(fd,off,2);
* read(fd,buf,100);
* close(fd);
*
*/
/* Higher Level Driver API
*
* Higher level drivers know how to deal with specific i2c
* devices (independent of the bus interface chip) and provide
* an abstraction, i.e., the usual read/write/ioctl access.
*
* Using the above example, such a high level driver could
* prevent the user from issuing potentially destructive write
* operations (the aforementioned EEPROM interprets any 3rd
* and following byte written to the device as data, i.e., the
* contents could easily be changed!).
* The correct 'read-pointer offset' programming could be
* implemented in 'open' and 'ioctl' of a high-level driver and
* the user would then only have to perform harmless read
* operations, e.g.,
*
* fd = open("/dev/i2c.eeprom",O_RDONLY) / * opens and sets EEPROM read pointer * /
* ioctl(fd, IOCTL_SEEK, 0x200) / * repositions the read pointer * /
* read(fd, buf, 100)
* close(fd)
*
*/
/* struct provided at driver registration. The driver may store
* private data behind the mandatory first fields but the size
* must be set to the size of the entire struct, e.g.,
*
* struct driver_pvt {
* rtems_libi2c_drv_t pub;
* struct { ... } pvt;
* } my_driver = {
* { ops: my_ops,
* size: sizeof(my_driver)
* },
* { ...};
* };
*
* A pointer to this struct is passed to the callback ops.
*/
typedef struct rtems_libi2c_drv_t_
{
rtems_driver_address_table *ops; /* the driver ops */
int size; /* size of whole structure (including appended private data) */
} rtems_libi2c_drv_t;
/*
* The high level driver must be registered with a particular
* bus number and i2c address.
*
* The registration procedure also creates a filesystem node,
* i.e., the returned minor number is not really needed.
*
* If the 'name' argument is NULL, no filesystem node is
* created (but this can be done 'manually' using rtems_libi2c_major
* and the return value of this routine).
*
* RETURNS minor number (FYI) or -1 on failure
*/
int
rtems_libi2c_register_drv (char *name, rtems_libi2c_drv_t * drvtbl,
unsigned bus, unsigned i2caddr);
/* Operations available to high level drivers */
/* NOTES: The bus a device is attached to is LOCKED from the first send_start
* until send_stop is executed!
*
* Bus tenure MUST NOT span multiple system calls - otherwise, a single
* thread could get into the protected sections (or would deadlock if the
* mutex was not nestable).
* E.g., consider what happens if 'open' sends a 'start' and 'close'
* sends a 'stop' (i.e., the bus mutex would be locked in 'open' and
* released in 'close'. A single thread could try to open two devices
* on the same bus and would either deadlock or nest into the bus mutex
* and potentially mess up the i2c messages.
*
* The correct way is to *always* relinquish the i2c bus (i.e., send 'stop'
* from any driver routine prior to returning control to the caller.
* Consult the implementation of the generic driver routines (open, close, ...)
* below or the examples in i2c-2b-eeprom.c and i2c-2b-ds1621.c
*
* Drivers just pass the minor number on to these routines...
*/
rtems_status_code rtems_libi2c_send_start (rtems_device_minor_number minor);
rtems_status_code rtems_libi2c_send_stop (rtems_device_minor_number minor);
rtems_status_code
rtems_libi2c_send_addr (rtems_device_minor_number minor, int rw);
/* the read/write routines return the number of bytes transferred
* or -(status_code) on error.
*/
int
rtems_libi2c_read_bytes (rtems_device_minor_number minor,
unsigned char *bytes, int nbytes);
int
rtems_libi2c_write_bytes (rtems_device_minor_number minor,
unsigned char *bytes, int nbytes);
/* Send start, send address and read bytes */
int
rtems_libi2c_start_read_bytes (uint32_t minor, unsigned char *bytes,
int nbytes);
/* Send start, send address and write bytes */
int
rtems_libi2c_start_write_bytes (uint32_t minor, unsigned char *bytes,
int nbytes);
#ifdef __cplusplus
}
#endif
#endif
|
