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 #include "hw/registerfields.h"
  17
  18 typedef struct RegisterInfo RegisterInfo;
  19 typedef struct RegisterAccessInfo RegisterAccessInfo;
  20 typedef struct RegisterInfoArray RegisterInfoArray;
  21
  22 /**
  23  * Access description for a register that is part of guest accessible device
  24  * state.
  25  *
  26  * @name: String name of the register
  27  * @ro: whether or not the bit is read-only
  28  * @w1c: bits with the common write 1 to clear semantic.
  29  * @reset: reset value.
  30  * @cor: Bits that are clear on read
  31  * @rsvd: Bits that are reserved and should not be changed
  32  *
  33  * @pre_write: Pre write callback. Passed the value that's to be written,
  34  * immediately before the actual write. The returned value is what is written,
  35  * giving the handler a chance to modify the written value.
  36  * @post_write: Post write callback. Passed the written value. Most write side
  37  * effects should be implemented here.
  38  *
  39  * @post_read: Post read callback. Passes the value that is about to be returned
  40  * for a read. The return value from this function is what is ultimately read,
  41  * allowing this function to modify the value before return to the client.
  42  */
  43
  44 struct RegisterAccessInfo {
  45     const char *name;
  46     uint64_t ro;
  47     uint64_t w1c;
  48     uint64_t reset;
  49     uint64_t cor;
  50     uint64_t rsvd;
  51     uint64_t unimp;
  52
  53     uint64_t (*pre_write)(RegisterInfo *reg, uint64_t val);
  54     void (*post_write)(RegisterInfo *reg, uint64_t val);
  55
  56     uint64_t (*post_read)(RegisterInfo *reg, uint64_t val);
  57
  58     hwaddr addr;
  59 };
  60
  61 /**
  62  * A register that is part of guest accessible state
  63  * @data: pointer to the register data. Will be cast
  64  * to the relevant uint type depending on data_size.
  65  * @data_size: Size of the register in bytes. Must be
  66  * 1, 2, 4 or 8
  67  *
  68  * @access: Access description of this register
  69  *
  70  * @debug: Whether or not verbose debug is enabled
  71  * @prefix: String prefix for log and debug messages
  72  *
  73  * @opaque: Opaque data for the register
  74  */
  75
  76 struct RegisterInfo {
  77     /* <private> */
  78     DeviceState parent_obj;
  79
  80     /* <public> */
  81     void *data;
  82     int data_size;
  83
  84     const RegisterAccessInfo *access;
  85
  86     void *opaque;
  87 };
  88
  89 #define TYPE_REGISTER "qemu,register"
  90 #define REGISTER(obj) OBJECT_CHECK(RegisterInfo, (obj), TYPE_REGISTER)
  91
  92 /**
  93  * This structure is used to group all of the individual registers which are
  94  * modeled using the RegisterInfo structure.
  95  *
  96  * @r is an array containing of all the relevant RegisterInfo structures.
  97  *
  98  * @num_elements is the number of elements in the array r
  99  *
 100  * @mem: optional Memory region for the register
 101  */
 102
 103 struct RegisterInfoArray {
 104     MemoryRegion mem;
 105
 106     int num_elements;
 107     RegisterInfo **r;
 108
 109     bool debug;
 110     const char *prefix;
 111 };
 112
 113 /**
 114  * write a value to a register, subject to its restrictions
 115  * @reg: register to write to
 116  * @val: value to write
 117  * @we: write enable mask
 118  * @prefix: The device prefix that should be printed before the register name
 119  * @debug: Should the write operation debug information be printed?
 120  */
 121
 122 void register_write(RegisterInfo *reg, uint64_t val, uint64_t we,
 123                     const char *prefix, bool debug);
 124
 125 /**
 126  * read a value from a register, subject to its restrictions
 127  * @reg: register to read from
 128  * @re: read enable mask
 129  * @prefix: The device prefix that should be printed before the register name
 130  * @debug: Should the read operation debug information be printed?
 131  * returns: value read
 132  */
 133
 134 uint64_t register_read(RegisterInfo *reg, uint64_t re, const char* prefix,
 135                        bool debug);
 136
 137 /**
 138  * reset a register
 139  * @reg: register to reset
 140  */
 141
 142 void register_reset(RegisterInfo *reg);
 143
 144 /**
 145  * Initialize a register.
 146  * @reg: Register to initialize
 147  */
 148
 149 void register_init(RegisterInfo *reg);
 150
 151 /**
 152  * Memory API MMIO write handler that will write to a Register API register.
 153  * @opaque: RegisterInfo to write to
 154  * @addr: Address to write
 155  * @value: Value to write
 156  * @size: Number of bytes to write
 157  */
 158
 159 void register_write_memory(void *opaque, hwaddr addr, uint64_t value,
 160                            unsigned size);
 161
 162 /**
 163  * Memory API MMIO read handler that will read from a Register API register.
 164  * @opaque: RegisterInfo to read from
 165  * @addr: Address to read
 166  * @size: Number of bytes to read
 167  * returns: Value read from register
 168  */
 169
 170 uint64_t register_read_memory(void *opaque, hwaddr addr, unsigned size);
 171
 172 /**
 173  * Init a block of registers into a container MemoryRegion. A
 174  * number of constant register definitions are parsed to create a corresponding
 175  * array of RegisterInfo's.
 176  *
 177  * @owner: device owning the registers
 178  * @rae: Register definitions to init
 179  * @num: number of registers to init (length of @rae)
 180  * @ri: Register array to init, must already be allocated
 181  * @data: Array to use for register data, must already be allocated
 182  * @ops: Memory region ops to access registers.
 183  * @debug enabled: turn on/off verbose debug information
 184  * returns: A structure containing all of the registers and an initialized
 185  *          memory region (r_array->mem) the caller should add to a container.
 186  */
 187
 188 RegisterInfoArray *register_init_block32(DeviceState *owner,
 189                                          const RegisterAccessInfo *rae,
 190                                          int num, RegisterInfo *ri,
 191                                          uint32_t *data,
 192                                          const MemoryRegionOps *ops,
 193                                          bool debug_enabled,
 194                                          uint64_t memory_size);
 195
 196 /**
 197  * This function should be called to cleanup the registers that were initialized
 198  * when calling register_init_block32(). This function should only be called
 199  * from the device's instance_finalize function.
 200  *
 201  * Any memory operations that the device performed that require cleanup (such
 202  * as creating subregions) need to be called before calling this function.
 203  *
 204  * @r_array: A structure containing all of the registers, as returned by
 205  *           register_init_block32()
 206  */
 207
 208 void register_finalize_block(RegisterInfoArray *r_array);
 209
 210 #endif