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