| 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/core/qdev.h" |
| 15 | #include "system/memory.h" |
| 16 | #include "hw/core/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 | void *data; |
| 79 | int data_size; |
| 80 | |
| 81 | const RegisterAccessInfo *access; |
| 82 | |
| 83 | void *opaque; |
| 84 | }; |
| 85 | |
| 86 | #define TYPE_REGISTER_ARRAY "qemu-register-array" |
| 87 | OBJECT_DECLARE_SIMPLE_TYPE(RegisterInfoArray, REGISTER_ARRAY) |
| 88 | |
| 89 | /** |
| 90 | * This structure is used to group all of the individual registers which are |
| 91 | * modeled using the RegisterInfo structure. |
| 92 | * |
| 93 | * @r is an array containing of all the relevant RegisterInfo structures. |
| 94 | * |
| 95 | * @num_elements is the number of elements in the array r |
| 96 | * |
| 97 | * @mem: optional Memory region for the register |
| 98 | */ |
| 99 | |
| 100 | struct RegisterInfoArray { |
| 101 | Object parent_obj; |
| 102 | |
| 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 | |
| 121 | void 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 | |
| 133 | uint64_t register_read(RegisterInfo *reg, uint64_t re, const char* prefix, |
| 134 | bool debug); |
| 135 | |
| 136 | /** |
| 137 | * Resets a register. This will also call the post_write hook if it exists. |
| 138 | * @reg: The register to reset. |
| 139 | */ |
| 140 | |
| 141 | void register_reset(RegisterInfo *reg); |
| 142 | |
| 143 | /** |
| 144 | * Initialize a register. |
| 145 | * @reg: Register to initialize |
| 146 | */ |
| 147 | |
| 148 | void 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 | |
| 158 | void 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 | |
| 169 | uint64_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 | * @memory_size: Size of the memory region |
| 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_block8(DeviceState *owner, |
| 189 | const RegisterAccessInfo *rae, |
| 190 | int num, RegisterInfo *ri, |
| 191 | uint8_t *data, |
| 192 | const MemoryRegionOps *ops, |
| 193 | bool debug_enabled, |
| 194 | uint64_t memory_size); |
| 195 | |
| 196 | RegisterInfoArray *register_init_block32(DeviceState *owner, |
| 197 | const RegisterAccessInfo *rae, |
| 198 | int num, RegisterInfo *ri, |
| 199 | uint32_t *data, |
| 200 | const MemoryRegionOps *ops, |
| 201 | bool debug_enabled, |
| 202 | uint64_t memory_size); |
| 203 | |
| 204 | RegisterInfoArray *register_init_block64(DeviceState *owner, |
| 205 | const RegisterAccessInfo *rae, |
| 206 | int num, RegisterInfo *ri, |
| 207 | uint64_t *data, |
| 208 | const MemoryRegionOps *ops, |
| 209 | bool debug_enabled, |
| 210 | uint64_t memory_size); |
| 211 | |
| 212 | /** |
| 213 | * register_array_get_owner |
| 214 | * |
| 215 | * Retrieve the device owning the register info array @reg_array. |
| 216 | * |
| 217 | * @reg_array The register info array to retrieve the owner from |
| 218 | * |
| 219 | * Returns: the device owning @reg_array |
| 220 | */ |
| 221 | DeviceState *register_array_get_owner(const RegisterInfoArray *reg_array); |
| 222 | |
| 223 | #endif |