blob: cab2ce6f30305696ff753aa61daad344e72f41b2 [file] [log] [blame]
Shiyu Sundc2c83b2020-03-19 16:59:52 +11001/*
2 * This file is part of the flashrom project.
3 *
4 * Copyright (C) 2020 The Chromium OS Authors
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 */
16
17#ifndef I2C_HELPER_H
18#define I2C_HELPER_H
19
20#include <inttypes.h>
21
22/**
23 * An convinent structure that contains the buffer size and the buffer
24 * pointer. Used to wrap buffer details while doing the I2C data
25 * transfer on both input and output. It is the client's responsibility
26 * to use i2c_buffer_t_fill to initialize this struct instead of
27 * trying to construct it directly.
28 */
29typedef struct {
30 void *buf;
31 uint16_t len;
32} i2c_buffer_t;
33
34/**
35 * i2c_buffer_t_fill - fills in the i2c_buffer_t
36 *
37 * @i2c_buf: pointer to the be constructed.
38 * @buf: buffer contains data to be included in i2c_buffer_t.
39 * @len: length of buffer to be included in i2c_buffer_t.
40 *
41 * This function takes in a pointer to an initialized i2c_buffer_t
42 * object with related information, and fill in the i2c_buffer_t with
43 * some validation applied. The function does allow initialization with
44 * NULL buffer but will make sure len == 0 in such case.
45 *
46 * returns 0 on success, <0 to indicate failure
47 */
48static inline int i2c_buffer_t_fill(i2c_buffer_t *i2c_buf, void *buf, uint16_t len)
49{
50 if (!i2c_buf || (!buf && len))
51 return -1;
52
53 i2c_buf->buf = buf;
54 i2c_buf->len = len;
55
56 return 0;
57}
58
59/**
60 * i2c_open - opens the target I2C device and set the I2C slave address
61 *
62 * @bus: I2C bus number of the target device.
63 * @addr: I2C slave address.
64 * @force: whether to force set the I2C slave address.
65 *
66 * This function returns a file descriptor for the target device. It is
67 * the client's responsibility to pass the return value to i2c_close to
68 * clean up.
69 *
70 * returns fd of target device on success, <0 to indicate failure
71 */
72int i2c_open(int bus, uint16_t addr, int force);
73
74/**
Peter Marheine0969e432021-03-31 11:28:11 +110075 * i2c_open_path: open an I2C device by device path
76 *
77 * This function behaves the same as i2c_open, but takes a filesystem
78 * path (assumed to be an I2C device file) instead of a bus number.
79 */
80int i2c_open_path(const char *path, uint16_t addr, int force);
81
82/**
Shiyu Sundc2c83b2020-03-19 16:59:52 +110083 * i2c_close - closes the file descriptor returned by i2c_open
84 *
85 * @fd: file descriptor to be closed.
86 *
87 * It is the client's responsibility to set fd = -1 when it is
88 * done with it.
89 *
90 * returns 0 on success, <0 to indicate failure
91 */
92int i2c_close(int fd);
93
94/**
95 * i2c_read - reads data from the I2C device
96 *
97 * @fd: file descriptor of the target device.
98 * @addr: I2C slave address of the target device.
99 * @buf_read: data struct includes reading buffer and size.
100 *
101 * This function does accept empty read and do nothing on such case.
102 *
103 * returns read length on success, <0 to indicate failure
104 */
105int i2c_read(int fd, uint16_t addr, i2c_buffer_t *buf_read);
106
107/**
108 * i2c_write - writes command/data into the I2C device
109 *
110 * @fd: file descriptor of the target device.
111 * @addr: I2C slave address of the target device.
112 * @buf_write: data struct includes writting buffer and size.
113 *
114 * This function does accept empty write and do nothing on such case.
115 *
116 * returns wrote length on success, <0 to indicate failure.
117 */
118int i2c_write(int fd, uint16_t addr, const i2c_buffer_t *buf_write);
119
120#endif /* !I2C_HELPER_H */