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