block/export: Add query-block-exports
[qemu.git] / include / hw / register.h
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