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 #define REGISTER(obj) OBJECT_CHECK(RegisterInfo, (obj), TYPE_REGISTER) 92 93 /** 94 * This structure is used to group all of the individual registers which are 95 * modeled using the RegisterInfo structure. 96 * 97 * @r is an array containing of all the relevant RegisterInfo structures. 98 * 99 * @num_elements is the number of elements in the array r 100 * 101 * @mem: optional Memory region for the register 102 */ 103 104 struct RegisterInfoArray { 105 MemoryRegion mem; 106 107 int num_elements; 108 RegisterInfo **r; 109 110 bool debug; 111 const char *prefix; 112 }; 113 114 /** 115 * write a value to a register, subject to its restrictions 116 * @reg: register to write to 117 * @val: value to write 118 * @we: write enable mask 119 * @prefix: The device prefix that should be printed before the register name 120 * @debug: Should the write operation debug information be printed? 121 */ 122 123 void register_write(RegisterInfo *reg, uint64_t val, uint64_t we, 124 const char *prefix, bool debug); 125 126 /** 127 * read a value from a register, subject to its restrictions 128 * @reg: register to read from 129 * @re: read enable mask 130 * @prefix: The device prefix that should be printed before the register name 131 * @debug: Should the read operation debug information be printed? 132 * returns: value read 133 */ 134 135 uint64_t register_read(RegisterInfo *reg, uint64_t re, const char* prefix, 136 bool debug); 137 138 /** 139 * Resets a register. This will also call the post_write hook if it exists. 140 * @reg: The register to reset. 141 */ 142 143 void register_reset(RegisterInfo *reg); 144 145 /** 146 * Initialize a register. 147 * @reg: Register to initialize 148 */ 149 150 void register_init(RegisterInfo *reg); 151 152 /** 153 * Memory API MMIO write handler that will write to a Register API register. 154 * @opaque: RegisterInfo to write to 155 * @addr: Address to write 156 * @value: Value to write 157 * @size: Number of bytes to write 158 */ 159 160 void register_write_memory(void *opaque, hwaddr addr, uint64_t value, 161 unsigned size); 162 163 /** 164 * Memory API MMIO read handler that will read from a Register API register. 165 * @opaque: RegisterInfo to read from 166 * @addr: Address to read 167 * @size: Number of bytes to read 168 * returns: Value read from register 169 */ 170 171 uint64_t register_read_memory(void *opaque, hwaddr addr, unsigned size); 172 173 /** 174 * Init a block of registers into a container MemoryRegion. A 175 * number of constant register definitions are parsed to create a corresponding 176 * array of RegisterInfo's. 177 * 178 * @owner: device owning the registers 179 * @rae: Register definitions to init 180 * @num: number of registers to init (length of @rae) 181 * @ri: Register array to init, must already be allocated 182 * @data: Array to use for register data, must already be allocated 183 * @ops: Memory region ops to access registers. 184 * @debug enabled: turn on/off verbose debug information 185 * @memory_size: Size of the memory region 186 * returns: A structure containing all of the registers and an initialized 187 * memory region (r_array->mem) the caller should add to a container. 188 */ 189 190 RegisterInfoArray *register_init_block8(DeviceState *owner, 191 const RegisterAccessInfo *rae, 192 int num, RegisterInfo *ri, 193 uint8_t *data, 194 const MemoryRegionOps *ops, 195 bool debug_enabled, 196 uint64_t memory_size); 197 198 RegisterInfoArray *register_init_block32(DeviceState *owner, 199 const RegisterAccessInfo *rae, 200 int num, RegisterInfo *ri, 201 uint32_t *data, 202 const MemoryRegionOps *ops, 203 bool debug_enabled, 204 uint64_t memory_size); 205 206 /** 207 * This function should be called to cleanup the registers that were initialized 208 * when calling register_init_block32(). This function should only be called 209 * from the device's instance_finalize function. 210 * 211 * Any memory operations that the device performed that require cleanup (such 212 * as creating subregions) need to be called before calling this function. 213 * 214 * @r_array: A structure containing all of the registers, as returned by 215 * register_init_block32() 216 */ 217 218 void register_finalize_block(RegisterInfoArray *r_array); 219 220 #endif 221