Merge remote-tracking branch 'remotes/rth/tags/pull-tcg-20211016' into staging
[qemu.git] / include / hw / i2c / i2c.h
1 #ifndef QEMU_I2C_H
2 #define QEMU_I2C_H
3
4 #include "hw/qdev-core.h"
5 #include "qom/object.h"
6
7 /* The QEMU I2C implementation only supports simple transfers that complete
8 immediately. It does not support slave devices that need to be able to
9 defer their response (eg. CPU slave interfaces where the data is supplied
10 by the device driver in response to an interrupt). */
11
12 enum i2c_event {
13 I2C_START_RECV,
14 I2C_START_SEND,
15 I2C_FINISH,
16 I2C_NACK /* Masker NACKed a receive byte. */
17 };
18
19 typedef struct I2CNodeList I2CNodeList;
20
21 #define TYPE_I2C_SLAVE "i2c-slave"
22 OBJECT_DECLARE_TYPE(I2CSlave, I2CSlaveClass,
23 I2C_SLAVE)
24
25 struct I2CSlaveClass {
26 DeviceClass parent_class;
27
28 /* Master to slave. Returns non-zero for a NAK, 0 for success. */
29 int (*send)(I2CSlave *s, uint8_t data);
30
31 /*
32 * Slave to master. This cannot fail, the device should always
33 * return something here.
34 */
35 uint8_t (*recv)(I2CSlave *s);
36
37 /*
38 * Notify the slave of a bus state change. For start event,
39 * returns non-zero to NAK an operation. For other events the
40 * return code is not used and should be zero.
41 */
42 int (*event)(I2CSlave *s, enum i2c_event event);
43
44 /*
45 * Check if this device matches the address provided. Returns bool of
46 * true if it matches (or broadcast), and updates the device list, false
47 * otherwise.
48 *
49 * If broadcast is true, match should add the device and return true.
50 */
51 bool (*match_and_add)(I2CSlave *candidate, uint8_t address, bool broadcast,
52 I2CNodeList *current_devs);
53 };
54
55 struct I2CSlave {
56 DeviceState qdev;
57
58 /* Remaining fields for internal use by the I2C code. */
59 uint8_t address;
60 };
61
62 #define TYPE_I2C_BUS "i2c-bus"
63 OBJECT_DECLARE_SIMPLE_TYPE(I2CBus, I2C_BUS)
64
65 typedef struct I2CNode I2CNode;
66
67 struct I2CNode {
68 I2CSlave *elt;
69 QLIST_ENTRY(I2CNode) next;
70 };
71
72 typedef QLIST_HEAD(I2CNodeList, I2CNode) I2CNodeList;
73
74 struct I2CBus {
75 BusState qbus;
76 I2CNodeList current_devs;
77 uint8_t saved_address;
78 bool broadcast;
79 };
80
81 I2CBus *i2c_init_bus(DeviceState *parent, const char *name);
82 int i2c_bus_busy(I2CBus *bus);
83
84 /**
85 * i2c_start_transfer: start a transfer on an I2C bus.
86 *
87 * @bus: #I2CBus to be used
88 * @address: address of the slave
89 * @is_recv: indicates the transfer direction
90 *
91 * When @is_recv is a known boolean constant, use the
92 * i2c_start_recv() or i2c_start_send() helper instead.
93 *
94 * Returns: 0 on success, -1 on error
95 */
96 int i2c_start_transfer(I2CBus *bus, uint8_t address, bool is_recv);
97
98 /**
99 * i2c_start_recv: start a 'receive' transfer on an I2C bus.
100 *
101 * @bus: #I2CBus to be used
102 * @address: address of the slave
103 *
104 * Returns: 0 on success, -1 on error
105 */
106 int i2c_start_recv(I2CBus *bus, uint8_t address);
107
108 /**
109 * i2c_start_send: start a 'send' transfer on an I2C bus.
110 *
111 * @bus: #I2CBus to be used
112 * @address: address of the slave
113 *
114 * Returns: 0 on success, -1 on error
115 */
116 int i2c_start_send(I2CBus *bus, uint8_t address);
117
118 void i2c_end_transfer(I2CBus *bus);
119 void i2c_nack(I2CBus *bus);
120 int i2c_send(I2CBus *bus, uint8_t data);
121 uint8_t i2c_recv(I2CBus *bus);
122 bool i2c_scan_bus(I2CBus *bus, uint8_t address, bool broadcast,
123 I2CNodeList *current_devs);
124
125 /**
126 * Create an I2C slave device on the heap.
127 * @name: a device type name
128 * @addr: I2C address of the slave when put on a bus
129 *
130 * This only initializes the device state structure and allows
131 * properties to be set. Type @name must exist. The device still
132 * needs to be realized. See qdev-core.h.
133 */
134 I2CSlave *i2c_slave_new(const char *name, uint8_t addr);
135
136 /**
137 * Create and realize an I2C slave device on the heap.
138 * @bus: I2C bus to put it on
139 * @name: I2C slave device type name
140 * @addr: I2C address of the slave when put on a bus
141 *
142 * Create the device state structure, initialize it, put it on the
143 * specified @bus, and drop the reference to it (the device is realized).
144 */
145 I2CSlave *i2c_slave_create_simple(I2CBus *bus, const char *name, uint8_t addr);
146
147 /**
148 * Realize and drop a reference an I2C slave device
149 * @dev: I2C slave device to realize
150 * @bus: I2C bus to put it on
151 * @addr: I2C address of the slave on the bus
152 * @errp: pointer to NULL initialized error object
153 *
154 * Returns: %true on success, %false on failure.
155 *
156 * Call 'realize' on @dev, put it on the specified @bus, and drop the
157 * reference to it.
158 *
159 * This function is useful if you have created @dev via qdev_new(),
160 * i2c_slave_new() or i2c_slave_try_new() (which take a reference to
161 * the device it returns to you), so that you can set properties on it
162 * before realizing it. If you don't need to set properties then
163 * i2c_slave_create_simple() is probably better (as it does the create,
164 * init and realize in one step).
165 *
166 * If you are embedding the I2C slave into another QOM device and
167 * initialized it via some variant on object_initialize_child() then
168 * do not use this function, because that family of functions arrange
169 * for the only reference to the child device to be held by the parent
170 * via the child<> property, and so the reference-count-drop done here
171 * would be incorrect. (Instead you would want i2c_slave_realize(),
172 * which doesn't currently exist but would be trivial to create if we
173 * had any code that wanted it.)
174 */
175 bool i2c_slave_realize_and_unref(I2CSlave *dev, I2CBus *bus, Error **errp);
176
177 /**
178 * Set the I2C bus address of a slave device
179 * @dev: I2C slave device
180 * @address: I2C address of the slave when put on a bus
181 */
182 void i2c_slave_set_address(I2CSlave *dev, uint8_t address);
183
184 extern const VMStateDescription vmstate_i2c_slave;
185
186 #define VMSTATE_I2C_SLAVE(_field, _state) { \
187 .name = (stringify(_field)), \
188 .size = sizeof(I2CSlave), \
189 .vmsd = &vmstate_i2c_slave, \
190 .flags = VMS_STRUCT, \
191 .offset = vmstate_offset_value(_state, _field, I2CSlave), \
192 }
193
194 #endif