Changeset c47890c in rtems for cpukit/libi2c


Ignore:
Timestamp:
Oct 26, 2007, 9:51:41 AM (12 years ago)
Author:
Thomas Doerfler <Thomas.Doerfler@…>
Branches:
4.10, 4.11, 4.9, master
Children:
7a4e8e7c
Parents:
83374f3
Message:

* empty log message *

File:
1 edited

Legend:

Unmodified
Added
Removed
  • cpukit/libi2c/README_libi2c

    r83374f3 rc47890c  
    7373  the i2c controller driver (2<->1)
    7474
     75===================================
     76Differences between i2c and spi bus
     77===================================
     78SPI and I2C has many similarities, but also some differences:
     79
     80- I2C uses inband addressing (the first bits sent select, which slave
     81device is addressed) while SPI uses dedicated select lines to address
     82a slave device
     83
     84- SPI supports combined full duplex read-write transactions while I2C
     85either sends or receives data from a slave device
     86
     87- SPI supports a varity of per-slave options, which include:
     88  - number of bits per character to transfer
     89  - polarity and phase of clock wrt data
     90  - clock frequency
     91
     92The libi2c API defines a superset of functions to handle both flavours
     93of serial data transmission, but care should be taken not to use
     94features dedicated to the wrong type of serial bus.
     95
    7596
    7697======================
     
    112133bus available on the board.
    113134
    114 ===================
    115 Device Registration
    116 ===================
    117 tbd
     135==========================
     136Device/Driver Registration
     137==========================
     138Each device attached to an i2c or spi bus must be registered with a
     139call to
     140
     141int
     142rtems_libi2c_register_drv (char *name, rtems_libi2c_drv_t * drvtbl,
     143                           unsigned bus, unsigned i2caddr);
     144
     145With this call, libi2c is informed, that:
     146
     147- a device is attached to the given "bus" number (which in fact is the
     148return value received from a previous rtems_libi2c_register_bus()
     149call) with the address "i2caddr"
     150
     151- the device is managed by a driver, who's entry functions are listed
     152  in "drvtbl"
     153
     154- the device should be registered with the given "name" in the device
     155  tree of the filesystem.
     156
     157The call will create a proper minor device number, which has the bus
     158number and i2c_address encoded. This minor number is the return value
     159of the call and is also associated with the filesystem node created
     160for this device.
     161
     162Note: If you have multiple devices of the same type, you must register
     163each of them through a separate call (with the same "drvtbl", but
     164different name/bus/i2caddr).
    118165
    119166====================================================================
     
    138185
    139186These calls perform some parameter checking and then call the
    140 appropriate high level i2c device driver function, if available.
     187appropriate high level i2c device driver function, if available,
     188according to the entries in the "drvtbl" passed in the
     189rtems_libi2c_register_drv() call.
    141190
    142191There are two exceptions: when i2c_read or i2c_write is called with a
     
    146195
    147196The main reason for the libi2c OS adaption layer is, that it
    148 dispatches the RTEMS I/O Manager calles to the proper device driver
     197dispatches the RTEMS I/O Manager calls to the proper device driver
    149198according to the minor number used.
    150199
     
    155204Each high level i2c device driver provides a set of functions in the
    156205rtems_libi2c_drv_t data structure passed the libi2c when the device is
    157 registered (see "Device registration"). These function directly match
     206registered (see "Device registration" above). These function directly match
    158207the RTEMS I/O Mangers calls "open", "close", "read", "write",
    159208"control", and they are passed the same arguments. Functions not
    160 needed may be ommited.
     209needed may be ommited (and replaced by a NULL pointer in
     210rtems_libi2c_drv_t).
    161211
    162212======================================================================
    163213high level i2c device driver and libi2c low level abstraction layer IF
    164214======================================================================
    165 tbd
     215libi2c provides a set of functions for the high level drivers. These
     216functions are:
     217
     218rtems_libi2c_send_start();
     219rtems_libi2c_send_stop();
     220rtems_libi2c_send_addr();
     221rtems_libi2c_read_bytes();
     222rtems_libi2c_write_bytes();
     223rtems_libi2c_start_read_bytes();
     224rtems_libi2c_start_write_bytes();
     225rtems_libi2c_ioctl();
     226
     227Please look into libi2c.h for the proper parameters and return codes.
     228
     229These functions perform the proper i2c operations when called.
     230
     231A typical access sequence for the I2C bus would be:
     232
     233rtems_libi2c_send_start();
     234rtems_libi2c_send_addr();
     235rtems_libi2c_write_bytes();
     236rtems_libi2c_send_stop();
     237
     238Alternatively, the rtems_libi2c_write_bytes() call could be relpaced
     239with a
     240          rtems_libi2c_read_bytes()
     241
     242call or a sequence of multiple calls.
     243
     244Note: rtems_libi2c_send_start() locks the i2c/spi bus used, so no other
     245device can use this i2c/spi bus, until rtems_libi2c_send_stop() function
     246is called for the same device.
     247
     248Special provisions for SPI devices:
     249===================================
     250For SPI devices and their drivers, the libi2c interface is used
     251slightly differently:
     252
     253rtems_libi2c_send_start() will lock access to the SPI bus, but has no
     254effect on the hardware bus interface.
     255
     256rtems_libi2c_ioctl(...,RTEMS_LIBI2C_IOCTL_SET_TFRMODE,...) will set
     257the transfer mode (bit rate, clock phase and polaritiy, bits per
     258char...) according to the rtems_libi2c_tfr_mode_t structure passed in.
     259
     260rtems_libi2c_send_addr() will activate the proper select line to
     261address a certain SPI device. The correspondance between an address
     262and the select line pulled is BSP specific.
     263
     264rtems_libi2c_send_stop(); will deactivate the address line and unlock
     265the bus.
     266
     267A typical access sequence for the SPI bus would be:
     268
     269rtems_libi2c_send_start();
     270rtems_libi2c_ioctl(...,RTEMS_LIBI2C_IOCTL_SET_TFRMODE,...);
     271rtems_libi2c_send_addr();
     272rtems_libi2c_write_bytes();
     273rtems_libi2c_send_stop();
     274
     275Alternatively, the rtems_libi2c_write_bytes() call could be relpaced
     276with a
     277         rtems_libi2c_read_bytes()
     278or a
     279         rtems_libi2c_ioctl(...,RTEMS_LIBI2C_IOCTL_READ_WRITE,...)
     280call or a sequence of multiple calls.
    166281
    167282====================================================================
    168283libi2c low level abstraction layer and i2c controller driver IF
    169284====================================================================
    170 tbd
    171 
    172 Differences between i2c and spi device drivers
    173 ==================================================
    174 tbd
    175 
    176 Differences between i2c and spi controller drivers
    177 ==================================================
    178 tbd
     285Each low level i2c/spi driver must provide a set of bus_ops functions
     286as defined in the rtems_libi2c_bus_ops_t structure.
     287
     288typedef struct rtems_libi2c_bus_ops_
     289{
     290  /* Initialize the bus; might be called again to reset the bus driver */
     291  rtems_status_code (*init) (rtems_libi2c_bus_t * bushdl);
     292  /* Send start condition */
     293  rtems_status_code (*send_start) (rtems_libi2c_bus_t * bushdl);
     294  /* Send stop  condition */
     295  rtems_status_code (*send_stop) (rtems_libi2c_bus_t * bushdl);
     296  /* initiate transfer from (rw!=0) or to a device */
     297  rtems_status_code (*send_addr) (rtems_libi2c_bus_t * bushdl,
     298                                  uint32_t addr, int rw);
     299  /* read a number of bytes */
     300  int (*read_bytes) (rtems_libi2c_bus_t * bushdl, unsigned char *bytes,
     301                     int nbytes);
     302  /* write a number of bytes */
     303  int (*write_bytes) (rtems_libi2c_bus_t * bushdl, unsigned char *bytes,
     304                      int nbytes);
     305  /* ioctl misc functions */
     306  int (*ioctl) (rtems_libi2c_bus_t * bushdl,
     307                int   cmd,
     308                void *buffer;
     309                );
     310} rtems_libi2c_bus_ops_t;
     311
     312Each of these functions performs the corresponding function to the i2c
     313bus.
     314
     315Special provisions for SPI devices:
     316===================================
     317For SPI busses, special behaviour is required:
     318
     319(*send_start) (rtems_libi2c_bus_t * bushdl)
     320              normally is an empty function.
     321
     322 (*send_addr) (rtems_libi2c_bus_t * bushdl, uint32_t addr, int rw)
     323              will activate the SPI select line matching to addr.
     324
     325(*send_stop) (rtems_libi2c_bus_t * bushdl)
     326              will deactivate the SPI select line
     327
     328(*ioctl(...,RTEMS_LIBI2C_IOCTL_SET_TFRMODE,...)
     329             will set the transfer mode (bit rate, clock phase and
     330             polaritiy, bits per char...) according to the
     331             rtems_libi2c_tfr_mode_t structure passed in.
     332
     333(*ioctl(...,RTEMS_LIBI2C_IOCTL_READ_WRITE,...)
     334             will send and receive data at the same time.
     335
     336Note:
     337
     338- low-level I2C drivers normally are specific to the master
     339device, but independent from the board hardware. So in many cases they
     340can totally reside in libcpu or libchip.
     341
     342- low-level SPI drivers are mostly board independent, but the
     343  addressing is board/BSP dependent. Therefore the (*send_start),
     344  (*send_addr) and (*send_stop) functions are typically defined in the
     345  BSP. The rest of the functions can reside in libcpu or libchip.
Note: See TracChangeset for help on using the changeset viewer.