/* This file is part of the program psim.
- Copyright (C) 1994-1995, Andrew Cagney <cagney@highland.com.au>
+ Copyright (C) 1994-1996, Andrew Cagney <cagney@highland.com.au>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
#ifndef _CORE_H_
#define _CORE_H_
-/* basic types */
+/* Introduction:
-typedef struct _core core;
-typedef struct _core_map core_map;
+ The core device, positioned at the top of the device tree that
+ models the architecure being simulated, acts as an interface
+ between the processor engines and the modeled devices.
-/* constructor */
+ On the one side the processor engines issue read and write requests
+ to the core (each request further catagorised as being for an
+ instruction or data subunit) while on the other side, the core is
+ receiving address configuration and DMA requests from child
+ devices.
-core INLINE_CORE *core_create
-(void);
+ In the below a synopsis of the core object and device in PSIM is
+ given, details of the object can be found in the files
+ <<corefile.h>> and <<corefile.c>>.
-device INLINE_CORE *core_device_create
-(core *);
+ */
+/* Core::
+ At the heart of the interface between devices and processor engines
+ is a single core object. This object, in turn, has two children:
-/* the core has three sub mappings that the more efficient
- read/write fixed quantity functions use */
+ o a core device which exists in the device tree and provides
+ an interface to the core object to child devices.
-core_map INLINE_CORE *core_readable
-(core *memory);
+ o a set of access maps which provide an efficient
+ interface to the core object for the processor engines.
-core_map INLINE_CORE *core_writeable
-(core *memory);
+ */
-core_map INLINE_CORE *core_executable
-(core *memory);
+/* basic types */
+typedef struct _core core;
+typedef struct _core_map core_map;
+/* constructor */
-/* operators to add/remove a mapping in the core
+INLINE_CORE\
+(core *) core_create
+(void);
- callback-memory:
+INLINE_CORE\
+(core *) core_from_device
+(device *root);
- All access are passed onto the specified devices callback routines
- after being `translated'. DEFAULT indicates that the specified
- memory should be called if all other mappings fail.
-
- For callback-memory, the device must be specified.
+INLINE_CORE\
+(void) core_init
+(core *memory);
- raw-memory:
+/* Core map management:::
- While RAM could be implemented using the callback interface
- core instead treats it as the common case including the code
- directly in the read/write operators.
+ The core ojbect manages two different types of address maps:
- For raw-memory, the device is ignored and the core alloc's a
- block to act as the memory.
+ o raw-memory - the address range can be implemented using
+ a simple byte array. No device needs to be notifed of
+ any accesses to the specified memory range.
+
+ o callback - Any access to the specified address range
+ should be passed on to the associated device. That device
+ can in turn resolve the access - handling or aborting or
+ restarting it.
- default-memory:
+ For callback maps it is possible to further order them by
+ specifiying specifying a callback level (eg callback + 1).
- Should, for the core, there be no defined mapping for a given
- address then the default map (if present) is called.
+ When the core is resolving an access it searches each of the maps
+ in order. First raw-memory and then callback maps (in assending
+ order of level). This search order makes it possible for latter
+ maps to overlap earlier ones. For instance, a device that wants to
+ be notified of all accesses that are not covered by raw-memory maps
+ could attach its self with an address range of the entire address
+ space.
- For default-memory, the device must be specified. */
+ In addition, each attached address map as an associated set of
+ access attributes (readable, writeable, executable) which are
+ verified as part of resolving each access.
-void INLINE_CORE core_attach
+ */
+
+INLINE_CORE\
+(void) core_attach
(core *map,
attach_type attach,
int address_space,
unsigned nr_bytes, /* host limited */
device *device); /*callback/default*/
-void INLINE_CORE core_detach
-(core *map,
- attach_type attach,
- int address_space,
- unsigned_word addr,
- unsigned nr_bytes, /* host limited */
- access_type access,
- device *device); /*callback/default*/
+/* Bugs:::
+
+ At present there is no method for removing address maps. That will
+ be implemented in a future release.
+
+ The operation of mapping between an address and its destination
+ device or memory array is currently implemented using a simple
+ linked list. The posibility of replacing this list with a more
+ powerfull data structure exists.
+
+ */
+
+
+/* Device::
+
+ The device that corresponds to the core object is described
+ separatly in the devices section.
+
+ */
+
+/* Access maps::
+
+ Providing an interface between the processor engines and the core
+ object are the access maps (core_map). Three access maps are
+ provided, one for each of the possible access requests that can be
+ generated by a processor.
+
+ o read
+ o write
+
+ o execute
+
+ A processor being able to request a read (or write) or write
+ operation to any of the maps. Those operations can either be
+ highly efficient (by specifying a specific transfer size) or
+ generic (specifying a parameterized number of bytes).
+
+ Internally the core object takes the request, determines the
+ approperiate attached address space that it should handle it passes
+ it on.
+
+ */
+
+INLINE_CORE\
+(core_map *) core_readable
+(core *memory);
+
+INLINE_CORE\
+(core_map *) core_writeable
+(core *memory);
+
+INLINE_CORE\
+(core_map *) core_executable
+(core *memory);
-/* Variable sized read/write:
+/* Variable sized read/write
Transfer (zero) a variable size block of data between the host and
target (possibly byte swapping it). Should any problems occure,
the number of bytes actually transfered is returned. */
-unsigned INLINE_CORE core_map_read_buffer
+INLINE_CORE\
+(unsigned) core_map_read_buffer
(core_map *map,
void *buffer,
unsigned_word addr,
unsigned nr_bytes);
-unsigned INLINE_CORE core_map_write_buffer
+INLINE_CORE\
+(unsigned) core_map_write_buffer
(core_map *map,
const void *buffer,
unsigned_word addr,
unsigned nr_bytes);
-/* Fixed sized read/write:
+/* Fixed sized read/write
Transfer a fixed amout of memory between the host and target. The
memory always being translated and the operation always aborting
should a problem occure */
#define DECLARE_CORE_WRITE_N(N) \
-void INLINE_CORE core_map_write_##N \
+INLINE_CORE\
+(void) core_map_write_##N \
(core_map *map, \
unsigned_word addr, \
unsigned_##N val, \
DECLARE_CORE_WRITE_N(word)
#define DECLARE_CORE_READ_N(N) \
-unsigned_##N INLINE_CORE core_map_read_##N \
+INLINE_CORE\
+(unsigned_##N) core_map_read_##N \
(core_map *map, \
unsigned_word addr, \
cpu *processor, \