Changeset c47890c in rtems

10/26/07 09:51:41 (16 years ago)
Thomas Doerfler <Thomas.Doerfler@…>
4.10, 4.11, 4.9, 5, master

* empty log message *

2 edited


  • cpukit/ChangeLog

    r83374f3 rc47890c  
     12007-10-26      Thomas Doerfler <>
     3        * libi2c/README-libi2c
     4        document structure of libi2c library
    162007-10-25      Thomas Doerfler <>
  • cpukit/libi2c/README_libi2c

    r83374f3 rc47890c  
    7373  the i2c controller driver (2<->1)
     76Differences between i2c and spi bus
     78SPI and I2C has many similarities, but also some differences:
     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
     84- SPI supports combined full duplex read-write transactions while I2C
     85either sends or receives data from a slave device
     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
     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.
    112133bus available on the board.
    114 ===================
    115 Device Registration
    116 ===================
    117 tbd
     136Device/Driver Registration
     138Each device attached to an i2c or spi bus must be registered with a
     139call to
     142rtems_libi2c_register_drv (char *name, rtems_libi2c_drv_t * drvtbl,
     143                           unsigned bus, unsigned i2caddr);
     145With this call, libi2c is informed, that:
     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"
     151- the device is managed by a driver, who's entry functions are listed
     152  in "drvtbl"
     154- the device should be registered with the given "name" in the device
     155  tree of the filesystem.
     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.
     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).
    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.
    142191There are two exceptions: when i2c_read or i2c_write is called with a
    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.
    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
    163213high level i2c device driver and libi2c low level abstraction layer IF
    165 tbd
     215libi2c provides a set of functions for the high level drivers. These
     216functions are:
     227Please look into libi2c.h for the proper parameters and return codes.
     229These functions perform the proper i2c operations when called.
     231A typical access sequence for the I2C bus would be:
     238Alternatively, the rtems_libi2c_write_bytes() call could be relpaced
     239with a
     240          rtems_libi2c_read_bytes()
     242call or a sequence of multiple calls.
     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.
     248Special provisions for SPI devices:
     250For SPI devices and their drivers, the libi2c interface is used
     251slightly differently:
     253rtems_libi2c_send_start() will lock access to the SPI bus, but has no
     254effect on the hardware bus interface.
     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.
     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.
     264rtems_libi2c_send_stop(); will deactivate the address line and unlock
     265the bus.
     267A typical access sequence for the SPI bus would be:
     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.
    168283libi2c low level abstraction layer and i2c controller driver IF
    170 tbd
    172 Differences between i2c and spi device drivers
    173 ==================================================
    174 tbd
    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.
     288typedef struct rtems_libi2c_bus_ops_
     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;
     312Each of these functions performs the corresponding function to the i2c
     315Special provisions for SPI devices:
     317For SPI busses, special behaviour is required:
     319(*send_start) (rtems_libi2c_bus_t * bushdl)
     320              normally is an empty function.
     322 (*send_addr) (rtems_libi2c_bus_t * bushdl, uint32_t addr, int rw)
     323              will activate the SPI select line matching to addr.
     325(*send_stop) (rtems_libi2c_bus_t * bushdl)
     326              will deactivate the SPI select line
     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.
     334             will send and receive data at the same time.
     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.
     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.