sim/ppc/emul_chirp.h

   1 /*  This file is part of the program psim.
   2
   3     Copyright (C) 1994-1997, 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 _EMUL_CHIRP_H_
  22 #define _EMUL_CHIRP_H_
  23
  24 /* EMUL_CHIRP:
  25
  26    The emulation of the OpenBoot client interface (as defined in 1275)
  27    illustrates how it is possible for PSIM to implement an interface
  28    that is both running in virtual memory and is called using a
  29    standard function call interface.
  30
  31    The OpenBoot client interface is implemented by using two
  32    instructions:
  33
  34         client_interface:
  35                 <emul_call>
  36                 blr
  37
  38    A client program makes a function call to `client_interface' using
  39    the `bl' instruction.  The simulator will then execute the
  40    <emul_call> instruction (which calls emul_chirp) and then the `blr'
  41    which will return to the caller.
  42
  43    In addition to providing the `client_interface' entry point, while
  44    a client request is being handled, emul_chirp patches (well it will
  45    one day) the data access exception vector with a <emul_call>
  46    instruction.  By doing this, emul_chirp is able to catch and handle
  47    any invalid data accesses it makes while emulating a client call.
  48
  49    When such an exception occures, emul_chirp is able to recover by
  50    restoring the processor and then calling the clients callback
  51    interface so that the client can recover from the data exception.
  52
  53    Handling this are the emul_chirp states:
  54
  55                               serving---.
  56                              /          |
  57    Emulation compleated     ^           v Client makes call to
  58      - restore int vectors  |           | emulated interface
  59                             ^           v   - patch exception vectors
  60                             |          /
  61                             `-emulating-. emulating the request
  62                              /          |
  63                             |           v Emulation encounters
  64    Client callback recovers ^           | data access exception
  65    from data exception and  |           v   - re-enable vm
  66    returns.                 ^           |   - call client callback
  67      - restart request      |          /
  68                             `--faulting
  69    */
  70
  71
  72 extern const os_emul emul_chirp;
  73
  74 #endif