include/bsp/i2c.h

0001 /*
0002  * Generic I2C bus interface for RTEMS
0003  *
0004  * Copyright (C) 2000 OKTET Ltd., St.-Petersburg, Russia
0005  * Author: Victor V. Vengerov <vvv@oktet.ru>
0006  *
0007  * The license and distribution terms for this file may be
0008  * found in the file LICENSE in this distribution or at
0009  *
0010  * http://www.rtems.org/license/LICENSE.
0011  */
0012
0013 #ifndef __RTEMS__I2C_H__
0014 #define __RTEMS__I2C_H__
0015
0016 #include <rtems.h>
0017 #include <bsp.h>
0018 /* This header file define the generic interface to i2c buses available in
0019  * system. This interface may be used by user applications or i2c-device
0020  * drivers (like RTC, NVRAM, etc).
0021  *
0022  * Functions i2c_initialize and i2c_transfer declared in this header usually
0023  * implemented in particular board support package. Usually this
0024  * implementation is a simple wrapper or multiplexor to I2C controller
0025  * driver which is available in system.  It may be generic "software
0026  * controller" I2C driver which control SDA and SCL signals directly (if SDA
0027  * and SCL is general-purpose I/O pins), or driver for hardware I2C
0028  * controller (standalone or integrated with processors: MBus controller in
0029  * ColdFire processors, I2C controller in PowerQUICC and so on).
0030  *
0031  * i2c_transfer is a very generic low-level function. Higher-level function
0032  * i2c_write, i2c_read, i2c_wrrd, i2c_wbrd is defined here too.
0033  */
0034
0035 /* I2C Bus Number type */
0036 typedef uint32_t         i2c_bus_number;
0037
0038 /* I2C device address */
0039 typedef uint16_t         i2c_address;
0040
0041 /* I2C error codes generated during message transfer */
0042 typedef enum i2c_message_status {
0043     I2C_SUCCESSFUL = 0,
0044     I2C_TIMEOUT,
0045     I2C_NO_DEVICE,
0046     I2C_ARBITRATION_LOST,
0047     I2C_NO_ACKNOWLEDGE,
0048     I2C_NO_DATA,
0049     I2C_RESOURCE_NOT_AVAILABLE
0050 } i2c_message_status;
0051
0052 /* I2C Message */
0053 typedef struct i2c_message {
0054     i2c_address        addr;   /* I2C slave device address */
0055     uint16_t           flags;  /* message flags (see below) */
0056     i2c_message_status status; /* message transfer status code */
0057     uint16_t           len;    /* Number of bytes to read or write */
0058     uint8_t           *buf;    /* pointer to data array */
0059 } i2c_message;
0060
0061 /* I2C message flag */
0062 #define I2C_MSG_ADDR_10 (0x01)  /* 10-bit address */
0063 #define I2C_MSG_WR      (0x02)  /* transfer direction for this message
0064                                    from master to slave */
0065 #define I2C_MSG_ERRSKIP (0x04)  /* Skip message if last transfered message
0066                                    is failed */
0067 /* Type for function which is called when transfer over I2C bus is finished */
0068 typedef void (*i2c_transfer_done) (void * arg);
0069
0070 /* i2c_initialize --
0071  *     I2C driver initialization. This function usually called on device
0072  *     driver initialization state, before initialization task. All I2C
0073  *     buses are initialized; reasonable slow data transfer rate is
0074  *     selected for each bus.
0075  *
0076  * PARAMETERS:
0077  *     major - I2C device major number
0078  *     minor - I2C device minor number
0079  *     arg - RTEMS driver initialization argument
0080  *
0081  * RETURNS:
0082  *     RTEMS status code
0083  */
0084 rtems_device_driver
0085 i2c_initialize(rtems_device_major_number major,
0086                rtems_device_minor_number minor,
0087                void *arg);
0088
0089 /* i2c_select_clock_rate --
0090  *     select I2C bus clock rate for specified bus. Some bus controller do not
0091  *     allow to select arbitrary clock rate; in this case nearest possible
0092  *     slower clock rate is selected.
0093  *
0094  * PARAMETERS:
0095  *     bus - I2C bus number
0096  *     bps - data transfer rate for this bytes in bits per second
0097  *
0098  * RETURNS:
0099  *     RTEMS_SUCCESSFUL, if operation performed successfully,
0100  *     RTEMS_INVALID_NUMBER, if wrong bus number is specified,
0101  *     RTEMS_UNSATISFIED, if bus do not support data transfer rate selection
0102  *     or specified data transfer rate could not be used.
0103  */
0104 rtems_status_code
0105 i2c_select_clock_rate(i2c_bus_number bus, int bps);
0106
0107 /* i2c_transfer --
0108  *     Initiate multiple-messages transfer over specified I2C bus or
0109  *     put request into queue if bus or some other resource is busy. (This
0110  *     is non-blocking function).
0111  *
0112  * PARAMETERS:
0113  *     bus - I2C bus number
0114  *     nmsg - number of messages
0115  *     msg - pointer to messages array
0116  *     done - function which is called when transfer is finished
0117  *     done_arg_ptr - arbitrary argument ptr passed to done funciton
0118  *
0119  * RETURNS:
0120  *     RTEMS_SUCCESSFUL if transfer initiated successfully, or error
0121  *     code if something failed.
0122  */
0123 rtems_status_code
0124 i2c_transfer(i2c_bus_number bus, int nmsg, i2c_message *msg,
0125              i2c_transfer_done done, void *done_arg);
0126
0127 /* i2c_transfer_wait --
0128  *     Initiate I2C bus transfer and block until this transfer will be
0129  *     finished. This function wait the semaphore if system in
0130  *     SYSTEM_STATE_UP state, or poll done flag in other states.
0131  *
0132  * PARAMETERS:
0133  *     bus - I2C bus number
0134  *     msg - pointer to transfer messages array
0135  *     nmsg - number of messages in transfer
0136  *
0137  * RETURNS:
0138  *     I2C_SUCCESSFUL, if tranfer finished successfully,
0139  *     I2C_RESOURCE_NOT_AVAILABLE, if semaphore operations has failed,
0140  *     value of status field of first error-finished message in transfer,
0141  *     if something wrong.
0142  */
0143 i2c_message_status
0144 i2c_transfer_wait(i2c_bus_number bus, i2c_message *msg, int nmsg);
0145
0146 /* i2c_poll --
0147  *     Poll I2C bus controller for events and hanle it. This function is
0148  *     used when I2C driver operates in poll-driven mode.
0149  *
0150  * PARAMETERS:
0151  *     bus - bus number to be polled
0152  *
0153  * RETURNS:
0154  *     none
0155  */
0156 void
0157 i2c_poll(i2c_bus_number bus);
0158
0159 /* i2c_write --
0160  *     Send single message over specified I2C bus to addressed device and
0161  *     wait while transfer is finished.
0162  *
0163  * PARAMETERS:
0164  *     bus  - I2C bus number
0165  *     addr - address of I2C device
0166  *     buf  - data to be sent to device
0167  *     size - data buffer size
0168  *
0169  * RETURNS:
0170  *     transfer status
0171  */
0172 i2c_message_status
0173 i2c_write(i2c_bus_number bus, i2c_address addr, void *buf, int size);
0174
0175 /* i2c_wrbyte --
0176  *     Send single one-byte long message over specified I2C bus to
0177  *     addressed device and wait while transfer is finished.
0178  *
0179  * PARAMETERS:
0180  *     bus  - I2C bus number
0181  *     addr - address of I2C device
0182  *     cmd  - byte message to be sent to device
0183  *
0184  * RETURNS:
0185  *     transfer status
0186  */
0187 i2c_message_status
0188 i2c_wrbyte(i2c_bus_number bus, i2c_address addr, uint8_t         cmd);
0189
0190 /* i2c_read --
0191  *     receive single message over specified I2C bus from addressed device.
0192  *     This call will wait while transfer is finished.
0193  *
0194  * PARAMETERS:
0195  *     bus  - I2C bus number
0196  *     addr - address of I2C device
0197  *     buf  - buffer for received message
0198  *     size - receive buffer size
0199  *
0200  * RETURNS:
0201  *     transfer status
0202  */
0203 i2c_message_status
0204 i2c_read(i2c_bus_number bus, i2c_address addr, void *buf, int size);
0205
0206 /* i2c_wrrd --
0207  *     Send message over I2C bus to specified device and receive message
0208  *     from the same device during single transfer.
0209  *
0210  * PARAMETERS:
0211  *     bus   - I2C bus number
0212  *     addr  - address of I2C device
0213  *     bufw  - data to be sent to device
0214  *     sizew - send data buffer size
0215  *     bufr  - buffer for received message
0216  *     sizer - receive buffer size
0217  *
0218  * RETURNS:
0219  *     transfer status
0220  */
0221 i2c_message_status
0222 i2c_wrrd(i2c_bus_number bus, i2c_address addr, void *bufw, int sizew,
0223          void *bufr, int sizer);
0224
0225 /* i2c_wbrd --
0226  *     Send one-byte message over I2C bus to specified device and receive
0227  *     message from the same device during single transfer.
0228  *
0229  * PARAMETERS:
0230  *     bus   - I2C bus number
0231  *     addr  - address of I2C device
0232  *     cmd   - one-byte message to be sent over I2C bus
0233  *     bufr  - buffer for received message
0234  *     sizer - receive buffer size
0235  *
0236  * RETURNS:
0237  *     transfer status
0238  */
0239 i2c_message_status
0240 i2c_wbrd(i2c_bus_number bus, i2c_address addr, uint8_t         cmd,
0241          void *bufr, int sizer);
0242
0243 #endif