[e56c3546] | 1 | /* |
---|
| 2 | * Generic I2C bus interface for RTEMS |
---|
| 3 | * |
---|
| 4 | * Copyright (C) 2000 OKTET Ltd., St.-Petersburg, Russia |
---|
| 5 | * Author: Victor V. Vengerov <vvv@oktet.ru> |
---|
| 6 | * |
---|
| 7 | * The license and distribution terms for this file may be |
---|
| 8 | * found in the file LICENSE in this distribution or at |
---|
| 9 | * |
---|
[c499856] | 10 | * http://www.rtems.org/license/LICENSE. |
---|
[e56c3546] | 11 | */ |
---|
| 12 | |
---|
| 13 | #ifndef __RTEMS__I2C_H__ |
---|
| 14 | #define __RTEMS__I2C_H__ |
---|
| 15 | |
---|
| 16 | #include <rtems.h> |
---|
| 17 | #include <bsp.h> |
---|
| 18 | /* This header file define the generic interface to i2c buses available in |
---|
| 19 | * system. This interface may be used by user applications or i2c-device |
---|
| 20 | * drivers (like RTC, NVRAM, etc). |
---|
| 21 | * |
---|
| 22 | * Functions i2c_initialize and i2c_transfer declared in this header usually |
---|
| 23 | * implemented in particular board support package. Usually this |
---|
| 24 | * implementation is a simple wrapper or multiplexor to I2C controller |
---|
| 25 | * driver which is available in system. It may be generic "software |
---|
| 26 | * controller" I2C driver which control SDA and SCL signals directly (if SDA |
---|
| 27 | * and SCL is general-purpose I/O pins), or driver for hardware I2C |
---|
| 28 | * controller (standalone or integrated with processors: MBus controller in |
---|
| 29 | * ColdFire processors, I2C controller in PowerQUICC and so on). |
---|
| 30 | * |
---|
| 31 | * i2c_transfer is a very generic low-level function. Higher-level function |
---|
| 32 | * i2c_write, i2c_read, i2c_wrrd, i2c_wbrd is defined here too. |
---|
| 33 | */ |
---|
| 34 | |
---|
| 35 | /* I2C Bus Number type */ |
---|
[b7044dc] | 36 | typedef uint32_t i2c_bus_number; |
---|
[e56c3546] | 37 | |
---|
| 38 | /* I2C device address */ |
---|
[b7044dc] | 39 | typedef uint16_t i2c_address; |
---|
[e56c3546] | 40 | |
---|
| 41 | /* I2C error codes generated during message transfer */ |
---|
| 42 | typedef enum i2c_message_status { |
---|
| 43 | I2C_SUCCESSFUL = 0, |
---|
| 44 | I2C_TIMEOUT, |
---|
| 45 | I2C_NO_DEVICE, |
---|
| 46 | I2C_ARBITRATION_LOST, |
---|
| 47 | I2C_NO_ACKNOWLEDGE, |
---|
| 48 | I2C_NO_DATA, |
---|
| 49 | I2C_RESOURCE_NOT_AVAILABLE |
---|
| 50 | } i2c_message_status; |
---|
| 51 | |
---|
| 52 | /* I2C Message */ |
---|
| 53 | typedef struct i2c_message { |
---|
| 54 | i2c_address addr; /* I2C slave device address */ |
---|
[b7044dc] | 55 | uint16_t flags; /* message flags (see below) */ |
---|
[e56c3546] | 56 | i2c_message_status status; /* message transfer status code */ |
---|
[b7044dc] | 57 | uint16_t len; /* Number of bytes to read or write */ |
---|
| 58 | uint8_t *buf; /* pointer to data array */ |
---|
[e56c3546] | 59 | } i2c_message; |
---|
| 60 | |
---|
| 61 | /* I2C message flag */ |
---|
| 62 | #define I2C_MSG_ADDR_10 (0x01) /* 10-bit address */ |
---|
| 63 | #define I2C_MSG_WR (0x02) /* transfer direction for this message |
---|
| 64 | from master to slave */ |
---|
| 65 | #define I2C_MSG_ERRSKIP (0x04) /* Skip message if last transfered message |
---|
| 66 | is failed */ |
---|
| 67 | /* Type for function which is called when transfer over I2C bus is finished */ |
---|
[73c97f7] | 68 | typedef void (*i2c_transfer_done) (void *arg); |
---|
[e56c3546] | 69 | |
---|
| 70 | /* i2c_initialize -- |
---|
| 71 | * I2C driver initialization. This function usually called on device |
---|
| 72 | * driver initialization state, before initialization task. All I2C |
---|
| 73 | * buses are initialized; reasonable slow data transfer rate is |
---|
| 74 | * selected for each bus. |
---|
| 75 | * |
---|
| 76 | * PARAMETERS: |
---|
| 77 | * major - I2C device major number |
---|
| 78 | * minor - I2C device minor number |
---|
| 79 | * arg - RTEMS driver initialization argument |
---|
| 80 | * |
---|
| 81 | * RETURNS: |
---|
| 82 | * RTEMS status code |
---|
| 83 | */ |
---|
| 84 | rtems_device_driver |
---|
| 85 | i2c_initialize(rtems_device_major_number major, |
---|
| 86 | rtems_device_minor_number minor, |
---|
| 87 | void *arg); |
---|
| 88 | |
---|
| 89 | /* i2c_select_clock_rate -- |
---|
| 90 | * select I2C bus clock rate for specified bus. Some bus controller do not |
---|
[6128a4a] | 91 | * allow to select arbitrary clock rate; in this case nearest possible |
---|
[e56c3546] | 92 | * slower clock rate is selected. |
---|
| 93 | * |
---|
| 94 | * PARAMETERS: |
---|
| 95 | * bus - I2C bus number |
---|
| 96 | * bps - data transfer rate for this bytes in bits per second |
---|
| 97 | * |
---|
| 98 | * RETURNS: |
---|
[6128a4a] | 99 | * RTEMS_SUCCESSFUL, if operation performed successfully, |
---|
[e56c3546] | 100 | * RTEMS_INVALID_NUMBER, if wrong bus number is specified, |
---|
| 101 | * RTEMS_UNSATISFIED, if bus do not support data transfer rate selection |
---|
| 102 | * or specified data transfer rate could not be used. |
---|
| 103 | */ |
---|
| 104 | rtems_status_code |
---|
| 105 | i2c_select_clock_rate(i2c_bus_number bus, int bps); |
---|
| 106 | |
---|
| 107 | /* i2c_transfer -- |
---|
| 108 | * Initiate multiple-messages transfer over specified I2C bus or |
---|
| 109 | * put request into queue if bus or some other resource is busy. (This |
---|
| 110 | * is non-blocking function). |
---|
| 111 | * |
---|
| 112 | * PARAMETERS: |
---|
| 113 | * bus - I2C bus number |
---|
| 114 | * nmsg - number of messages |
---|
| 115 | * msg - pointer to messages array |
---|
| 116 | * done - function which is called when transfer is finished |
---|
[b06d0552] | 117 | * done_arg_ptr - arbitrary argument ptr passed to done funciton |
---|
[e56c3546] | 118 | * |
---|
| 119 | * RETURNS: |
---|
| 120 | * RTEMS_SUCCESSFUL if transfer initiated successfully, or error |
---|
| 121 | * code if something failed. |
---|
| 122 | */ |
---|
| 123 | rtems_status_code |
---|
[6128a4a] | 124 | i2c_transfer(i2c_bus_number bus, int nmsg, i2c_message *msg, |
---|
[b06d0552] | 125 | i2c_transfer_done done, void * done_arg_ptr); |
---|
[e56c3546] | 126 | |
---|
| 127 | /* i2c_transfer_wait -- |
---|
| 128 | * Initiate I2C bus transfer and block until this transfer will be |
---|
| 129 | * finished. This function wait the semaphore if system in |
---|
| 130 | * SYSTEM_STATE_UP state, or poll done flag in other states. |
---|
| 131 | * |
---|
| 132 | * PARAMETERS: |
---|
| 133 | * bus - I2C bus number |
---|
| 134 | * msg - pointer to transfer messages array |
---|
| 135 | * nmsg - number of messages in transfer |
---|
| 136 | * |
---|
| 137 | * RETURNS: |
---|
[296846a] | 138 | * I2C_SUCCESSFUL, if transfer finished successfully, |
---|
[e56c3546] | 139 | * I2C_RESOURCE_NOT_AVAILABLE, if semaphore operations has failed, |
---|
| 140 | * value of status field of first error-finished message in transfer, |
---|
| 141 | * if something wrong. |
---|
| 142 | */ |
---|
| 143 | i2c_message_status |
---|
| 144 | i2c_transfer_wait(i2c_bus_number bus, i2c_message *msg, int nmsg); |
---|
| 145 | |
---|
| 146 | /* i2c_poll -- |
---|
| 147 | * Poll I2C bus controller for events and hanle it. This function is |
---|
| 148 | * used when I2C driver operates in poll-driven mode. |
---|
| 149 | * |
---|
| 150 | * PARAMETERS: |
---|
| 151 | * bus - bus number to be polled |
---|
| 152 | * |
---|
| 153 | * RETURNS: |
---|
| 154 | * none |
---|
| 155 | */ |
---|
| 156 | void |
---|
| 157 | i2c_poll(i2c_bus_number bus); |
---|
| 158 | |
---|
| 159 | /* i2c_write -- |
---|
| 160 | * Send single message over specified I2C bus to addressed device and |
---|
| 161 | * wait while transfer is finished. |
---|
| 162 | * |
---|
| 163 | * PARAMETERS: |
---|
| 164 | * bus - I2C bus number |
---|
| 165 | * addr - address of I2C device |
---|
| 166 | * buf - data to be sent to device |
---|
| 167 | * size - data buffer size |
---|
| 168 | * |
---|
| 169 | * RETURNS: |
---|
| 170 | * transfer status |
---|
| 171 | */ |
---|
| 172 | i2c_message_status |
---|
| 173 | i2c_write(i2c_bus_number bus, i2c_address addr, void *buf, int size); |
---|
| 174 | |
---|
| 175 | /* i2c_wrbyte -- |
---|
| 176 | * Send single one-byte long message over specified I2C bus to |
---|
| 177 | * addressed device and wait while transfer is finished. |
---|
| 178 | * |
---|
| 179 | * PARAMETERS: |
---|
| 180 | * bus - I2C bus number |
---|
| 181 | * addr - address of I2C device |
---|
| 182 | * cmd - byte message to be sent to device |
---|
| 183 | * |
---|
| 184 | * RETURNS: |
---|
| 185 | * transfer status |
---|
| 186 | */ |
---|
| 187 | i2c_message_status |
---|
[b7044dc] | 188 | i2c_wrbyte(i2c_bus_number bus, i2c_address addr, uint8_t cmd); |
---|
[e56c3546] | 189 | |
---|
| 190 | /* i2c_read -- |
---|
| 191 | * receive single message over specified I2C bus from addressed device. |
---|
| 192 | * This call will wait while transfer is finished. |
---|
| 193 | * |
---|
| 194 | * PARAMETERS: |
---|
| 195 | * bus - I2C bus number |
---|
| 196 | * addr - address of I2C device |
---|
| 197 | * buf - buffer for received message |
---|
| 198 | * size - receive buffer size |
---|
| 199 | * |
---|
| 200 | * RETURNS: |
---|
| 201 | * transfer status |
---|
| 202 | */ |
---|
| 203 | i2c_message_status |
---|
| 204 | i2c_read(i2c_bus_number bus, i2c_address addr, void *buf, int size); |
---|
| 205 | |
---|
| 206 | /* i2c_wrrd -- |
---|
| 207 | * Send message over I2C bus to specified device and receive message |
---|
| 208 | * from the same device during single transfer. |
---|
| 209 | * |
---|
| 210 | * PARAMETERS: |
---|
| 211 | * bus - I2C bus number |
---|
| 212 | * addr - address of I2C device |
---|
| 213 | * bufw - data to be sent to device |
---|
| 214 | * sizew - send data buffer size |
---|
| 215 | * bufr - buffer for received message |
---|
| 216 | * sizer - receive buffer size |
---|
| 217 | * |
---|
| 218 | * RETURNS: |
---|
| 219 | * transfer status |
---|
| 220 | */ |
---|
| 221 | i2c_message_status |
---|
| 222 | i2c_wrrd(i2c_bus_number bus, i2c_address addr, void *bufw, int sizew, |
---|
| 223 | void *bufr, int sizer); |
---|
| 224 | |
---|
| 225 | /* i2c_wbrd -- |
---|
| 226 | * Send one-byte message over I2C bus to specified device and receive |
---|
| 227 | * message from the same device during single transfer. |
---|
| 228 | * |
---|
| 229 | * PARAMETERS: |
---|
| 230 | * bus - I2C bus number |
---|
| 231 | * addr - address of I2C device |
---|
| 232 | * cmd - one-byte message to be sent over I2C bus |
---|
| 233 | * bufr - buffer for received message |
---|
| 234 | * sizer - receive buffer size |
---|
| 235 | * |
---|
| 236 | * RETURNS: |
---|
| 237 | * transfer status |
---|
| 238 | */ |
---|
| 239 | i2c_message_status |
---|
[b7044dc] | 240 | i2c_wbrd(i2c_bus_number bus, i2c_address addr, uint8_t cmd, |
---|
[e56c3546] | 241 | void *bufr, int sizer); |
---|
| 242 | |
---|
| 243 | #endif |
---|