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 222