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
18typedef struct RegisterInfo RegisterInfo;
19typedef struct RegisterAccessInfo RegisterAccessInfo;
20typedef 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
44struct 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
76struct 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
103struct 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
122void 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
134uint64_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
142void register_reset(RegisterInfo *reg);
143
144/**
145 * Initialize a register.
146 * @reg: Register to initialize
147 */
148
149void 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
159void 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
170uint64_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
188RegisterInfoArray *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
208void register_finalize_block(RegisterInfoArray *r_array);
209
210#endif
211