source: rtems/cpukit/include/dev/i2c/i2c.h @ 5bb5e01

Last change on this file since 5bb5e01 was 5bb5e01, checked in by Christian Mauderer <christian.mauderer@…>, on May 26, 2021 at 2:33:40 PM

i2c: Add non blocking read / write

This adds the possibility to open an I2C bus with O_NONBLOCK (or set it
later via fcntl) to get non-blocking transmissions. This means that if
the bus is busy, a read, write or transfer ioctl will return with a
EAGAIN errno.

  • Property mode set to 100644
File size: 10.7 KB
Line 
1/**
2 * @file
3 *
4 * @brief Inter-Integrated Circuit (I2C) Driver API
5 *
6 * @ingroup I2C
7 */
8
9/*
10 * Copyright (c) 2014, 2017 embedded brains GmbH.  All rights reserved.
11 *
12 *  embedded brains GmbH
13 *  Dornierstr. 4
14 *  82178 Puchheim
15 *  Germany
16 *  <rtems@embedded-brains.de>
17 *
18 * The license and distribution terms for this file may be
19 * found in the file LICENSE in this distribution or at
20 * http://www.rtems.org/license/LICENSE.
21 */
22
23#ifndef _DEV_I2C_I2C_H
24#define _DEV_I2C_I2C_H
25
26#include <linux/i2c.h>
27#include <linux/i2c-dev.h>
28
29#include <rtems.h>
30#include <rtems/seterr.h>
31#include <rtems/thread.h>
32
33#include <sys/ioctl.h>
34#include <sys/stat.h>
35
36#ifdef __cplusplus
37extern "C" {
38#endif /* __cplusplus */
39
40typedef struct i2c_msg i2c_msg;
41
42typedef struct i2c_bus i2c_bus;
43
44typedef struct i2c_dev i2c_dev;
45
46typedef struct i2c_rdwr_ioctl_data i2c_rdwr_ioctl_data;
47
48/**
49 * @defgroup I2C Inter-Integrated Circuit (I2C) Driver
50 *
51 * @ingroup RTEMSDeviceDrivers
52 *
53 * @brief Inter-Integrated Circuit (I2C) bus and device driver support.
54 *
55 * @{
56 */
57
58/**
59 * @defgroup I2CBus I2C Bus Driver
60 *
61 * @ingroup I2C
62 *
63 * @{
64 */
65
66/**
67 * @name I2C IO Control Commands
68 *
69 * @{
70 */
71
72/**
73 * @brief Obtains the bus.
74 *
75 * This command has no argument.
76 */
77#define I2C_BUS_OBTAIN 0x800
78
79/**
80 * @brief Releases the bus.
81 *
82 * This command has no argument.
83 */
84#define I2C_BUS_RELEASE 0x801
85
86/**
87 * @brief Gets the bus control.
88 *
89 * The argument type is a pointer to i2c_bus pointer.
90 */
91#define I2C_BUS_GET_CONTROL 0x802
92
93/**
94 * @brief Sets the bus clock in Hz.
95 *
96 * The argument type is unsigned long.
97 */
98#define I2C_BUS_SET_CLOCK 0x803
99
100/** @} */
101
102/**
103 * @brief Default I2C bus clock in Hz.
104 */
105#define I2C_BUS_CLOCK_DEFAULT 100000
106
107/**
108 * @brief I2C bus control.
109 */
110struct i2c_bus {
111  /**
112   * @brief Transfers I2C messages.
113   *
114   * @param[in] bus The bus control.
115   * @param[in] msgs The messages to transfer.
116   * @param[in] msg_count The count of messages to transfer.  It must be
117   * positive.
118   *
119   * @retval 0 Successful operation.
120   * @retval negative Negative error number in case of an error.
121   */
122  int (*transfer)(i2c_bus *bus, i2c_msg *msgs, uint32_t msg_count);
123
124  /**
125   * @brief Sets the bus clock.
126   *
127   * @param[in] bus The bus control.
128   * @param[in] clock The desired bus clock in Hz.
129   *
130   * @retval 0 Successful operation.
131   * @retval negative Negative error number in case of an error.
132   */
133  int (*set_clock)(i2c_bus *bus, unsigned long clock);
134
135  /**
136   * @brief Destroys the bus.
137   *
138   * @param[in] bus The bus control.
139   */
140  void (*destroy)(i2c_bus *bus);
141
142  /**
143   * @brief Mutex to protect the bus access.
144   */
145  rtems_recursive_mutex mutex;
146
147  /**
148   * @brief Default slave device address.
149   */
150  uint16_t default_address;
151
152  /**
153   * @brief Use 10-bit addresses.
154   */
155  bool ten_bit_address;
156
157  /**
158   * @brief Use SMBus PEC.
159   */
160  bool use_pec;
161
162  /**
163   * @brief Transfer retry count.
164   */
165  unsigned long retries;
166
167  /**
168   * @brief Transaction timeout in ticks.
169   */
170  rtems_interval timeout;
171
172  /**
173   * @brief Controller functionality.
174   */
175  unsigned long functionality;
176};
177
178/**
179 * @brief Initializes a bus control.
180 *
181 * After a sucessful initialization the bus control must be destroyed via
182 * i2c_bus_destroy().  A registered bus control will be automatically destroyed
183 * in case the device file is unlinked.  Make sure to call i2c_bus_destroy() in
184 * a custom destruction handler.
185 *
186 * @param[in] bus The bus control.
187 *
188 * @retval 0 Successful operation.
189 * @retval -1 An error occurred.  The errno is set to indicate the error.
190 *
191 * @see i2c_bus_register()
192 */
193int i2c_bus_init(i2c_bus *bus);
194
195/**
196 * @brief Allocates a bus control from the heap and initializes it.
197 *
198 * After a sucessful allocation and initialization the bus control must be
199 * destroyed via i2c_bus_destroy_and_free().  A registered bus control will be
200 * automatically destroyed in case the device file is unlinked.  Make sure to
201 * call i2c_bus_destroy_and_free() in a custom destruction handler.
202 *
203 * @param[in] size The size of the bus control.  This enables the addition of
204 * bus controller specific data to the base bus control.  The bus control is
205 * zero initialized.
206 *
207 * @retval non-NULL The new bus control.
208 * @retval NULL An error occurred.  The errno is set to indicate the error.
209 *
210 * @see i2c_bus_register()
211 */
212i2c_bus *i2c_bus_alloc_and_init(size_t size);
213
214/**
215 * @brief Destroys a bus control.
216 *
217 * @param[in] bus The bus control.
218 */
219void i2c_bus_destroy(i2c_bus *bus);
220
221/**
222 * @brief Destroys a bus control and frees its memory.
223 *
224 * @param[in] bus The bus control.
225 */
226void i2c_bus_destroy_and_free(i2c_bus *bus);
227
228/**
229 * @brief Registers a bus control.
230 *
231 * This function claims ownership of the bus control regardless if the
232 * registration is successful or not.
233 *
234 * @param[in] bus The bus control.
235 * @param[in] bus_path The path to the bus device file.
236 *
237 * @retval 0 Successful operation.
238 * @retval -1 An error occurred.  The errno is set to indicate the error.
239 */
240int i2c_bus_register(
241  i2c_bus *bus,
242  const char *bus_path
243);
244
245/**
246 * @brief Try to obtain the bus.
247 *
248 * @param[in] bus The bus control.
249 *
250 * @retval 0 Successful operation.
251 * @retval EBUSY if mutex is already locked.
252 */
253int i2c_bus_try_obtain(i2c_bus *bus);
254
255/**
256 * @brief Obtains the bus.
257 *
258 * @param[in] bus The bus control.
259 */
260void i2c_bus_obtain(i2c_bus *bus);
261
262/**
263 * @brief Releases the bus.
264 *
265 * @param[in] bus The bus control.
266 */
267void i2c_bus_release(i2c_bus *bus);
268
269/**
270 * @brief Transfers I2C messages.
271 *
272 * The bus is obtained before the transfer and released afterwards. This is the
273 * same like calling @ref i2c_bus_do_transfer with flags set to 0.
274 *
275 * @param[in] bus The bus control.
276 * @param[in] msgs The messages to transfer.
277 * @param[in] msg_count The count of messages to transfer.  It must be
278 * positive.
279 *
280 * @retval 0 Successful operation.
281 * @retval negative Negative error number in case of an error.
282 */
283int i2c_bus_transfer(i2c_bus *bus, i2c_msg *msgs, uint32_t msg_count);
284
285/**
286 * @brief Transfers I2C messages with optional flags.
287 *
288 * The bus is obtained before the transfer and released afterwards. If the flag
289 * I2C_BUS_NOBLOCK is set and the bus is already obtained, nothing will be
290 * transfered and the function returns with an -EAGAIN.
291 *
292 * @param[in] bus The bus control.
293 * @param[in] msgs The messages to transfer.
294 * @param[in] msg_count The count of messages to transfer.  It must be
295 * positive.
296 * @param[in] flags Options for the whole transfer.
297 *
298 * @retval 0 Successful operation.
299 * @retval -EAGAIN if @ref I2C_BUS_NOBLOCK is set and the bus is already
300 * obtained.
301 * @retval negative Negative error number in case of an error.
302 */
303int i2c_bus_do_transfer(
304  i2c_bus *bus,
305  i2c_msg *msgs,
306  uint32_t msg_count,
307  uint32_t flags
308);
309
310/**
311 * @brief I2C bus transfer flag to indicate that the task should not block if
312 * the bus is busy on a new transfer.
313 */
314#define I2C_BUS_NOBLOCK (1u << 0)
315
316/** @} */
317
318/**
319 * @defgroup I2CDevice I2C Device Driver
320 *
321 * @ingroup I2C
322 *
323 * @{
324 */
325
326/**
327 * @brief Base number for device IO control commands.
328 */
329#define I2C_DEV_IO_CONTROL 0x900
330
331/**
332 * @brief I2C slave device control.
333 */
334struct i2c_dev {
335  /**
336   * @brief Reads from the device.
337   *
338   * @retval non-negative Bytes transferred from device.
339   * @retval negative Negative error number in case of an error.
340   */
341  ssize_t (*read)(i2c_dev *dev, void *buf, size_t n, off_t offset);
342
343  /**
344   * @brief Writes to the device.
345   *
346   * @retval non-negative Bytes transferred to device.
347   * @retval negative Negative error number in case of an error.
348   */
349  ssize_t (*write)(i2c_dev *dev, const void *buf, size_t n, off_t offset);
350
351  /**
352   * @brief Device IO control.
353   *
354   * @retval 0 Successful operation.
355   * @retval negative Negative error number in case of an error.
356   */
357  int (*ioctl)(i2c_dev *dev, ioctl_command_t command, void *arg);
358
359  /**
360   * @brief Gets the file size.
361   */
362  off_t (*get_size)(i2c_dev *dev);
363
364  /**
365   * @brief Gets the file block size.
366   */
367  blksize_t (*get_block_size)(i2c_dev *dev);
368
369  /**
370   * @brief Destroys the device.
371   */
372  void (*destroy)(i2c_dev *dev);
373
374  /**
375   * @brief The bus control.
376   */
377  i2c_bus *bus;
378
379  /**
380   * @brief The device address.
381   */
382  uint16_t address;
383
384  /**
385   * @brief File descriptor of the bus.
386   *
387   * This prevents destruction of the bus since we hold a reference to it with
388   * this.
389   */
390  int bus_fd;
391};
392
393
394/**
395 * @brief Initializes a device control.
396 *
397 * After a sucessful initialization the device control must be destroyed via
398 * i2c_dev_destroy().  A registered device control will be automatically
399 * destroyed in case the device file is unlinked.  Make sure to call
400 * i2c_dev_destroy_and_free() in a custom destruction handler.
401 *
402 * @param[in] device The device control.
403 * @param[in] bus_path The path to the bus device file.
404 * @param[in] address The address of the device.
405 *
406 * @retval 0 Successful operation.
407 * @retval -1 An error occurred.  The errno is set to indicate the error.
408 *
409 * @see i2c_dev_register()
410 */
411int i2c_dev_init(i2c_dev *dev, const char *bus_path, uint16_t address);
412
413/**
414 * @brief Allocates a device control from the heap and initializes it.
415 *
416 * After a sucessful allocation and initialization the device control must be
417 * destroyed via i2c_dev_destroy_and_free().  A registered device control will
418 * be automatically destroyed in case the device file is unlinked.  Make sure
419 * to call i2c_dev_destroy_and_free() in a custom destruction handler.
420 *
421 * @param[in] size The size of the device control.  This enables the addition
422 * of device specific data to the base device control.  The device control is
423 * zero initialized.
424 * @param[in] bus_path The path to the bus device file.
425 * @param[in] address The address of the device.
426 *
427 * @retval non-NULL The new device control.
428 * @retval NULL An error occurred.  The errno is set to indicate the error.
429 *
430 * @see i2c_dev_register()
431 */
432i2c_dev *i2c_dev_alloc_and_init(
433  size_t size,
434  const char *bus_path,
435  uint16_t address
436);
437
438/**
439 * @brief Destroys a device control.
440 *
441 * @param[in] dev The device control.
442 */
443void i2c_dev_destroy(i2c_dev *dev);
444
445/**
446 * @brief Destroys a device control and frees its memory.
447 *
448 * @param[in] dev The device control.
449 */
450void i2c_dev_destroy_and_free(i2c_dev *dev);
451
452/**
453 * @brief Registers a device control.
454 *
455 * This function claims ownership of the device control regardless if the
456 * registration is successful or not.
457 *
458 * @param[in] dev The dev control.
459 * @param[in] dev_path The path to the device file of the device.
460 *
461 * @retval 0 Successful operation.
462 * @retval -1 An error occurred.  The errno is set to indicate the error.
463 */
464int i2c_dev_register(
465  i2c_dev *dev,
466  const char *dev_path
467);
468
469/** @} */  /* end of i2c device driver */
470
471/** @} */
472
473#ifdef __cplusplus
474}
475#endif /* __cplusplus */
476
477#endif /* _DEV_I2C_I2C_H */
Note: See TracBrowser for help on using the repository browser.