include/hw/qdev-clock.h

   1 /*
   2  * Device's clock input and output
   3  *
   4  * Copyright GreenSocs 2016-2020
   5  *
   6  * Authors:
   7  *  Frederic Konrad
   8  *  Damien Hedde
   9  *
  10  * This work is licensed under the terms of the GNU GPL, version 2 or later.
  11  * See the COPYING file in the top-level directory.
  12  */
  13
  14 #ifndef QDEV_CLOCK_H
  15 #define QDEV_CLOCK_H
  16
  17 #include "hw/clock.h"
  18
  19 /**
  20  * qdev_init_clock_in:
  21  * @dev: the device to add an input clock to
  22  * @name: the name of the clock (can't be NULL).
  23  * @callback: optional callback to be called on update or NULL.
  24  * @opaque: argument for the callback
  25  * @returns: a pointer to the newly added clock
  26  *
  27  * Add an input clock to device @dev as a clock named @name.
  28  * This adds a child<> property.
  29  * The callback will be called with @opaque as opaque parameter.
  30  */
  31 Clock *qdev_init_clock_in(DeviceState *dev, const char *name,
  32                           ClockCallback *callback, void *opaque);
  33
  34 /**
  35  * qdev_init_clock_out:
  36  * @dev: the device to add an output clock to
  37  * @name: the name of the clock (can't be NULL).
  38  * @returns: a pointer to the newly added clock
  39  *
  40  * Add an output clock to device @dev as a clock named @name.
  41  * This adds a child<> property.
  42  */
  43 Clock *qdev_init_clock_out(DeviceState *dev, const char *name);
  44
  45 /**
  46  * qdev_get_clock_in:
  47  * @dev: the device which has the clock
  48  * @name: the name of the clock (can't be NULL).
  49  * @returns: a pointer to the clock
  50  *
  51  * Get the input clock @name from @dev or NULL if does not exist.
  52  */
  53 Clock *qdev_get_clock_in(DeviceState *dev, const char *name);
  54
  55 /**
  56  * qdev_get_clock_out:
  57  * @dev: the device which has the clock
  58  * @name: the name of the clock (can't be NULL).
  59  * @returns: a pointer to the clock
  60  *
  61  * Get the output clock @name from @dev or NULL if does not exist.
  62  */
  63 Clock *qdev_get_clock_out(DeviceState *dev, const char *name);
  64
  65 /**
  66  * qdev_connect_clock_in:
  67  * @dev: a device
  68  * @name: the name of an input clock in @dev
  69  * @source: the source clock (an output clock of another device for example)
  70  *
  71  * Set the source clock of input clock @name of device @dev to @source.
  72  * @source period update will be propagated to @name clock.
  73  */
  74 static inline void qdev_connect_clock_in(DeviceState *dev, const char *name,
  75                                          Clock *source)
  76 {
  77     clock_set_source(qdev_get_clock_in(dev, name), source);
  78 }
  79
  80 /**
  81  * qdev_alias_clock:
  82  * @dev: the device which has the clock
  83  * @name: the name of the clock in @dev (can't be NULL)
  84  * @alias_dev: the device to add the clock
  85  * @alias_name: the name of the clock in @container
  86  * @returns: a pointer to the clock
  87  *
  88  * Add a clock @alias_name in @alias_dev which is an alias of the clock @name
  89  * in @dev. The direction _in_ or _out_ will the same as the original.
  90  * An alias clock must not be modified or used by @alias_dev and should
  91  * typically be only only for device composition purpose.
  92  */
  93 Clock *qdev_alias_clock(DeviceState *dev, const char *name,
  94                         DeviceState *alias_dev, const char *alias_name);
  95
  96 /**
  97  * qdev_finalize_clocklist:
  98  * @dev: the device being finalized
  99  *
 100  * Clear the clocklist from @dev. Only used internally in qdev.
 101  */
 102 void qdev_finalize_clocklist(DeviceState *dev);
 103
 104 /**
 105  * ClockPortInitElem:
 106  * @name: name of the clock (can't be NULL)
 107  * @output: indicates whether the clock is input or output
 108  * @callback: for inputs, optional callback to be called on clock's update
 109  * with device as opaque
 110  * @offset: optional offset to store the ClockIn or ClockOut pointer in device
 111  * state structure (0 means unused)
 112  */
 113 struct ClockPortInitElem {
 114     const char *name;
 115     bool is_output;
 116     ClockCallback *callback;
 117     size_t offset;
 118 };
 119
 120 #define clock_offset_value(devstate, field) \
 121     (offsetof(devstate, field) + \
 122      type_check(Clock *, typeof_field(devstate, field)))
 123
 124 #define QDEV_CLOCK(out_not_in, devstate, field, cb) { \
 125     .name = (stringify(field)), \
 126     .is_output = out_not_in, \
 127     .callback = cb, \
 128     .offset = clock_offset_value(devstate, field), \
 129 }
 130
 131 /**
 132  * QDEV_CLOCK_(IN|OUT):
 133  * @devstate: structure type. @dev argument of qdev_init_clocks below must be
 134  * a pointer to that same type.
 135  * @field: a field in @_devstate (must be Clock*)
 136  * @callback: (for input only) callback (or NULL) to be called with the device
 137  * state as argument
 138  *
 139  * The name of the clock will be derived from @field
 140  */
 141 #define QDEV_CLOCK_IN(devstate, field, callback) \
 142     QDEV_CLOCK(false, devstate, field, callback)
 143
 144 #define QDEV_CLOCK_OUT(devstate, field) \
 145     QDEV_CLOCK(true, devstate, field, NULL)
 146
 147 #define QDEV_CLOCK_END { .name = NULL }
 148
 149 typedef struct ClockPortInitElem ClockPortInitArray[];
 150
 151 /**
 152  * qdev_init_clocks:
 153  * @dev: the device to add clocks to
 154  * @clocks: a QDEV_CLOCK_END-terminated array which contains the
 155  * clocks information.
 156  */
 157 void qdev_init_clocks(DeviceState *dev, const ClockPortInitArray clocks);
 158
 159 #endif /* QDEV_CLOCK_H */