[qemu.git] / include / hw / register.h

/*
 * Register Definition API
 *
 * Copyright (c) 2016 Xilinx Inc.
 * Copyright (c) 2013 Peter Crosthwaite <[email protected]>
 *
 * This work is licensed under the terms of the GNU GPL, version 2.  See
 * the COPYING file in the top-level directory.
 */

#ifndef REGISTER_H
#define REGISTER_H

#include "hw/qdev-core.h"
#include "exec/memory.h"

typedef struct RegisterInfo RegisterInfo;
typedef struct RegisterAccessInfo RegisterAccessInfo;
typedef struct RegisterInfoArray RegisterInfoArray;

/**
 * Access description for a register that is part of guest accessible device
 * state.
 *
 * @name: String name of the register
 * @ro: whether or not the bit is read-only
 * @w1c: bits with the common write 1 to clear semantic.
 * @reset: reset value.
 * @cor: Bits that are clear on read
 * @rsvd: Bits that are reserved and should not be changed
 *
 * @pre_write: Pre write callback. Passed the value that's to be written,
 * immediately before the actual write. The returned value is what is written,
 * giving the handler a chance to modify the written value.
 * @post_write: Post write callback. Passed the written value. Most write side
 * effects should be implemented here.
 *
 * @post_read: Post read callback. Passes the value that is about to be returned
 * for a read. The return value from this function is what is ultimately read,
 * allowing this function to modify the value before return to the client.
 */

struct RegisterAccessInfo {
    const char *name;
    uint64_t ro;
    uint64_t w1c;
    uint64_t reset;
    uint64_t cor;
    uint64_t rsvd;
    uint64_t unimp;

    uint64_t (*pre_write)(RegisterInfo *reg, uint64_t val);
    void (*post_write)(RegisterInfo *reg, uint64_t val);

    uint64_t (*post_read)(RegisterInfo *reg, uint64_t val);

    hwaddr addr;
};

/**
 * A register that is part of guest accessible state
 * @data: pointer to the register data. Will be cast
 * to the relevant uint type depending on data_size.
 * @data_size: Size of the register in bytes. Must be
 * 1, 2, 4 or 8
 *
 * @access: Access description of this register
 *
 * @debug: Whether or not verbose debug is enabled
 * @prefix: String prefix for log and debug messages
 *
 * @opaque: Opaque data for the register
 */

struct RegisterInfo {
    /* <private> */
    DeviceState parent_obj;

    /* <public> */
    void *data;
    int data_size;

    const RegisterAccessInfo *access;

    void *opaque;
};

#define TYPE_REGISTER "qemu,register"
#define REGISTER(obj) OBJECT_CHECK(RegisterInfo, (obj), TYPE_REGISTER)

/**
 * This structure is used to group all of the individual registers which are
 * modeled using the RegisterInfo structure.
 *
 * @r is an aray containing of all the relevent RegisterInfo structures.
 *
 * @num_elements is the number of elements in the array r
 *
 * @mem: optional Memory region for the register
 */

struct RegisterInfoArray {
    MemoryRegion mem;

    int num_elements;
    RegisterInfo **r;

    bool debug;
    const char *prefix;
};

/**
 * write a value to a register, subject to its restrictions
 * @reg: register to write to
 * @val: value to write
 * @we: write enable mask
 * @prefix: The device prefix that should be printed before the register name
 * @debug: Should the write operation debug information be printed?
 */

void register_write(RegisterInfo *reg, uint64_t val, uint64_t we,
                    const char *prefix, bool debug);

/**
 * read a value from a register, subject to its restrictions
 * @reg: register to read from
 * @re: read enable mask
 * @prefix: The device prefix that should be printed before the register name
 * @debug: Should the read operation debug information be printed?
 * returns: value read
 */

uint64_t register_read(RegisterInfo *reg, uint64_t re, const char* prefix,
                       bool debug);

/**
 * reset a register
 * @reg: register to reset
 */

