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 "exec/memory.h"
  15
  16 typedef struct RegisterInfo RegisterInfo;
  17 typedef struct RegisterAccessInfo RegisterAccessInfo;
  18 typedef struct RegisterInfoArray RegisterInfoArray;
  19
  20 /**
  21  * Access description for a register that is part of guest accessible device
  22  * state.
  23  *
  24  * @name: String name of the register
  25  * @ro: whether or not the bit is read-only
  26  * @w1c: bits with the common write 1 to clear semantic.
  27  * @reset: reset value.
  28  * @cor: Bits that are clear on read
  29  * @rsvd: Bits that are reserved and should not be changed
  30  *
  31  * @pre_write: Pre write callback. Passed the value that's to be written,
  32  * immediately before the actual write. The returned value is what is written,
  33  * giving the handler a chance to modify the written value.
  34  * @post_write: Post write callback. Passed the written value. Most write side
  35  * effects should be implemented here.
  36  *
  37  * @post_read: Post read callback. Passes the value that is about to be returned
  38  * for a read. The return value from this function is what is ultimately read,
  39  * allowing this function to modify the value before return to the client.
  40  */
  41
  42 struct RegisterAccessInfo {
  43     const char *name;
  44     uint64_t ro;
  45     uint64_t w1c;
  46     uint64_t reset;
  47     uint64_t cor;
  48     uint64_t rsvd;
  49     uint64_t unimp;
  50
  51     uint64_t (*pre_write)(RegisterInfo *reg, uint64_t val);
  52     void (*post_write)(RegisterInfo *reg, uint64_t val);
  53
  54     uint64_t (*post_read)(RegisterInfo *reg, uint64_t val);
  55
  56     hwaddr addr;
  57 };
  58
  59 /**
  60  * A register that is part of guest accessible state
  61  * @data: pointer to the register data. Will be cast
  62  * to the relevant uint type depending on data_size.
  63  * @data_size: Size of the register in bytes. Must be
  64  * 1, 2, 4 or 8
  65  *
  66  * @access: Access description of this register
  67  *
  68  * @debug: Whether or not verbose debug is enabled
  69  * @prefix: String prefix for log and debug messages
  70  *
  71  * @opaque: Opaque data for the register
  72  */
  73
  74 struct RegisterInfo {
  75     /* <public> */
  76     void *data;
  77     int data_size;
  78
  79     const RegisterAccessInfo *access;
  80
  81     void *opaque;
  82 };
  83
  84 /**
  85  * This structure is used to group all of the individual registers which are
  86  * modeled using the RegisterInfo structure.
  87  *
  88  * @r is an aray containing of all the relevent RegisterInfo structures.
  89  *
  90  * @num_elements is the number of elements in the array r
  91  *
  92  * @mem: optional Memory region for the register
  93  */
  94
  95 struct RegisterInfoArray {
  96     int num_elements;
  97     RegisterInfo **r;
  98
  99     bool debug;
 100     const char *prefix;
 101 };
 102
 103 /**
 104  * write a value to a register, subject to its restrictions
 105  * @reg: register to write to
 106  * @val: value to write
 107  * @we: write enable mask
 108  * @prefix: The device prefix that should be printed before the register name
 109  * @debug: Should the write operation debug information be printed?
 110  */
 111
 112 void register_write(RegisterInfo *reg, uint64_t val, uint64_t we,
 113                     const char *prefix, bool debug);
 114
 115 /**
 116  * read a value from a register, subject to its restrictions
 117  * @reg: register to read from
 118  * @re: read enable mask
 119  * @prefix: The device prefix that should be printed before the register name
 120  * @debug: Should the read operation debug information be printed?
 121  * returns: value read
 122  */
 123
 124 uint64_t register_read(RegisterInfo *reg, uint64_t re, const char* prefix,
 125                        bool debug);
 126
 127 /**
 128  * reset a register
 129  * @reg: register to reset
 130  */
 131
 132 void register_reset(RegisterInfo *reg);
 133
 134 /**
 135  * Memory API MMIO write handler that will write to a Register API register.
 136  * @opaque: RegisterInfo to write to
 137  * @addr: Address to write
 138  * @value: Value to write
 139  * @size: Number of bytes to write
 140  */
 141
 142 void register_write_memory(void *opaque, hwaddr addr, uint64_t value,
 143                            unsigned size);
 144
 145 /**
 146  * Memory API MMIO read handler that will read from a Register API register.
 147  * @opaque: RegisterInfo to read from
 148  * @addr: Address to read
 149  * @size: Number of bytes to read
 150  * returns: Value read from register
 151  */
 152
 153 uint64_t register_read_memory(void *opaque, hwaddr addr, unsigned size);
 154
 155 #endif