184865Sobrien/*  This file is part of the program psim.
2130561Sobrien
384865Sobrien    Copyright (C) 1994-1997, Andrew Cagney <cagney@highland.com.au>
484865Sobrien
584865Sobrien    This program is free software; you can redistribute it and/or modify
684865Sobrien    it under the terms of the GNU General Public License as published by
784865Sobrien    the Free Software Foundation; either version 3 of the License, or
884865Sobrien    (at your option) any later version.
984865Sobrien
1084865Sobrien    This program is distributed in the hope that it will be useful,
1184865Sobrien    but WITHOUT ANY WARRANTY; without even the implied warranty of
1284865Sobrien    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
1384865Sobrien    GNU General Public License for more details.
1484865Sobrien
1584865Sobrien    You should have received a copy of the GNU General Public License
1684865Sobrien    along with this program; if not, see <http://www.gnu.org/licenses/>.
1784865Sobrien
1884865Sobrien    */
1984865Sobrien
2084865Sobrien
2184865Sobrien#ifndef _EMUL_CHIRP_H_
2284865Sobrien#define _EMUL_CHIRP_H_
2384865Sobrien
2484865Sobrien/* EMUL_CHIRP:
2584865Sobrien
2684865Sobrien   The emulation of the OpenBoot client interface (as defined in 1275)
2784865Sobrien   illustrates how it is possible for PSIM to implement an interface
2884865Sobrien   that is both running in virtual memory and is called using a
2984865Sobrien   standard function call interface.
3084865Sobrien
3184865Sobrien   The OpenBoot client interface is implemented by using two
3284865Sobrien   instructions:
3384865Sobrien
3484865Sobrien   	client_interface:
3584865Sobrien		<emul_call>
3684865Sobrien		blr
3784865Sobrien
3884865Sobrien   A client program makes a function call to `client_interface' using
3984865Sobrien   the `bl' instruction.  The simulator will then execute the
4084865Sobrien   <emul_call> instruction (which calls emul_chirp) and then the `blr'
4184865Sobrien   which will return to the caller.
4284865Sobrien
4384865Sobrien   In addition to providing the `client_interface' entry point, while
4484865Sobrien   a client request is being handled, emul_chirp patches (well it will
4584865Sobrien   one day) the data access exception vector with a <emul_call>
4684865Sobrien   instruction.  By doing this, emul_chirp is able to catch and handle
4784865Sobrien   any invalid data accesses it makes while emulating a client call.
4884865Sobrien
4984865Sobrien   When such an exception occures, emul_chirp is able to recover by
5084865Sobrien   restoring the processor and then calling the clients callback
5184865Sobrien   interface so that the client can recover from the data exception.
5284865Sobrien
5384865Sobrien   Handling this are the emul_chirp states:
5484865Sobrien
5584865Sobrien                              serving---.
5684865Sobrien                             /          |
5784865Sobrien   Emulation compleated     ^           v Client makes call to
5884865Sobrien     - restore int vectors  |           | emulated interface
5984865Sobrien                            ^           v   - patch exception vectors
6084865Sobrien                            |          /
6184865Sobrien                            `-emulating-. emulating the request
6284865Sobrien                             /          |
6384865Sobrien                            |           v Emulation encounters
6484865Sobrien   Client callback recovers ^           | data access exception
6584865Sobrien   from data exception and  |           v   - re-enable vm
6684865Sobrien   returns.                 ^           |   - call client callback
6784865Sobrien     - restart request      |          /
6884865Sobrien                            `--faulting
6984865Sobrien   */
7084865Sobrien
7184865Sobrien
7284865Sobrienextern const os_emul emul_chirp;
7384865Sobrien
7484865Sobrien#endif
7584865Sobrien