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