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 17typedef struct RegisterInfo RegisterInfo; 18typedef struct RegisterAccessInfo RegisterAccessInfo; 19typedef 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 43struct 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 75struct 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 102struct 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 121void 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 133uint64_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 141void register_reset(RegisterInfo *reg); 142 143/** 144 * Initialize a register. 145 * @reg: Register to initialize 146 */ 147 148void 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 158void 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 169uint64_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 187RegisterInfoArray *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 207void 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 256