aboutsummaryrefslogtreecommitdiff
path: root/include/hw
diff options
context:
space:
mode:
authorPhilippe Mathieu-Daudé <f4bug@amsat.org>2020-07-06 00:41:54 +0200
committerCorey Minyard <cminyard@mvista.com>2020-07-16 12:30:54 -0500
commit73d5f22ecbb76dfc785876779d47787084ff0f42 (patch)
treef6948cbded902bb7ed65b1d16a2d9487b4fde362 /include/hw
parent1373b15bb55e46b067f84f70c60d3d03af62fd62 (diff)
downloadqemu-arm-73d5f22ecbb76dfc785876779d47787084ff0f42.tar.gz
hw/i2c: Document the I2C qdev helpers
In commit d88c42ff2c we added new prototype but neglected to add their documentation. Fix that. Reported-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Corey Minyard <cminyard@mvista.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Message-Id: <20200705224154.16917-6-f4bug@amsat.org> Signed-off-by: Corey Minyard <cminyard@mvista.com>
Diffstat (limited to 'include/hw')
-rw-r--r--include/hw/i2c/i2c.h48
1 files changed, 48 insertions, 0 deletions
diff --git a/include/hw/i2c/i2c.h b/include/hw/i2c/i2c.h
index c533058998..a9c030a512 100644
--- a/include/hw/i2c/i2c.h
+++ b/include/hw/i2c/i2c.h
@@ -79,8 +79,56 @@ int i2c_send_recv(I2CBus *bus, uint8_t *data, bool send);
int i2c_send(I2CBus *bus, uint8_t data);
uint8_t i2c_recv(I2CBus *bus);
+/**
+ * Create an I2C slave device on the heap.
+ * @name: a device type name
+ * @addr: I2C address of the slave when put on a bus
+ *
+ * This only initializes the device state structure and allows
+ * properties to be set. Type @name must exist. The device still
+ * needs to be realized. See qdev-core.h.
+ */
I2CSlave *i2c_slave_new(const char *name, uint8_t addr);
+
+/**
+ * Create and realize an I2C slave device on the heap.
+ * @bus: I2C bus to put it on
+ * @name: I2C slave device type name
+ * @addr: I2C address of the slave when put on a bus
+ *
+ * Create the device state structure, initialize it, put it on the
+ * specified @bus, and drop the reference to it (the device is realized).
+ */
I2CSlave *i2c_slave_create_simple(I2CBus *bus, const char *name, uint8_t addr);
+
+/**
+ * Realize and and drop a reference an I2C slave device
+ * @dev: I2C slave device to realize
+ * @bus: I2C bus to put it on
+ * @addr: I2C address of the slave on the bus
+ * @errp: pointer to NULL initialized error object
+ *
+ * Returns: %true on success, %false on failure.
+ *
+ * Call 'realize' on @dev, put it on the specified @bus, and drop the
+ * reference to it.
+ *
+ * This function is useful if you have created @dev via qdev_new(),
+ * i2c_slave_new() or i2c_slave_try_new() (which take a reference to
+ * the device it returns to you), so that you can set properties on it
+ * before realizing it. If you don't need to set properties then
+ * i2c_slave_create_simple() is probably better (as it does the create,
+ * init and realize in one step).
+ *
+ * If you are embedding the I2C slave into another QOM device and
+ * initialized it via some variant on object_initialize_child() then
+ * do not use this function, because that family of functions arrange
+ * for the only reference to the child device to be held by the parent
+ * via the child<> property, and so the reference-count-drop done here
+ * would be incorrect. (Instead you would want i2c_slave_realize(),
+ * which doesn't currently exist but would be trivial to create if we
+ * had any code that wanted it.)
+ */
bool i2c_slave_realize_and_unref(I2CSlave *dev, I2CBus *bus, Error **errp);
/* lm832x.c */