source: rtems/cpukit/include/dev/i2c/i2c.h @ 7cb1c2b0

5
Last change on this file since 7cb1c2b0 was 7cb1c2b0, checked in by Andreas Dachsberger <andreas.dachsberger@…>, on Apr 2, 2019 at 11:39:02 AM

doxygen: Added I2C Driver to Device Drivers

Update #3706.

  • Property mode set to 100644
File size: 9.5 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 Obtains the bus.
247 *
248 * @param[in] bus The bus control.
249 */
250void i2c_bus_obtain(i2c_bus *bus);
251
252/**
253 * @brief Releases the bus.
254 *
255 * @param[in] bus The bus control.
256 */
257void i2c_bus_release(i2c_bus *bus);
258
259/**
260 * @brief Transfers I2C messages.
261 *
262 * The bus is obtained before the transfer and released afterwards.
263 *
264 * @param[in] bus The bus control.
265 * @param[in] msgs The messages to transfer.
266 * @param[in] msg_count The count of messages to transfer.  It must be
267 * positive.
268 *
269 * @retval 0 Successful operation.
270 * @retval negative Negative error number in case of an error.
271 */
272int i2c_bus_transfer(i2c_bus *bus, i2c_msg *msgs, uint32_t msg_count);
273
274/** @} */
275
276/**
277 * @defgroup I2CDevice I2C Device Driver
278 *
279 * @ingroup I2C
280 *
281 * @{
282 */
283
284/**
285 * @brief Base number for device IO control commands.
286 */
287#define I2C_DEV_IO_CONTROL 0x900
288
289/**
290 * @brief I2C slave device control.
291 */
292struct i2c_dev {
293  /**
294   * @brief Reads from the device.
295   *
296   * @retval non-negative Bytes transferred from device.
297   * @retval negative Negative error number in case of an error.
298   */
299  ssize_t (*read)(i2c_dev *dev, void *buf, size_t n, off_t offset);
300
301  /**
302   * @brief Writes to the device.
303   *
304   * @retval non-negative Bytes transferred to device.
305   * @retval negative Negative error number in case of an error.
306   */
307  ssize_t (*write)(i2c_dev *dev, const void *buf, size_t n, off_t offset);
308
309  /**
310   * @brief Device IO control.
311   *
312   * @retval 0 Successful operation.
313   * @retval negative Negative error number in case of an error.
314   */
315  int (*ioctl)(i2c_dev *dev, ioctl_command_t command, void *arg);
316
317  /**
318   * @brief Gets the file size.
319   */
320  off_t (*get_size)(i2c_dev *dev);
321
322  /**
323   * @brief Gets the file block size.
324   */
325  blksize_t (*get_block_size)(i2c_dev *dev);
326
327  /**
328   * @brief Destroys the device.
329   */
330  void (*destroy)(i2c_dev *dev);
331
332  /**
333   * @brief The bus control.
334   */
335  i2c_bus *bus;
336
337  /**
338   * @brief The device address.
339   */
340  uint16_t address;
341
342  /**
343   * @brief File descriptor of the bus.
344   *
345   * This prevents destruction of the bus since we hold a reference to it with
346   * this.
347   */
348  int bus_fd;
349};
350
351
352/**
353 * @brief Initializes a device control.
354 *
355 * After a sucessful initialization the device control must be destroyed via
356 * i2c_dev_destroy().  A registered device control will be automatically
357 * destroyed in case the device file is unlinked.  Make sure to call
358 * i2c_dev_destroy_and_free() in a custom destruction handler.
359 *
360 * @param[in] device The device control.
361 * @param[in] bus_path The path to the bus device file.
362 * @param[in] address The address of the device.
363 *
364 * @retval 0 Successful operation.
365 * @retval -1 An error occurred.  The errno is set to indicate the error.
366 *
367 * @see i2c_dev_register()
368 */
369int i2c_dev_init(i2c_dev *dev, const char *bus_path, uint16_t address);
370
371/**
372 * @brief Allocates a device control from the heap and initializes it.
373 *
374 * After a sucessful allocation and initialization the device control must be
375 * destroyed via i2c_dev_destroy_and_free().  A registered device control will
376 * be automatically destroyed in case the device file is unlinked.  Make sure
377 * to call i2c_dev_destroy_and_free() in a custom destruction handler.
378 *
379 * @param[in] size The size of the device control.  This enables the addition
380 * of device specific data to the base device control.  The device control is
381 * zero initialized.
382 * @param[in] bus_path The path to the bus device file.
383 * @param[in] address The address of the device.
384 *
385 * @retval non-NULL The new device control.
386 * @retval NULL An error occurred.  The errno is set to indicate the error.
387 *
388 * @see i2c_dev_register()
389 */
390i2c_dev *i2c_dev_alloc_and_init(
391  size_t size,
392  const char *bus_path,
393  uint16_t address
394);
395
396/**
397 * @brief Destroys a device control.
398 *
399 * @param[in] dev The device control.
400 */
401void i2c_dev_destroy(i2c_dev *dev);
402
403/**
404 * @brief Destroys a device control and frees its memory.
405 *
406 * @param[in] dev The device control.
407 */
408void i2c_dev_destroy_and_free(i2c_dev *dev);
409
410/**
411 * @brief Registers a device control.
412 *
413 * This function claims ownership of the device control regardless if the
414 * registration is successful or not.
415 *
416 * @param[in] dev The dev control.
417 * @param[in] dev_path The path to the device file of the device.
418 *
419 * @retval 0 Successful operation.
420 * @retval -1 An error occurred.  The errno is set to indicate the error.
421 */
422int i2c_dev_register(
423  i2c_dev *dev,
424  const char *dev_path
425);
426
427/** @} */  /* end of i2c device driver */
428
429/** @} */
430
431#ifdef __cplusplus
432}
433#endif /* __cplusplus */
434
435#endif /* _DEV_I2C_I2C_H */
Note: See TracBrowser for help on using the repository browser.