| 1 | /* This file is part of the program psim. |
| 2 | |
| 3 | Copyright (C) 1994-1996, Andrew Cagney <cagney@highland.com.au> |
| 4 | |
| 5 | This program is free software; you can redistribute it and/or modify |
| 6 | it under the terms of the GNU General Public License as published by |
| 7 | the Free Software Foundation; either version 3 of the License, or |
| 8 | (at your option) any later version. |
| 9 | |
| 10 | This program is distributed in the hope that it will be useful, |
| 11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 13 | GNU General Public License for more details. |
| 14 | |
| 15 | You should have received a copy of the GNU General Public License |
| 16 | along with this program; if not, see <http://www.gnu.org/licenses/>. |
| 17 | |
| 18 | */ |
| 19 | |
| 20 | |
| 21 | #ifndef _CORE_H_ |
| 22 | #define _CORE_H_ |
| 23 | |
| 24 | /* Introduction: |
| 25 | |
| 26 | The core device, positioned at the top of the device tree that |
| 27 | models the architecure being simulated, acts as an interface |
| 28 | between the processor engines and the modeled devices. |
| 29 | |
| 30 | On the one side the processor engines issue read and write requests |
| 31 | to the core (each request further catagorised as being for an |
| 32 | instruction or data subunit) while on the other side, the core is |
| 33 | receiving address configuration and DMA requests from child |
| 34 | devices. |
| 35 | |
| 36 | In the below a synopsis of the core object and device in PSIM is |
| 37 | given, details of the object can be found in the files |
| 38 | <<corefile.h>> and <<corefile.c>>. |
| 39 | |
| 40 | */ |
| 41 | |
| 42 | /* Core:: |
| 43 | |
| 44 | At the heart of the interface between devices and processor engines |
| 45 | is a single core object. This object, in turn, has two children: |
| 46 | |
| 47 | o a core device which exists in the device tree and provides |
| 48 | an interface to the core object to child devices. |
| 49 | |
| 50 | o a set of access maps which provide an efficient |
| 51 | interface to the core object for the processor engines. |
| 52 | |
| 53 | */ |
| 54 | |
| 55 | /* basic types */ |
| 56 | |
| 57 | typedef struct _core core; |
| 58 | typedef struct _core_map core_map; |
| 59 | |
| 60 | /* constructor */ |
| 61 | |
| 62 | INLINE_CORE\ |
| 63 | (core *) core_create |
| 64 | (void); |
| 65 | |
| 66 | INLINE_CORE\ |
| 67 | (core *) core_from_device |
| 68 | (device *root); |
| 69 | |
| 70 | INLINE_CORE\ |
| 71 | (void) core_init |
| 72 | (core *memory); |
| 73 | |
| 74 | /* Core map management::: |
| 75 | |
| 76 | The core ojbect manages two different types of address maps: |
| 77 | |
| 78 | o raw-memory - the address range can be implemented using |
| 79 | a simple byte array. No device needs to be notifed of |
| 80 | any accesses to the specified memory range. |
| 81 | |
| 82 | o callback - Any access to the specified address range |
| 83 | should be passed on to the associated device. That device |
| 84 | can in turn resolve the access - handling or aborting or |
| 85 | restarting it. |
| 86 | |
| 87 | For callback maps it is possible to further order them by |
| 88 | specifiying specifying a callback level (eg callback + 1). |
| 89 | |
| 90 | When the core is resolving an access it searches each of the maps |
| 91 | in order. First raw-memory and then callback maps (in assending |
| 92 | order of level). This search order makes it possible for latter |
| 93 | maps to overlap earlier ones. For instance, a device that wants to |
| 94 | be notified of all accesses that are not covered by raw-memory maps |
| 95 | could attach its self with an address range of the entire address |
| 96 | space. |
| 97 | |
| 98 | In addition, each attached address map as an associated set of |
| 99 | access attributes (readable, writeable, executable) which are |
| 100 | verified as part of resolving each access. |
| 101 | |
| 102 | */ |
| 103 | |
| 104 | INLINE_CORE\ |
| 105 | (void) core_attach |
| 106 | (core *map, |
| 107 | attach_type attach, |
| 108 | int address_space, |
| 109 | access_type access, |
| 110 | unsigned_word addr, |
| 111 | unsigned nr_bytes, /* host limited */ |
| 112 | device *device); /*callback/default*/ |
| 113 | |
| 114 | /* Bugs::: |
| 115 | |
| 116 | At present there is no method for removing address maps. That will |
| 117 | be implemented in a future release. |
| 118 | |
| 119 | The operation of mapping between an address and its destination |
| 120 | device or memory array is currently implemented using a simple |
| 121 | linked list. The posibility of replacing this list with a more |
| 122 | powerfull data structure exists. |
| 123 | |
| 124 | */ |
| 125 | |
| 126 | |
| 127 | /* Device:: |
| 128 | |
| 129 | The device that corresponds to the core object is described |
| 130 | separatly in the devices section. |
| 131 | |
| 132 | */ |
| 133 | |
| 134 | /* Access maps:: |
| 135 | |
| 136 | Providing an interface between the processor engines and the core |
| 137 | object are the access maps (core_map). Three access maps are |
| 138 | provided, one for each of the possible access requests that can be |
| 139 | generated by a processor. |
| 140 | |
| 141 | o read |
| 142 | |
| 143 | o write |
| 144 | |
| 145 | o execute |
| 146 | |
| 147 | A processor being able to request a read (or write) or write |
| 148 | operation to any of the maps. Those operations can either be |
| 149 | highly efficient (by specifying a specific transfer size) or |
| 150 | generic (specifying a parameterized number of bytes). |
| 151 | |
| 152 | Internally the core object takes the request, determines the |
| 153 | approperiate attached address space that it should handle it passes |
| 154 | it on. |
| 155 | |
| 156 | */ |
| 157 | |
| 158 | INLINE_CORE\ |
| 159 | (core_map *) core_readable |
| 160 | (core *memory); |
| 161 | |
| 162 | INLINE_CORE\ |
| 163 | (core_map *) core_writeable |
| 164 | (core *memory); |
| 165 | |
| 166 | INLINE_CORE\ |
| 167 | (core_map *) core_executable |
| 168 | (core *memory); |
| 169 | |
| 170 | /* Variable sized read/write |
| 171 | |
| 172 | Transfer (zero) a variable size block of data between the host and |
| 173 | target (possibly byte swapping it). Should any problems occure, |
| 174 | the number of bytes actually transfered is returned. */ |
| 175 | |
| 176 | INLINE_CORE\ |
| 177 | (unsigned) core_map_read_buffer |
| 178 | (core_map *map, |
| 179 | void *buffer, |
| 180 | unsigned_word addr, |
| 181 | unsigned nr_bytes); |
| 182 | |
| 183 | INLINE_CORE\ |
| 184 | (unsigned) core_map_write_buffer |
| 185 | (core_map *map, |
| 186 | const void *buffer, |
| 187 | unsigned_word addr, |
| 188 | unsigned nr_bytes); |
| 189 | |
| 190 | |
| 191 | /* Fixed sized read/write |
| 192 | |
| 193 | Transfer a fixed amout of memory between the host and target. The |
| 194 | memory always being translated and the operation always aborting |
| 195 | should a problem occure */ |
| 196 | |
| 197 | #define DECLARE_CORE_WRITE_N(N) \ |
| 198 | INLINE_CORE\ |
| 199 | (void) core_map_write_##N \ |
| 200 | (core_map *map, \ |
| 201 | unsigned_word addr, \ |
| 202 | unsigned_##N val, \ |
| 203 | cpu *processor, \ |
| 204 | unsigned_word cia); |
| 205 | |
| 206 | DECLARE_CORE_WRITE_N(1) |
| 207 | DECLARE_CORE_WRITE_N(2) |
| 208 | DECLARE_CORE_WRITE_N(4) |
| 209 | DECLARE_CORE_WRITE_N(8) |
| 210 | DECLARE_CORE_WRITE_N(word) |
| 211 | |
| 212 | #define DECLARE_CORE_READ_N(N) \ |
| 213 | INLINE_CORE\ |
| 214 | (unsigned_##N) core_map_read_##N \ |
| 215 | (core_map *map, \ |
| 216 | unsigned_word addr, \ |
| 217 | cpu *processor, \ |
| 218 | unsigned_word cia); |
| 219 | |
| 220 | DECLARE_CORE_READ_N(1) |
| 221 | DECLARE_CORE_READ_N(2) |
| 222 | DECLARE_CORE_READ_N(4) |
| 223 | DECLARE_CORE_READ_N(8) |
| 224 | DECLARE_CORE_READ_N(word) |
| 225 | |
| 226 | #endif |