void register_reset(RegisterInfo *reg);

/**
 * Initialize a register.
 * @reg: Register to initialize
 */

void register_init(RegisterInfo *reg);

/**
 * Memory API MMIO write handler that will write to a Register API register.
 * @opaque: RegisterInfo to write to
 * @addr: Address to write
 * @value: Value to write
 * @size: Number of bytes to write
 */

void register_write_memory(void *opaque, hwaddr addr, uint64_t value,
                           unsigned size);

/**
 * Memory API MMIO read handler that will read from a Register API register.
 * @opaque: RegisterInfo to read from
 * @addr: Address to read
 * @size: Number of bytes to read
 * returns: Value read from register
 */

uint64_t register_read_memory(void *opaque, hwaddr addr, unsigned size);

/**
 * Init a block of registers into a container MemoryRegion. A
 * number of constant register definitions are parsed to create a corresponding
 * array of RegisterInfo's.
 *
 * @owner: device owning the registers
 * @rae: Register definitions to init
 * @num: number of registers to init (length of @rae)
 * @ri: Register array to init, must already be allocated
 * @data: Array to use for register data, must already be allocated
 * @ops: Memory region ops to access registers.
 * @debug enabled: turn on/off verbose debug information
 * returns: A structure containing all of the registers and an initialized
 *          memory region (r_array->mem) the caller should add to a container.
 */

RegisterInfoArray *register_init_block32(DeviceState *owner,
                                         const RegisterAccessInfo *rae,
                                         int num, RegisterInfo *ri,
                                         uint32_t *data,
                                         const MemoryRegionOps *ops,
                                         bool debug_enabled,
                                         uint64_t memory_size);

/**
 * This function should be called to cleanup the registers that were initialized
 * when calling register_init_block32(). This function should only be called
 * from the device's instance_finalize function.
 *
 * Any memory operations that the device performed that require cleanup (such
 * as creating subregions) need to be called before calling this function.
 *
 * @r_array: A structure containing all of the registers, as returned by
 *           register_init_block32()
 */

void register_finalize_block(RegisterInfoArray *r_array);

/* Define constants for a 32 bit register */

/* This macro will define A_FOO, for the byte address of a register
 * as well as R_FOO for the uint32_t[] register number (A_FOO / 4).
 */
