include/hw/register.h

   1 /*
   2  * Register Definition API
   3  *
   4  * Copyright (c) 2016 Xilinx Inc.
   5  * Copyright (c) 2013 Peter Crosthwaite <peter.crosthwaite@xilinx.com>
   6  *
   7  * This work is licensed under the terms of the GNU GPL, version 2.  See
   8  * the COPYING file in the top-level directory.
   9  */
  10
  11 #ifndef REGISTER_H
  12 #define REGISTER_H
  13
  14 #include "hw/qdev-core.h"
  15 #include "exec/memory.h"
  16
  17 typedef struct RegisterInfo RegisterInfo;
  18 typedef struct RegisterAccessInfo RegisterAccessInfo;
  19 typedef struct RegisterInfoArray RegisterInfoArray;
  20
  21 /**
  22  * Access description for a register that is part of guest accessible device
  23  * state.
  24  *
  25  * @name: String name of the register
  26  * @ro: whether or not the bit is read-only
  27  * @w1c: bits with the common write 1 to clear semantic.
  28  * @reset: reset value.
  29  * @cor: Bits that are clear on read
  30  * @rsvd: Bits that are reserved and should not be changed
  31  *
  32  * @pre_write: Pre write callback. Passed the value that's to be written,
  33  * immediately before the actual write. The returned value is what is written,
  34  * giving the handler a chance to modify the written value.
  35  * @post_write: Post write callback. Passed the written value. Most write side
  36  * effects should be implemented here.
  37  *
  38  * @post_read: Post read callback. Passes the value that is about to be returned
  39  * for a read. The return value from this function is what is ultimately read,
  40  * allowing this function to modify the value before return to the client.
  41  */
  42
  43 struct RegisterAccessInfo {
  44     const char *name;
  45     uint64_t ro;
  46     uint64_t w1c;
  47     uint64_t reset;
  48     uint64_t cor;
  49     uint64_t rsvd;
  50     uint64_t unimp;
  51
  52     uint64_t (*pre_write)(RegisterInfo *reg, uint64_t val);
  53     void (*post_write)(RegisterInfo *reg, uint64_t val);
  54
  55     uint64_t (*post_read)(RegisterInfo *reg, uint64_t val);
  56
  57     hwaddr addr;
  58 };
  59
  60 /**
  61  * A register that is part of guest accessible state
  62  * @data: pointer to the register data. Will be cast
  63  * to the relevant uint type depending on data_size.
  64  * @data_size: Size of the register in bytes. Must be
  65  * 1, 2, 4 or 8
  66  *
  67  * @access: Access description of this register
  68  *
  69  * @debug: Whether or not verbose debug is enabled
  70  * @prefix: String prefix for log and debug messages
  71  *
  72  * @opaque: Opaque data for the register
  73  */
  74
  75 struct RegisterInfo {
  76     /* <private> */
  77     DeviceState parent_obj;
  78
  79     /* <public> */
  80     void *data;
  81     int data_size;
  82
  83     const RegisterAccessInfo *access;
  84
  85     void *opaque;
  86 };
  87
  88 #define TYPE_REGISTER "qemu,register"
  89 #define REGISTER(obj) OBJECT_CHECK(RegisterInfo, (obj), TYPE_REGISTER)
  90
  91 /**
  92  * This structure is used to group all of the individual registers which are
  93  * modeled using the RegisterInfo structure.
  94  *
  95  * @r is an aray containing of all the relevent RegisterInfo structures.
  96  *
  97  * @num_elements is the number of elements in the array r
  98  *
  99  * @mem: optional Memory region for the register
 100  */
 101
 102 struct RegisterInfoArray {
 103     MemoryRegion mem;
 104
 105     int num_elements;
 106     RegisterInfo **r;
 107
 108     bool debug;
 109     const char *prefix;
 110 };
 111
 112 /**
 113  * write a value to a register, subject to its restrictions
 114  * @reg: register to write to
 115  * @val: value to write
 116  * @we: write enable mask
 117  * @prefix: The device prefix that should be printed before the register name
 118  * @debug: Should the write operation debug information be printed?
 119  */
 120
 121 void register_write(RegisterInfo *reg, uint64_t val, uint64_t we,
 122                     const char *prefix, bool debug);
 123
 124 /**
 125  * read a value from a register, subject to its restrictions
 126  * @reg: register to read from
 127  * @re: read enable mask
 128  * @prefix: The device prefix that should be printed before the register name
 129  * @debug: Should the read operation debug information be printed?
 130  * returns: value read
 131  */
 132
 133 uint64_t register_read(RegisterInfo *reg, uint64_t re, const char* prefix,
 134                        bool debug);
 135
 136 /**
 137  * reset a register
 138  * @reg: register to reset
 139  */
 140
 141 void register_reset(RegisterInfo *reg);
 142
 143 /**
 144  * Initialize a register.
 145  * @reg: Register to initialize
 146  */
 147
 148 void register_init(RegisterInfo *reg);
 149
 150 /**
 151  * Memory API MMIO write handler that will write to a Register API register.
 152  * @opaque: RegisterInfo to write to
 153  * @addr: Address to write
 154  * @value: Value to write
 155  * @size: Number of bytes to write
 156  */
 157
 158 void register_write_memory(void *opaque, hwaddr addr, uint64_t value,
 159                            unsigned size);
 160
 161 /**
 162  * Memory API MMIO read handler that will read from a Register API register.
 163  * @opaque: RegisterInfo to read from
 164  * @addr: Address to read
 165  * @size: Number of bytes to read
 166  * returns: Value read from register
 167  */
 168
 169 uint64_t register_read_memory(void *opaque, hwaddr addr, unsigned size);
 170
 171 /**
 172  * Init a block of registers into a container MemoryRegion. A
 173  * number of constant register definitions are parsed to create a corresponding
 174  * array of RegisterInfo's.
 175  *
 176  * @owner: device owning the registers
 177  * @rae: Register definitions to init
 178  * @num: number of registers to init (length of @rae)
 179  * @ri: Register array to init, must already be allocated
 180  * @data: Array to use for register data, must already be allocated
 181  * @ops: Memory region ops to access registers.
 182  * @debug enabled: turn on/off verbose debug information
 183  * returns: A structure containing all of the registers and an initialized
 184  *          memory region (r_array->mem) the caller should add to a container.
 185  */
 186
 187 RegisterInfoArray *register_init_block32(DeviceState *owner,
 188                                          const RegisterAccessInfo *rae,
 189                                          int num, RegisterInfo *ri,
 190                                          uint32_t *data,
 191                                          const MemoryRegionOps *ops,
 192                                          bool debug_enabled,
 193                                          uint64_t memory_size);
 194
 195 /**
 196  * This function should be called to cleanup the registers that were initialized
 197  * when calling register_init_block32(). This function should only be called
 198  * from the device's instance_finalize function.
 199  *
 200  * Any memory operations that the device performed that require cleanup (such
 201  * as creating subregions) need to be called before calling this function.
 202  *
 203  * @r_array: A structure containing all of the registers, as returned by
 204  *           register_init_block32()
 205  */
 206
 207 void register_finalize_block(RegisterInfoArray *r_array);
 208
 209 /* Define constants for a 32 bit register */
 210
 211 /* This macro will define A_FOO, for the byte address of a register
 212  * as well as R_FOO for the uint32_t[] register number (A_FOO / 4).
 213  */
 214 #define REG32(reg, addr)                                                  \
 215     enum { A_ ## reg = (addr) };                                          \
 216     enum { R_ ## reg = (addr) / 4 };
 217
 218 /* Define SHIFT, LENGTH and MASK constants for a field within a register */
 219
 220 /* This macro will define FOO_BAR_MASK, FOO_BAR_SHIFT and FOO_BAR_LENGTH
 221  * constants for field BAR in register FOO.
 222  */
 223 #define FIELD(reg, field, shift, length)                                  \
 224     enum { R_ ## reg ## _ ## field ## _SHIFT = (shift)};                  \
 225     enum { R_ ## reg ## _ ## field ## _LENGTH = (length)};                \
 226     enum { R_ ## reg ## _ ## field ## _MASK =                             \
 227                                         MAKE_64BIT_MASK(shift, length)};
 228
 229 /* Extract a field from a register */
 230 #define FIELD_EX32(storage, reg, field)                                   \
 231     extract32((storage), R_ ## reg ## _ ## field ## _SHIFT,               \
 232               R_ ## reg ## _ ## field ## _LENGTH)
 233
 234 /* Extract a field from an array of registers */
 235 #define ARRAY_FIELD_EX32(regs, reg, field)                                \
 236     FIELD_EX32((regs)[R_ ## reg], reg, field)
 237
 238 /* Deposit a register field.
 239  * Assigning values larger then the target field will result in
 240  * compilation warnings.
 241  */
 242 #define FIELD_DP32(storage, reg, field, val) ({                           \
 243     struct {                                                              \
 244         unsigned int v:R_ ## reg ## _ ## field ## _LENGTH;                \
 245     } v = { .v = val };                                                   \
 246     uint32_t d;                                                           \
 247     d = deposit32((storage), R_ ## reg ## _ ## field ## _SHIFT,           \
 248                   R_ ## reg ## _ ## field ## _LENGTH, v.v);               \
 249     d; })
 250
 251 /* Deposit a field to array of registers.  */
 252 #define ARRAY_FIELD_DP32(regs, reg, field, val)                           \
 253     (regs)[R_ ## reg] = FIELD_DP32((regs)[R_ ## reg], reg, field, val);
 254
 255 #endif