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