source: rtems/bsps/m68k/mcf5206elite/include/i2c.h @ d7d66d7

5
Last change on this file since d7d66d7 was 2afb22b, checked in by Chris Johns <chrisj@…>, on Dec 23, 2017 at 7:18:56 AM

Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step. It
copied header files from arbitrary locations into the build tree. The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

  • The make preinstall step itself needs time and disk space.
  • Errors in header files show up in the build tree copy. This makes it hard for editors to open the right file to fix the error.
  • There is no clear relationship between source and build tree header files. This makes an audit of the build process difficult.
  • The visibility of all header files in the build tree makes it difficult to enforce API barriers. For example it is discouraged to use BSP-specifics in the cpukit.
  • An introduction of a new build system is difficult.
  • Include paths specified by the -B option are system headers. This may suppress warnings.
  • The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step. All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc. Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

  • cpukit/include
  • cpukit/score/cpu/@RTEMS_CPU@/include
  • cpukit/libnetworking

The new BSP include directories are:

  • bsps/include
  • bsps/@RTEMS_CPU@/include
  • bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed. The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

  • Property mode set to 100644
File size: 7.7 KB
Line 
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 *
10 * http://www.rtems.org/license/LICENSE.
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 */
36typedef uint32_t         i2c_bus_number;
37
38/* I2C device address */
39typedef uint16_t         i2c_address;
40
41/* I2C error codes generated during message transfer */
42typedef 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 */
53typedef struct i2c_message {
54    i2c_address        addr;   /* I2C slave device address */
55    uint16_t           flags;  /* message flags (see below) */
56    i2c_message_status status; /* message transfer status code */
57    uint16_t           len;    /* Number of bytes to read or write */
58    uint8_t           *buf;    /* pointer to data array */
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 */
68typedef void (*i2c_transfer_done) (void *arg);
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 */
84rtems_device_driver
85i2c_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
91 *     allow to select arbitrary clock rate; in this case nearest possible
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:
99 *     RTEMS_SUCCESSFUL, if operation performed successfully,
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 */
104rtems_status_code
105i2c_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
117 *     done_arg_ptr - arbitrary argument ptr passed to done funciton
118 *
119 * RETURNS:
120 *     RTEMS_SUCCESSFUL if transfer initiated successfully, or error
121 *     code if something failed.
122 */
123rtems_status_code
124i2c_transfer(i2c_bus_number bus, int nmsg, i2c_message *msg,
125             i2c_transfer_done done, void * done_arg_ptr);
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:
138 *     I2C_SUCCESSFUL, if transfer finished successfully,
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 */
143i2c_message_status
144i2c_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 */
156void
157i2c_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 */
172i2c_message_status
173i2c_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 */
187i2c_message_status
188i2c_wrbyte(i2c_bus_number bus, i2c_address addr, uint8_t         cmd);
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 */
203i2c_message_status
204i2c_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 */
221i2c_message_status
222i2c_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 */
239i2c_message_status
240i2c_wbrd(i2c_bus_number bus, i2c_address addr, uint8_t         cmd,
241         void *bufr, int sizer);
242
243#endif
Note: See TracBrowser for help on using the repository browser.