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  * Must be called before @dev is realized.
  75  */
  76 void qdev_connect_clock_in(DeviceState *dev, const char *name, Clock *source);
  77
  78 /**
  79  * qdev_alias_clock:
  80  * @dev: the device which has the clock
  81  * @name: the name of the clock in @dev (can't be NULL)
  82  * @alias_dev: the device to add the clock
  83  * @alias_name: the name of the clock in @container
  84  * @returns: a pointer to the clock
  85  *
  86  * Add a clock @alias_name in @alias_dev which is an alias of the clock @name
  87  * in @dev. The direction _in_ or _out_ will the same as the original.
  88  * An alias clock must not be modified or used by @alias_dev and should
  89  * typically be only only for device composition purpose.
  90  */
  91 Clock *qdev_alias_clock(DeviceState *dev, const char *name,
  92                         DeviceState *alias_dev, const char *alias_name);
  93
  94 /**
  95  * qdev_finalize_clocklist:
  96  * @dev: the device being finalized
  97  *
  98  * Clear the clocklist from @dev. Only used internally in qdev.
  99  */
 100 void qdev_finalize_clocklist(DeviceState *dev);
 101
 102 /**
 103  * ClockPortInitElem:
 104  * @name: name of the clock (can't be NULL)
 105  * @output: indicates whether the clock is input or output
 106  * @callback: for inputs, optional callback to be called on clock's update
 107  * with device as opaque
 108  * @offset: optional offset to store the ClockIn or ClockOut pointer in device
 109  * state structure (0 means unused)
 110  */
 111 struct ClockPortInitElem {
 112     const char *name;
 113     bool is_output;
 114     ClockCallback *callback;
 115     size_t offset;
 116 };
 117
 118 #define clock_offset_value(devstate, field) \
 119     (offsetof(devstate, field) + \
 120      type_check(Clock *, typeof_field(devstate, field)))
 121
 122 #define QDEV_CLOCK(out_not_in, devstate, field, cb) { \
 123     .name = (stringify(field)), \
 124     .is_output = out_not_in, \
 125     .callback = cb, \
 126     .offset = clock_offset_value(devstate, field), \
 127 }
 128
 129 /**
 130  * QDEV_CLOCK_(IN|OUT):
 131  * @devstate: structure type. @dev argument of qdev_init_clocks below must be
 132  * a pointer to that same type.
 133  * @field: a field in @_devstate (must be Clock*)
 134  * @callback: (for input only) callback (or NULL) to be called with the device
 135  * state as argument
 136  *
 137  * The name of the clock will be derived from @field
 138  */
 139 #define QDEV_CLOCK_IN(devstate, field, callback) \
 140     QDEV_CLOCK(false, devstate, field, callback)
 141
 142 #define QDEV_CLOCK_OUT(devstate, field) \
 143     QDEV_CLOCK(true, devstate, field, NULL)
 144
 145 #define QDEV_CLOCK_END { .name = NULL }
 146
 147 typedef struct ClockPortInitElem ClockPortInitArray[];
 148
 149 /**
 150  * qdev_init_clocks:
 151  * @dev: the device to add clocks to
 152  * @clocks: a QDEV_CLOCK_END-terminated array which contains the
 153  * clocks information.
 154  */
 155 void qdev_init_clocks(DeviceState *dev, const ClockPortInitArray clocks);
 156
 157 #endif /* QDEV_CLOCK_H */