blob: 709a748d12853e89b94b6faf5fde62b1791df76d [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/**
Angel Ponsdb232952021-05-02 18:56:45 +020083 * i2c_open_from_programmer_params: open an I2C device from programmer params
84 *
85 * This function is a wrapper for i2c_open and i2c_open_path that obtains the
86 * I2C device to use from programmer parameters. It is meant to be called
87 * from I2C-based programmers to avoid repeating parameter parsing code.
88 */
89int i2c_open_from_programmer_params(uint16_t addr, int force);
90
91/**
Shiyu Sundc2c83b2020-03-19 16:59:52 +110092 * i2c_close - closes the file descriptor returned by i2c_open
93 *
94 * @fd: file descriptor to be closed.
95 *
96 * It is the client's responsibility to set fd = -1 when it is
97 * done with it.
98 *
99 * returns 0 on success, <0 to indicate failure
100 */
101int i2c_close(int fd);
102
103/**
104 * i2c_read - reads data from the I2C device
105 *
106 * @fd: file descriptor of the target device.
107 * @addr: I2C slave address of the target device.
108 * @buf_read: data struct includes reading buffer and size.
109 *
110 * This function does accept empty read and do nothing on such case.
111 *
112 * returns read length on success, <0 to indicate failure
113 */
114int i2c_read(int fd, uint16_t addr, i2c_buffer_t *buf_read);
115
116/**
117 * i2c_write - writes command/data into the I2C device
118 *
119 * @fd: file descriptor of the target device.
120 * @addr: I2C slave address of the target device.
121 * @buf_write: data struct includes writting buffer and size.
122 *
123 * This function does accept empty write and do nothing on such case.
124 *
125 * returns wrote length on success, <0 to indicate failure.
126 */
127int i2c_write(int fd, uint16_t addr, const i2c_buffer_t *buf_write);
128
129#endif /* !I2C_HELPER_H */