LXR 6.1/​cpukit/​include/​rtems/​libi2c.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:13

 /**
  * @file
  *
  * @ingroup libi2c
  *
  * @brief Legacy I2C Library
  */
 
 #ifndef _RTEMS_LIBI2C_H
 #define _RTEMS_LIBI2C_H
 
 /*
  * Authorship
  * ----------
  * This software was created by
  *     Till Straumann <strauman@slac.stanford.edu>, 2005,
  *     Stanford Linear Accelerator Center, Stanford University.
  *
  * Acknowledgement of sponsorship
  * ------------------------------
  * This software was produced by
  *     the Stanford Linear Accelerator Center, Stanford University,
  *     under Contract DE-AC03-76SFO0515 with the Department of Energy.
  *
  * Government disclaimer of liability
  * ----------------------------------
  * Neither the United States nor the United States Department of Energy,
  * nor any of their employees, makes any warranty, express or implied, or
  * assumes any legal liability or responsibility for the accuracy,
  * completeness, or usefulness of any data, apparatus, product, or process
  * disclosed, or represents that its use would not infringe privately owned
  * rights.
  *
  * Stanford disclaimer of liability
  * --------------------------------
  * Stanford University makes no representations or warranties, express or
  * implied, nor assumes any liability for the use of this software.
  *
  * Stanford disclaimer of copyright
  * --------------------------------
  * Stanford University, owner of the copyright, hereby disclaims its
  * copyright and all other rights in this software.  Hence, anyone may
  * freely use it for any purpose without restriction.
  *
  * Maintenance of notices
  * ----------------------
  * In the interest of clarity regarding the origin and status of this
  * SLAC software, this and all the preceding Stanford University notices
  * are to remain affixed to any copy or derivative of this software made
  * or distributed by the recipient and are to be affixed to any copy of
  * software made or distributed by the recipient that contains a copy or
  * derivative of this software.
  *
  * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
  */
 
 #include <rtems.h>
 
 #include <rtems/io.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
  * @defgroup libi2c Legacy I2C Library
  *
  * @ingroup RTEMSDeviceDrivers
  *
  * @brief Legacy I2C library.
  *
  */
 /**@{**/
 
 /* Simple I2C driver API */
 
 /* Initialize the libary - may fail if no semaphore or no driver slot is available */
 extern int rtems_libi2c_initialize (void);
 
 /* Alternatively to rtems_libi2c_initialize() the library can also be
  * initialized by means of a traditional driver table entry containing
  * the following entry points:
  */
 extern rtems_status_code
 rtems_i2c_init (
     rtems_device_major_number major,
     rtems_device_minor_number minor,
     void *arg);
 
 extern rtems_status_code
 rtems_i2c_open (
     rtems_device_major_number major,
     rtems_device_minor_number minor,
     void *arg);
 
 extern rtems_status_code
 rtems_i2c_close (
     rtems_device_major_number major,
     rtems_device_minor_number minor,
     void *arg);
 
 extern rtems_status_code
 rtems_i2c_read (
     rtems_device_major_number major,
     rtems_device_minor_number minor,
     void *arg);
 
 extern rtems_status_code
 rtems_i2c_write (
     rtems_device_major_number major,
     rtems_device_minor_number minor,
     void *arg);
 
 extern rtems_status_code
 rtems_i2c_ioctl (
     rtems_device_major_number major,
     rtems_device_minor_number minor,
     void *arg);
 
 extern const rtems_driver_address_table rtems_libi2c_io_ops;
 
 /* Unfortunately, if you want to add this driver to
  * a RTEMS configuration table then you need all the
  * members explicitly :-( (Device_driver_table should
  * hold pointers to rtems_driver_address_tables rather
  * than full structs).
  *
  * The difficulty is that adding this driver to the
  * configuration table is not enough; you still need
  * to populate the framework with low-level bus-driver(s)
  * and high-level drivers and/or device-files...
  *
  * Currently the preferred way is having the BSP
  * call 'rtems_libi2c_initialize' followed by
  * 'rtems_libi2c_register_bus' and
  * 'rtems_libi2c_register_drv' and/or
  * 'mknod' (for 'raw' device nodes)
  * from the 'bsp_predriver_hook'.
  */
 #define RTEMS_LIBI2C_DRIVER_TABLE_ENTRY   \
 {                                         \
   initialization_entry:  rtems_i2c_init,  \
   open_entry:            rtems_i2c_open,  \
   close_entry:           rtems_i2c_close, \
   read_entry:            rtems_i2c_read,  \
   write_entry:           rtems_i2c_write, \
   control_entry:         rtems_i2c_ioctl, \
 }
 
 /* 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_
 {
   const 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);
   /* ioctl misc functions */
   int (*ioctl) (rtems_libi2c_bus_t * bushdl,
         int   cmd,
         void *buffer
         );
 } 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, also IMFS filesystem must exist). It may be NULL in
  * which case the library will pick a default.
  *
  * RETURNS: bus # (>=0) or -1 on error (errno set).
  */
 
 extern int rtems_libi2c_register_bus (const 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_
 {
   const 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
  */
 extern int
 rtems_libi2c_register_drv (const 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...
  */
 extern rtems_status_code rtems_libi2c_send_start (rtems_device_minor_number minor);
 
 extern rtems_status_code rtems_libi2c_send_stop (rtems_device_minor_number minor);
 
 extern 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.
  */
 extern int
 rtems_libi2c_read_bytes (rtems_device_minor_number minor,
                          unsigned char *bytes, int nbytes);
 
 extern int
 rtems_libi2c_write_bytes (rtems_device_minor_number minor,
                           const unsigned char *bytes, int nbytes);
 
 /* Send start, send address and read bytes */
 extern int
 rtems_libi2c_start_read_bytes (rtems_device_minor_number minor,
                    unsigned char *bytes,
                                int nbytes);
 
 /* Send start, send address and write bytes */
 extern int
 rtems_libi2c_start_write_bytes (rtems_device_minor_number minor,
                 const unsigned char *bytes,
                                 int nbytes);
 
 
 /* call misc iocontrol function */
 extern int
 rtems_libi2c_ioctl (rtems_device_minor_number minor,
             int cmd,
             ...);
 /*
  * NOTE: any low-level driver ioctl returning a negative
  * result for release the bus (perform a STOP condition)
  */
 /*******************************
  * defined IOCTLs:
  *******************************/
 #define RTEMS_LIBI2C_IOCTL_READ_WRITE  1
 /*
  * retval = rtems_libi2c_ioctl(rtems_device_minor_number minor,
  *                             RTEMS_LIBI2C_IOCTL_READ_WRITE,
  *                              rtems_libi2c_read_write_t *arg);
  *
  * This call performs a simultanous read/write transfer,
  * which is possible (and sometimes needed) for SPI devices
  *
  *   arg is a pointer to a rd_wr info data structure
  *
  * This call is only needed for SPI devices
  */
 #define RTEMS_LIBI2C_IOCTL_START_TFM_READ_WRITE  2
 /*
  * retval = rtems_libi2c_ioctl(rtems_device_minor_number minor,
  *                             RTEMS_LIBI2C_IOCTL_START_READ_WRITE,
  *                             unsigned char *rd_buffer,
  *                             const unsigned char *wr_buffer,
  *                             int byte_cnt,
  *                             const rtems_libi2c_tfr_mode_t *tfr_mode_ptr);
  *
  * This call addresses a slave and then:
  * - sets the proper transfer mode,
  *  - performs a simultanous  read/write transfer,
  *    (which is possible and sometimes needed for SPI devices)
  *    NOTE: - if rd_buffer is NULL, receive data will be dropped
  *          - if wr_buffer is NULL, bytes with content 0 will transmitted
  *
  *   rd_buffer is a pointer to a receive buffer (or NULL)
  *   wr_buffer is a pointer to the data to be sent (or NULL)
  *
  * This call is only needed for SPI devices
  */
 
 #define RTEMS_LIBI2C_IOCTL_SET_TFRMODE 3
 /*
  * retval = rtems_libi2c_ioctl(rtems_device_minor_number minor,
  *                             RTEMS_LIBI2C_IOCTL_SET_TFRMODE,
  *                             const rtems_libi2c_tfr_mode_t *tfr_mode_ptr);
  *
  * This call sets an SPI device to the transfer mode needed (baudrate etc.)
  *
  *   tfr_mode is a pointer to a structure defining the SPI transfer mode needed
  *   (see below).
  *
  * This call is only needed for SPI devices
  */
 
 #define RTEMS_LIBI2C_IOCTL_GET_DRV_T 4
 
 /*
  * retval = rtems_libi2c_ioctl(rtems_device_minor_number minor,
  *                             RTEMS_LIBI2C_IOCTL_GET_DRV_T,
  *                             const rtems_libi2c_drv_t *drv_t_ptr);
  *
  * This call allows the a high-level driver to query its driver table entry,
  * including its private data appended to it during creation of the entry
  *
  */
 
 /**
  * @brief IO control command for asynchronous read and write.
  *
  * @see rtems_libi2c_read_write_done_t and rtems_libi2c_read_write_async_t.
  *
  * @warning This is work in progress!
  */
 #define RTEMS_LIBI2C_IOCTL_READ_WRITE_ASYNC 5
 
 /*
  * argument data structures for IOCTLs defined above
  */
 typedef struct {
   unsigned char       *rd_buf;
   const unsigned char *wr_buf;
   int                  byte_cnt;
 } rtems_libi2c_read_write_t;
 
 typedef struct {
   uint32_t baudrate;       /* maximum bits per second               */
                            /* only valid for SPI drivers:           */
   uint8_t  bits_per_char;  /* how many bits per byte/word/longword? */
   bool     lsb_first;      /* true: send LSB first                  */
   bool     clock_inv;      /* true: inverted clock (high active)    */
   bool     clock_phs;      /* true: clock starts toggling at start of data tfr */
   uint32_t  idle_char;     /* This character will be continuously transmitted in read only functions */
 } rtems_libi2c_tfr_mode_t;
 
 typedef struct {
   rtems_libi2c_tfr_mode_t   tfr_mode;
   rtems_libi2c_read_write_t rd_wr;
 } rtems_libi2c_tfm_read_write_t;
 
 /**
  * @brief Notification function type for asynchronous read and write.
  *
  * @see RTEMS_LIBI2C_IOCTL_READ_WRITE_ASYNC and
  * rtems_libi2c_read_write_async_t.
  *
  * @warning This is work in progress!
  */
 typedef void (*rtems_libi2c_read_write_done_t) \
   ( int /* return value */, int /* nbytes */, void * /* arg */);
 
 /**
  * @brief IO command data for asynchronous read and write.
  *
  * @see RTEMS_LIBI2C_IOCTL_READ_WRITE_ASYNC and
  * rtems_libi2c_read_write_done_t.
  *
  * @warning This is work in progress!
  */
 typedef struct {
   unsigned char                 *rd_buf;
   const unsigned char           *wr_buf;
   int                            byte_cnt;
   rtems_libi2c_read_write_done_t done;
   void                          *arg;
 } rtems_libi2c_read_write_async_t;
 
 /** @} */
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team