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