ppc/pnv: Add a HIOMAP erase command
[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
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 * @memory_size: Size of the memory region
185 * returns: A structure containing all of the registers and an initialized
186 * memory region (r_array->mem) the caller should add to a container.
187 */
188
189 RegisterInfoArray *register_init_block8(DeviceState *owner,
190 const RegisterAccessInfo *rae,
191 int num, RegisterInfo *ri,
192 uint8_t *data,
193 const MemoryRegionOps *ops,
194 bool debug_enabled,
195 uint64_t memory_size);
196
197 RegisterInfoArray *register_init_block32(DeviceState *owner,
198 const RegisterAccessInfo *rae,
199 int num, RegisterInfo *ri,
200 uint32_t *data,
201 const MemoryRegionOps *ops,
202 bool debug_enabled,
203 uint64_t memory_size);
204
205 /**
206 * This function should be called to cleanup the registers that were initialized
207 * when calling register_init_block32(). This function should only be called
208 * from the device's instance_finalize function.
209 *
210 * Any memory operations that the device performed that require cleanup (such
211 * as creating subregions) need to be called before calling this function.
212 *
213 * @r_array: A structure containing all of the registers, as returned by
214 * register_init_block32()
215 */
216
217 void register_finalize_block(RegisterInfoArray *r_array);
218
219 #endif