include/hw/ssi/ssi.h

   1 /* QEMU Synchronous Serial Interface support.  */
   2
   3 /*
   4  * In principle SSI is a point-point interface.  As such the qemu
   5  * implementation has a single peripheral on a "bus".
   6  * However it is fairly common for boards to have multiple peripherals
   7  * connected to a single master, and select devices with an external
   8  * chip select.  This is implemented in qemu by having an explicit mux device.
   9  * It is assumed that master and peripheral are both using the same transfer
  10  * width.
  11  */
  12
  13 #ifndef QEMU_SSI_H
  14 #define QEMU_SSI_H
  15
  16 #include "hw/qdev-core.h"
  17 #include "qom/object.h"
  18
  19 typedef enum SSICSMode SSICSMode;
  20
  21 #define TYPE_SSI_PERIPHERAL "ssi-peripheral"
  22 OBJECT_DECLARE_TYPE(SSIPeripheral, SSIPeripheralClass,
  23                     SSI_PERIPHERAL)
  24
  25 #define SSI_GPIO_CS "ssi-gpio-cs"
  26
  27 enum SSICSMode {
  28     SSI_CS_NONE = 0,
  29     SSI_CS_LOW,
  30     SSI_CS_HIGH,
  31 };
  32
  33 /* Peripherals.  */
  34 struct SSIPeripheralClass {
  35     DeviceClass parent_class;
  36
  37     void (*realize)(SSIPeripheral *dev, Error **errp);
  38
  39     /* if you have standard or no CS behaviour, just override transfer.
  40      * This is called when the device cs is active (true by default).
  41      */
  42     uint32_t (*transfer)(SSIPeripheral *dev, uint32_t val);
  43     /* called when the CS line changes. Optional, devices only need to implement
  44      * this if they have side effects associated with the cs line (beyond
  45      * tristating the txrx lines).
  46      */
  47     int (*set_cs)(SSIPeripheral *dev, bool select);
  48     /* define whether or not CS exists and is active low/high */
  49     SSICSMode cs_polarity;
  50
  51     /* if you have non-standard CS behaviour override this to take control
  52      * of the CS behaviour at the device level. transfer, set_cs, and
  53      * cs_polarity are unused if this is overwritten. Transfer_raw will
  54      * always be called for the device for every txrx access to the parent bus
  55      */
  56     uint32_t (*transfer_raw)(SSIPeripheral *dev, uint32_t val);
  57 };
  58
  59 struct SSIPeripheral {
  60     DeviceState parent_obj;
  61
  62     /* cache the class */
  63     SSIPeripheralClass *spc;
  64
  65     /* Chip select state */
  66     bool cs;
  67
  68     /* Chip select index */
  69     uint8_t cs_index;
  70 };
  71
  72 extern const VMStateDescription vmstate_ssi_peripheral;
  73
  74 #define VMSTATE_SSI_PERIPHERAL(_field, _state) {                     \
  75     .name       = (stringify(_field)),                               \
  76     .size       = sizeof(SSIPeripheral),                             \
  77     .vmsd       = &vmstate_ssi_peripheral,                           \
  78     .flags      = VMS_STRUCT,                                        \
  79     .offset     = vmstate_offset_value(_state, _field, SSIPeripheral), \
  80 }
  81
  82 DeviceState *ssi_create_peripheral(SSIBus *bus, const char *name);
  83 /**
  84  * ssi_realize_and_unref: realize and unref an SSI peripheral
  85  * @dev: SSI peripheral to realize
  86  * @bus: SSI bus to put it on
  87  * @errp: error pointer
  88  *
  89  * Call 'realize' on @dev, put it on the specified @bus, and drop the
  90  * reference to it. Errors are reported via @errp and by returning
  91  * false.
  92  *
  93  * This function is useful if you have created @dev via qdev_new()
  94  * (which takes a reference to the device it returns to you), so that
  95  * you can set properties on it before realizing it. If you don't need
  96  * to set properties then ssi_create_peripheral() is probably better (as it
  97  * does the create, init and realize in one step).
  98  *
  99  * If you are embedding the SSI peripheral into another QOM device and
 100  * initialized it via some variant on object_initialize_child() then
 101  * do not use this function, because that family of functions arrange
 102  * for the only reference to the child device to be held by the parent
 103  * via the child<> property, and so the reference-count-drop done here
 104  * would be incorrect.  (Instead you would want ssi_realize(), which
 105  * doesn't currently exist but would be trivial to create if we had
 106  * any code that wanted it.)
 107  */
 108 bool ssi_realize_and_unref(DeviceState *dev, SSIBus *bus, Error **errp);
 109
 110 /* Master interface.  */
 111 SSIBus *ssi_create_bus(DeviceState *parent, const char *name);
 112
 113 uint32_t ssi_transfer(SSIBus *bus, uint32_t val);
 114
 115 DeviceState *ssi_get_cs(SSIBus *bus, uint8_t cs_index);
 116
 117 #endif