OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

hw/i2c: Document the I2C qdev helpers

Browse Source 
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>
This commit is contained in:
Philippe Mathieu-Daudé 2020-07-06 00:41:54 +02:00 committed by Corey Minyard
parent 1373b15bb5
commit 73d5f22ecb
1 changed files with 48 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
include/hw/i2c/i2c.h
View File

@ -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 */