sim/ppc/corefile.h

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