1 /*
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 struct programmer_cfg; /* defined in programmer.h */
23
24 /**
25 * An convenient structure that contains the buffer size and the buffer
26 * pointer. Used to wrap buffer details while doing the I2C data
27 * transfer on both input and output. It is the client's responsibility
28 * to use i2c_buffer_t_fill to initialize this struct instead of
29 * trying to construct it directly.
30 */
31 typedef struct {
32 void *buf;
33 uint16_t len;
34 } i2c_buffer_t;
35
36 /**
37 * i2c_buffer_t_fill - fills in the i2c_buffer_t
38 *
39 * @i2c_buf: pointer to the be constructed.
40 * @buf: buffer contains data to be included in i2c_buffer_t.
41 * @len: length of buffer to be included in i2c_buffer_t.
42 *
43 * This function takes in a pointer to an initialized i2c_buffer_t
44 * object with related information, and fill in the i2c_buffer_t with
45 * some validation applied. The function does allow initialization with
46 * NULL buffer but will make sure len == 0 in such case.
47 *
48 * returns 0 on success, <0 to indicate failure
49 */
i2c_buffer_t_fill(i2c_buffer_t * i2c_buf,void * buf,uint16_t len)50 static inline int i2c_buffer_t_fill(i2c_buffer_t *i2c_buf, void *buf, uint16_t len)
51 {
52 if (!i2c_buf || (!buf && len))
53 return -1;
54
55 i2c_buf->buf = buf;
56 i2c_buf->len = len;
57
58 return 0;
59 }
60
61 /**
62 * i2c_open - opens the target I2C device and set the I2C slave address
63 *
64 * @bus: I2C bus number of the target device.
65 * @addr: I2C slave address.
66 * @force: whether to force set the I2C slave address.
67 *
68 * This function returns a file descriptor for the target device. It is
69 * the client's responsibility to pass the return value to i2c_close to
70 * clean up.
71 *
72 * returns fd of target device on success, <0 to indicate failure
73 */
74 int i2c_open(int bus, uint16_t addr, int force);
75
76 /**
77 * i2c_open_path: open an I2C device by device path
78 *
79 * This function behaves the same as i2c_open, but takes a filesystem
80 * path (assumed to be an I2C device file) instead of a bus number.
81 */
82 int i2c_open_path(const char *path, uint16_t addr, int force);
83
84 /**
85 * i2c_open_from_programmer_params: open an I2C device from programmer params
86 *
87 * This function is a wrapper for i2c_open and i2c_open_path that obtains the
88 * I2C device to use from programmer parameters. It is meant to be called
89 * from I2C-based programmers to avoid repeating parameter parsing code.
90 */
91 int i2c_open_from_programmer_params(const struct programmer_cfg *cfg, uint16_t addr, int force);
92
93 /**
94 * i2c_close - closes the file descriptor returned by i2c_open
95 *
96 * @fd: file descriptor to be closed.
97 *
98 * It is the client's responsibility to set fd = -1 when it is
99 * done with it.
100 *
101 * returns 0 on success, <0 to indicate failure
102 */
103 int i2c_close(int fd);
104
105 /**
106 * i2c_read - reads data from the I2C device
107 *
108 * @fd: file descriptor of the target device.
109 * @addr: I2C slave address of the target device.
110 * @buf_read: data struct includes reading buffer and size.
111 *
112 * This function does accept empty read and do nothing on such case.
113 *
114 * returns read length on success, <0 to indicate failure
115 */
116 int i2c_read(int fd, uint16_t addr, i2c_buffer_t *buf_read);
117
118 /**
119 * i2c_write - writes command/data into the I2C device
120 *
121 * @fd: file descriptor of the target device.
122 * @addr: I2C slave address of the target device.
123 * @buf_write: data struct includes writing buffer and size.
124 *
125 * This function does accept empty write and do nothing on such case.
126 *
127 * returns wrote length on success, <0 to indicate failure.
128 */
129 int i2c_write(int fd, uint16_t addr, const i2c_buffer_t *buf_write);
130
131 #endif /* !I2C_HELPER_H */
132