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