Warning, /cpukit/libi2c/README.md is written in an unsupported language. File is not indexed.
0001 Copyright and License
0002 ---------------------
0003
0004 For Copyright and License of the source code, see the header in
0005 libi2c.c.
0006
0007 Overview
0008 --------
0009
0010 This directory contains a general I2C/SPI API library. It offers a
0011 standard API to I2C or SPI based device drivers, abstracting the low
0012 level driver (dealing with the I2C/SPI controller hardware of the
0013 board) from the high-level drivers (dealing with devices connected to
0014 the I2C or SPI bus).
0015
0016 In most cases throughout this document, i2c and spi devices are
0017 handled in a similar way. Therefore spi will not be explicitly named
0018 in every location.
0019
0020
0021 Features
0022 ---------
0023
0024 + supports multiple i2c and/or spi busses
0025 + supports multiple devices connected to each i2c/spi bus
0026 + handles bus and device registration to the I/O manager
0027
0028 Structure
0029 ---------
0030
0031 This library defines a layered API to i2c and spi devices. The
0032 layering is:
0033
0034 ```
0035 +----------------------------------------+
0036 6| Application |
0037 +----------------------------------------+
0038 5| RTEMS I/O Manager |
0039 +----------------------------------------+
0040 4|** libi2c OS adaption layer **|
0041 +----------------------------------------+
0042 3| high level i2c device driver |
0043 | (EEPROM, RTC, ...) |
0044 | (e.g. in c/src/libchip/i2c) |
0045 +----------------------------------------+
0046 2|** libi2c low level abstraction layer **|
0047 +----------------------------------------+
0048 1| i2c controller driver |
0049 | (in BSP) |
0050 +----------------------------------------+
0051 ```
0052
0053 This document will describe the following interfaces in separate
0054 sections:
0055
0056 + the interface between the RTEMS I/O Manager and the libi2c OS
0057 interface (5<->4)
0058
0059 + the interface between the libi2c OS interface and the high level
0060 i2c device driver (4<->3)
0061
0062 + the interface between the high level i2c device driver and the
0063 libi2c low level abstraction layer (3<->2)
0064
0065 + the interface between the libi2c low level abstraction layer and
0066 the i2c controller driver (2<->1)
0067
0068
0069 Differences between i2c and spi bus
0070 -----------------------------------
0071 SPI and I2C has many similarities, but also some differences:
0072
0073 - I2C uses inband addressing (the first bits sent select, which slave
0074 device is addressed) while SPI uses dedicated select lines to address
0075 a slave device
0076
0077 - SPI supports combined full duplex read-write transactions while I2C
0078 either sends or receives data from a slave device
0079
0080 - SPI supports a varity of per-slave options, which include:
0081 - number of bits per character to transfer
0082 - polarity and phase of clock wrt data
0083 - clock frequency
0084
0085 The libi2c API defines a superset of functions to handle both flavours
0086 of serial data transmission, but care should be taken not to use
0087 features dedicated to the wrong type of serial bus.
0088
0089
0090 Library Initialization
0091 ----------------------
0092 Before any libi2c API is used, the library must be initialized. This
0093 is achived with a call to function
0094
0095 rtems_libi2c_initialize ().
0096
0097 It creates a global mutex to lock internal data structures and
0098 registers the OS adaption layer to the RTEMS I/O manager.
0099
0100 Any subsequent call to this function will be silently ignored.
0101
0102 Typically the BSP startup code will perform this initialization.
0103
0104 A proper place for initializing the i2c layer and populating it
0105 with busses and device drivers (see 'Bus Registration' and
0106 'Device/Driver Registration' below) is the 'predriver_hook'
0107 where most facilities (such as malloc, libio) are already
0108 available. Note, however, that 'stdio' is not yet functional
0109 at this point and all i2c bus and device drivers should carefully
0110 avoid using stdio so that other drivers which may build on top
0111 of i2c devices may be initialized properly (this may happen
0112 just after 'predriver_hook' when stdio is still not available).
0113 E.g., drivers listed in the configuration table are initialized
0114 during this step.
0115
0116 Note that while 'libi2c' could be initialized from the rtems
0117 configuration table like other drivers there is no easy
0118 way of populating the i2c framework with bus- and device-
0119 drivers at this point (unless a special 'i2c' configuration
0120 table describing the bus layout is implemented in the future).
0121
0122 For the time being, we must rely on the BSP (predriver_hook)
0123 to initialize the i2c system if it is used by other drivers
0124 (e.g., the RTC driver may have to use a i2c device).
0125
0126
0127 Bus Registration
0128 ----------------
0129 Each i2c and/or spi bus available must be registerd with a call to
0130
0131 int rtems_libi2c_register_bus (char *name,
0132 rtems_libi2c_bus_t * bus)
0133
0134 It registers the bus to the libi2c internal data structures and
0135 creates a device node in the RTEMS filesystem with the given name. If
0136 no name is given (name==NULL), then the default name "/dev/i2c" is
0137 used instead.
0138
0139 With the second calling parameter "rtems_libi2c_bus_t * bus" the
0140 caller passes in a set of function pointers, which define the entries
0141 into the i2c controller driver (defined in the BSP).
0142
0143 This call returns an integer bus number, which can be used in
0144 subsequent calls to register devices attached to this bus (see below).
0145
0146 Typically the BSP startup code will perform this registration for each
0147 bus available on the board.
0148
0149
0150 Device/Driver Registration
0151 --------------------------
0152 Each device attached to an i2c or spi bus must be registered with a
0153 call to
0154
0155 int
0156 rtems_libi2c_register_drv (char *name, rtems_libi2c_drv_t * drvtbl,
0157 unsigned bus, unsigned i2caddr);
0158
0159 With this call, libi2c is informed, that:
0160
0161 - a device is attached to the given "bus" number (which in fact is the
0162 return value received from a previous rtems_libi2c_register_bus()
0163 call) with the address "i2caddr"
0164
0165 - the device is managed by a driver, who's entry functions are listed
0166 in "drvtbl"
0167
0168 - the device should be registered with the given "name" in the device
0169 tree of the filesystem.
0170
0171 The call will create a proper minor device number, which has the bus
0172 number and i2c_address encoded. This minor number is the return value
0173 of the call and is also associated with the filesystem node created
0174 for this device.
0175
0176 Note: If you have multiple devices of the same type, you must register
0177 each of them through a separate call (with the same "drvtbl", but
0178 different name/bus/i2caddr).
0179
0180
0181 (5<->4) RTEMS I/O Manager and the libi2c OS adaption layer IF
0182 -------------------------------------------------------------
0183
0184 The RTEMS I/O Manager regards the libi2c OS adaption layer as a normal
0185 RTEMS Device Driver with one unique major number and a set of minor
0186 numbers, one for each bus and one for each device attached to one of
0187 the busses.
0188
0189 Therefore the libi2c OS adaption layer provides the standard calls:
0190
0191 ```c
0192 static rtems_driver_address_table libi2c_io_ops = {
0193 initialization_entry: i2c_init,
0194 open_entry: i2c_open,
0195 close_entry: i2c_close,
0196 read_entry: i2c_read,
0197 write_entry: i2c_write,
0198 control_entry: i2c_ioctl
0199 };
0200 ```
0201
0202 These calls perform some parameter checking and then call the
0203 appropriate high level i2c device driver function, if available,
0204 according to the entries in the "drvtbl" passed in the
0205 rtems_libi2c_register_drv() call.
0206
0207 There are two exceptions: when i2c_read or i2c_write is called with a
0208 minor number specifying a bus (and not a device attached to the bus),
0209 then the respective transfer is performed as a raw byte stream
0210 transfer to the bus.
0211
0212 The main reason for the libi2c OS adaption layer is, that it
0213 dispatches the RTEMS I/O Manager calls to the proper device driver
0214 according to the minor number used.
0215
0216 libi2c OS adaption layer and the high level i2c device driver IF
0217 ----------------------------------------------------------------
0218
0219 Each high level i2c device driver provides a set of functions in the
0220 rtems_libi2c_drv_t data structure passed the libi2c when the device is
0221 registered (see "Device registration" above). These function directly match
0222 the RTEMS I/O Mangers calls "open", "close", "read", "write",
0223 "control", and they are passed the same arguments. Functions not
0224 needed may be omited (and replaced by a NULL pointer in
0225 rtems_libi2c_drv_t).
0226
0227 high level i2c device driver and libi2c low level abstraction layer IF
0228 ----------------------------------------------------------------------
0229 libi2c provides a set of functions for the high level drivers. These
0230 functions are:
0231
0232 ```c
0233 rtems_libi2c_send_start();
0234 rtems_libi2c_send_stop();
0235 rtems_libi2c_send_addr();
0236 rtems_libi2c_read_bytes();
0237 rtems_libi2c_write_bytes();
0238 rtems_libi2c_start_read_bytes();
0239 rtems_libi2c_start_write_bytes();
0240 rtems_libi2c_ioctl();
0241 ```
0242
0243 Please look into libi2c.h for the proper parameters and return codes.
0244
0245 These functions perform the proper i2c operations when called.
0246
0247 A typical access sequence for the I2C bus would be:
0248
0249 ```c
0250 rtems_libi2c_send_start();
0251 rtems_libi2c_send_addr();
0252 rtems_libi2c_write_bytes();
0253 rtems_libi2c_send_stop();
0254 ```
0255
0256 Alternatively, the rtems_libi2c_write_bytes() call could be relpaced
0257 with a
0258
0259 ```c
0260 rtems_libi2c_read_bytes()
0261 ```
0262 call or a sequence of multiple calls.
0263
0264 Note: rtems_libi2c_send_start() locks the i2c/spi bus used, so no other
0265 device can use this i2c/spi bus, until rtems_libi2c_send_stop() function
0266 is called for the same device.
0267
0268
0269 Special provisions for SPI devices:
0270 -----------------------------------
0271 For SPI devices and their drivers, the libi2c interface is used
0272 slightly differently:
0273
0274 rtems_libi2c_send_start() will lock access to the SPI bus, but has no
0275 effect on the hardware bus interface.
0276
0277 rtems_libi2c_ioctl(...,RTEMS_LIBI2C_IOCTL_SET_TFRMODE,...) will set
0278 the transfer mode (bit rate, clock phase and polaritiy, bits per
0279 char...) according to the rtems_libi2c_tfr_mode_t structure passed in.
0280
0281 rtems_libi2c_send_addr() will activate the proper select line to
0282 address a certain SPI device. The correspondance between an address
0283 and the select line pulled is BSP specific.
0284
0285 rtems_libi2c_send_stop(); will deactivate the address line and unlock
0286 the bus.
0287
0288 A typical access sequence for the SPI bus would be:
0289
0290 ```c
0291 rtems_libi2c_send_start();
0292 rtems_libi2c_ioctl(...,RTEMS_LIBI2C_IOCTL_SET_TFRMODE,...);
0293 rtems_libi2c_send_addr();
0294 rtems_libi2c_write_bytes();
0295 rtems_libi2c_send_stop();
0296 ```
0297
0298 Alternatively, the rtems_libi2c_write_bytes() call could be relpaced
0299 with a
0300 ```c
0301 rtems_libi2c_read_bytes()
0302 ```
0303 or a
0304 ```c
0305 rtems_libi2c_ioctl(...,RTEMS_LIBI2C_IOCTL_READ_WRITE,...)
0306 ```
0307 call or a sequence of multiple calls.
0308
0309
0310 libi2c low level abstraction layer and i2c controller driver IF
0311 ---------------------------------------------------------------
0312 Each low level i2c/spi driver must provide a set of bus_ops functions
0313 as defined in the rtems_libi2c_bus_ops_t structure.
0314
0315 ```c
0316 typedef struct rtems_libi2c_bus_ops_
0317 {
0318 /* Initialize the bus; might be called again to reset the bus driver */
0319 rtems_status_code (*init) (rtems_libi2c_bus_t * bushdl);
0320 /* Send start condition */
0321 rtems_status_code (*send_start) (rtems_libi2c_bus_t * bushdl);
0322 /* Send stop condition */
0323 rtems_status_code (*send_stop) (rtems_libi2c_bus_t * bushdl);
0324 /* initiate transfer from (rw!=0) or to a device */
0325 rtems_status_code (*send_addr) (rtems_libi2c_bus_t * bushdl,
0326 uint32_t addr, int rw);
0327 /* read a number of bytes */
0328 int (*read_bytes) (rtems_libi2c_bus_t * bushdl, unsigned char *bytes,
0329 int nbytes);
0330 /* write a number of bytes */
0331 int (*write_bytes) (rtems_libi2c_bus_t * bushdl, unsigned char *bytes,
0332 int nbytes);
0333 /* ioctl misc functions */
0334 int (*ioctl) (rtems_libi2c_bus_t * bushdl,
0335 int cmd,
0336 void *buffer;
0337 );
0338 } rtems_libi2c_bus_ops_t;
0339 ```
0340
0341 Each of these functions performs the corresponding function to the i2c
0342 bus.
0343
0344
0345 Special provisions for SPI devices:
0346 -----------------------------------
0347 For SPI busses, special behaviour is required:
0348
0349 ```c
0350 (*send_start) (rtems_libi2c_bus_t * bushdl)
0351 normally is an empty function.
0352
0353 (*send_addr) (rtems_libi2c_bus_t * bushdl, uint32_t addr, int rw)
0354 will activate the SPI select line matching to addr.
0355
0356 (*send_stop) (rtems_libi2c_bus_t * bushdl)
0357 will deactivate the SPI select line
0358
0359 (*ioctl(...,RTEMS_LIBI2C_IOCTL_SET_TFRMODE,...)
0360 will set the transfer mode (bit rate, clock phase and
0361 polaritiy, bits per char...) according to the
0362 rtems_libi2c_tfr_mode_t structure passed in.
0363
0364 (*ioctl(...,RTEMS_LIBI2C_IOCTL_READ_WRITE,...)
0365 will send and receive data at the same time.
0366 ```
0367
0368 Note:
0369 - low-level I2C drivers normally are specific to the master
0370 device, but independent from the board hardware. So in many cases they
0371 can totally reside in libcpu or libchip.
0372
0373 - low-level SPI drivers are mostly board independent, but the
0374 addressing is board/BSP dependent. Therefore the (*send_start),
0375 (*send_addr) and (*send_stop) functions are typically defined in the
0376 BSP. The rest of the functions can reside in libcpu or libchip.