#define REG32(reg, addr)                                                  \
    enum { A_ ## reg = (addr) };                                          \
    enum { R_ ## reg = (addr) / 4 };

/* Define SHIFT, LENGTH and MASK constants for a field within a register */

/* This macro will define FOO_BAR_MASK, FOO_BAR_SHIFT and FOO_BAR_LENGTH 
 * constants for field BAR in register FOO.
 */
#define FIELD(reg, field, shift, length)                                  \
    enum { R_ ## reg ## _ ## field ## _SHIFT = (shift)};                  \
    enum { R_ ## reg ## _ ## field ## _LENGTH = (length)};                \
    enum { R_ ## reg ## _ ## field ## _MASK =                             \
                                        MAKE_64BIT_MASK(shift, length)};

/* Extract a field from a register */
#define FIELD_EX32(storage, reg, field)                                   \
    extract32((storage), R_ ## reg ## _ ## field ## _SHIFT,               \
              R_ ## reg ## _ ## field ## _LENGTH)

/* Extract a field from an array of registers */
#define ARRAY_FIELD_EX32(regs, reg, field)                                \
    FIELD_EX32((regs)[R_ ## reg], reg, field)

/* Deposit a register field.
 * Assigning values larger then the target field will result in
 * compilation warnings.
 */
#define FIELD_DP32(storage, reg, field, val) ({                           \
    struct {                                                              \
        unsigned int v:R_ ## reg ## _ ## field ## _LENGTH;                \
    } v = { .v = val };                                                   \
    uint32_t d;                                                           \
    d = deposit32((storage), R_ ## reg ## _ ## field ## _SHIFT,           \
                  R_ ## reg ## _ ## field ## _LENGTH, v.v);               \
    d; })

/* Deposit a field to array of registers.  */
#define ARRAY_FIELD_DP32(regs, reg, field, val)                           \
    (regs)[R_ ## reg] = FIELD_DP32((regs)[R_ ## reg], reg, field, val);

#endif
Commit	Line	Data
1599121b AF	1	/*
	2	* Register Definition API
	3	*
	4	* Copyright (c) 2016 Xilinx Inc.
	5	* Copyright (c) 2013 Peter Crosthwaite <[email protected]>
	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
49e14ddb	14	#include "hw/qdev-core.h"
1599121b AF	15	#include "exec/memory.h"
	16
	17	typedef struct RegisterInfo RegisterInfo;
	18	typedef struct RegisterAccessInfo RegisterAccessInfo;
0b73c9bb	19	typedef struct RegisterInfoArray RegisterInfoArray;
1599121b AF	20
	21	/**
	22	* Access description for a register that is part of guest accessible device
	23	* state.
	24	*
	25	* @name: String name of the register
	26	* @ro: whether or not the bit is read-only
	27	* @w1c: bits with the common write 1 to clear semantic.
	28	* @reset: reset value.
	29	* @cor: Bits that are clear on read
	30	* @rsvd: Bits that are reserved and should not be changed
	31	*
	32	* @pre_write: Pre write callback. Passed the value that's to be written,
	33	* immediately before the actual write. The returned value is what is written,
	34	* giving the handler a chance to modify the written value.
	35	* @post_write: Post write callback. Passed the written value. Most write side
	36	* effects should be implemented here.
	37	*
	38	* @post_read: Post read callback. Passes the value that is about to be returned
	39	* for a read. The return value from this function is what is ultimately read,
	40	* allowing this function to modify the value before return to the client.
	41	*/
	42
	43	struct RegisterAccessInfo {
	44	const char *name;
	45	uint64_t ro;
	46	uint64_t w1c;
	47	uint64_t reset;
	48	uint64_t cor;
	49	uint64_t rsvd;
	50	uint64_t unimp;
	51
	52	uint64_t (pre_write)(RegisterInfo reg, uint64_t val);
	53	void (post_write)(RegisterInfo reg, uint64_t val);
	54
	55	uint64_t (post_read)(RegisterInfo reg, uint64_t val);
0b73c9bb AF	56
0b73c9bb AF	57	hwaddr addr;
1599121b AF	58	};
	59
	60	/**
	61	* A register that is part of guest accessible state
	62	* @data: pointer to the register data. Will be cast
	63	* to the relevant uint type depending on data_size.
	64	* @data_size: Size of the register in bytes. Must be
	65	* 1, 2, 4 or 8
	66	*
	67	* @access: Access description of this register
	68	*
	69	* @debug: Whether or not verbose debug is enabled
	70	* @prefix: String prefix for log and debug messages
	71	*
	72	* @opaque: Opaque data for the register
	73	*/
	74
	75	struct RegisterInfo {
49e14ddb PC	76	/* <private> */
	77	DeviceState parent_obj;
	78
1599121b AF	79	/* <public> */
	80	void *data;
	81	int data_size;
	82
	83	const RegisterAccessInfo *access;
	84
	85	void *opaque;
	86	};
	87
49e14ddb PC	88	#define TYPE_REGISTER "qemu,register"
	89	#define REGISTER(obj) OBJECT_CHECK(RegisterInfo, (obj), TYPE_REGISTER)
	90
0b73c9bb AF	91	/**
	92	* This structure is used to group all of the individual registers which are
	93	* modeled using the RegisterInfo structure.
	94	*
	95	* @r is an aray containing of all the relevent RegisterInfo structures.
	96	*
	97	* @num_elements is the number of elements in the array r
	98	*
	99	* @mem: optional Memory region for the register
	100	*/
	101
	102	struct RegisterInfoArray {
a7422959 PC	103	MemoryRegion mem;
a7422959 PC	104
0b73c9bb AF	105	int num_elements;
	106	RegisterInfo **r;
	107
	108	bool debug;
	109	const char *prefix;
	110	};
	111
1599121b AF	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	* reset a register
	138	* @reg: register to reset
	139	*/
	140
	141	void register_reset(RegisterInfo *reg);
	142
49e14ddb PC	143	/**
	144	* Initialize a register.
	145	* @reg: Register to initialize
	146	*/
	147
	148	void register_init(RegisterInfo *reg);
	149
0b73c9bb AF	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
a7422959 PC	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	* returns: A structure containing all of the registers and an initialized
	184	* memory region (r_array->mem) the caller should add to a container.
	185	*/
	186
	187	RegisterInfoArray register_init_block32(DeviceState owner,
	188	const RegisterAccessInfo *rae,
	189	int num, RegisterInfo *ri,
	190	uint32_t *data,
	191	const MemoryRegionOps *ops,
	192	bool debug_enabled,
	193	uint64_t memory_size);
	194
	195	/**
	196	* This function should be called to cleanup the registers that were initialized
	197	* when calling register_init_block32(). This function should only be called
	198	* from the device's instance_finalize function.
	199	*
	200	* Any memory operations that the device performed that require cleanup (such
	201	* as creating subregions) need to be called before calling this function.
	202	*
	203	* @r_array: A structure containing all of the registers, as returned by
	204	* register_init_block32()
	205	*/
	206
	207	void register_finalize_block(RegisterInfoArray *r_array);
	208
68420459 PC	209	/* Define constants for a 32 bit register */
	210
	211	/* This macro will define A_FOO, for the byte address of a register
	212	* as well as R_FOO for the uint32_t[] register number (A_FOO / 4).
	213	*/
	214	#define REG32(reg, addr) \
	215	enum { A_ ## reg = (addr) }; \
	216	enum { R_ ## reg = (addr) / 4 };
	217
	218	/* Define SHIFT, LENGTH and MASK constants for a field within a register */
	219
	220	/* This macro will define FOO_BAR_MASK, FOO_BAR_SHIFT and FOO_BAR_LENGTH
	221	* constants for field BAR in register FOO.
	222	*/
	223	#define FIELD(reg, field, shift, length) \
	224	enum { R_ ## reg ## _ ## field ## _SHIFT = (shift)}; \
	225	enum { R_ ## reg ## _ ## field ## _LENGTH = (length)}; \
	226	enum { R_ ## reg ## _ ## field ## _MASK = \
	227	MAKE_64BIT_MASK(shift, length)};
	228
	229	/* Extract a field from a register */
	230	#define FIELD_EX32(storage, reg, field) \
	231	extract32((storage), R_ ## reg ## _ ## field ## _SHIFT, \
	232	R_ ## reg ## _ ## field ## _LENGTH)
	233
	234	/* Extract a field from an array of registers */
	235	#define ARRAY_FIELD_EX32(regs, reg, field) \
	236	FIELD_EX32((regs)[R_ ## reg], reg, field)
	237
	238	/* Deposit a register field.
	239	* Assigning values larger then the target field will result in
	240	* compilation warnings.
	241	*/
	242	#define FIELD_DP32(storage, reg, field, val) ({ \
	243	struct { \
	244	unsigned int v:R_ ## reg ## _ ## field ## _LENGTH; \
	245	} v = { .v = val }; \
	246	uint32_t d; \
	247	d = deposit32((storage), R_ ## reg ## _ ## field ## _SHIFT, \
	248	R_ ## reg ## _ ## field ## _LENGTH, v.v); \
	249	d; })
	250
	251	/* Deposit a field to array of registers. */
	252	#define ARRAY_FIELD_DP32(regs, reg, field, val) \
	253	(regs)[R_ ## reg] = FIELD_DP32((regs)[R_ ## reg], reg, field, val);
	254
1599121b	255	#endif