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 57typedef struct _core core; 58typedef struct _core_map core_map; 59 60/* constructor */ 61 62INLINE_CORE\ 63(core *) core_create 64(void); 65 66INLINE_CORE\ 67(core *) core_from_device 68(device *root); 69 70INLINE_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 104INLINE_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 158INLINE_CORE\ 159(core_map *) core_readable 160(core *memory); 161 162INLINE_CORE\ 163(core_map *) core_writeable 164(core *memory); 165 166INLINE_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 176INLINE_CORE\ 177(unsigned) core_map_read_buffer 178(core_map *map, 179 void *buffer, 180 unsigned_word addr, 181 unsigned nr_bytes); 182 183INLINE_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) \ 198INLINE_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 206DECLARE_CORE_WRITE_N(1) 207DECLARE_CORE_WRITE_N(2) 208DECLARE_CORE_WRITE_N(4) 209DECLARE_CORE_WRITE_N(8) 210DECLARE_CORE_WRITE_N(word) 211 212#define DECLARE_CORE_READ_N(N) \ 213INLINE_CORE\ 214(unsigned_##N) core_map_read_##N \ 215(core_map *map, \ 216 unsigned_word addr, \ 217 cpu *processor, \ 218 unsigned_word cia); 219 220DECLARE_CORE_READ_N(1) 221DECLARE_CORE_READ_N(2) 222DECLARE_CORE_READ_N(4) 223DECLARE_CORE_READ_N(8) 224DECLARE_CORE_READ_N(word) 225 226#endif 227