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 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    specifying 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    powerful 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 transferred 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