Documentation/bootstrap-interface.txt

   1 Bootstrap Interface
   2 ===================
   3
   4 The Jailhouse hypervisor is started by performing the following steps:
   5
   6  - map physical memory region reserved for Jailhouse at fixed virtual address
   7    JAILHOUSE_BASE (definition available via jailhouse/hypercall.h)
   8
   9  - load its binary image at beginning of hypervisor memory region
  10
  11  - load system configuration [1] at its target address in hypervisor memory
  12    region [2]
  13
  14  - set "Number of Possible CPUs" and "Number of Online CPUs" in hypervisor
  15    header according to system state
  16
  17  - initialize remaining hypervisor memory to zero
  18
  19  - on each online CPU, call function at address stored in "Initialization
  20    Function" hypervisor header field
  21
  22
  23 Hypervisor Header
  24 -----------------
  25
  26 The hypervisor binary image starts with a header structure as defined in the
  27 following. Its first part is preset during the build process of the hypervisor
  28 core. The second part needs to be filled by the Linux driver that loads
  29 Jailhouse.
  30
  31
  32 Header Layout
  33 - - - - - - -
  34
  35         +------------------------------+ - begin of hypervisor header
  36         |     Signature "JAILHOUS"     |   (lower address)
  37         |          (8 bytes)           |
  38         +------------------------------+
  39         |     Hypervisor Core Size     |
  40         |       (unsigned long)        |
  41         +------------------------------+
  42         | Per-CPU Data Structure Size  |
  43         |       (unsigned long)        |
  44         +------------------------------+
  45         |  Address of Initialization   |
  46         |      Function (pointer)      |   preset in binary image
  47         +------------------------------+ - - - - - - - - - - - - - - - - -
  48         |   Number of Possible CPUs    |   set by driver while loading
  49         |        (unsigned int)        |
  50         +------------------------------+
  51         |    Number of Online CPUs     |
  52         |        (unsigned int)        |
  53         +------------------------------+ - higher address
  54
  55 All fields use the native endianness of the system.
  56
  57
  58 Field Descriptions
  59 - - - - - - - - - -
  60
  61 Hypervisor Core Size               - size of hypervisor core, starting with its
  62                                      header, ending after its bss section [2]
  63 Per-CPU Data Structure Size        - size of data structure used for a single
  64                                      CPU
  65 Address of Initialization Function - virtual address of initialization
  66                                      function, see below
  67 Number of Possible CPUs            - 0 to possible CPUs - 1 defines the range
  68                                      of CPU ID that can be passed as argument
  69                                      to the initialization function
  70 Number of Online CPUs              - defines the number of CPUs the
  71                                      initialization function will expect
  72
  73
  74 Hypervisor Initialization Function
  75 ----------------------------------
  76
  77 The initialization function has to be called on each online CPU in order to
  78 hand over control of the system to Jailhouse. Jailhouse will wait for as many
  79 CPUs as specified in the "Number of Online CPUs" header field and will not
  80 return from the function until all started the initialization. CPUs not
  81 initialized during hypervisor activation cannot be used by any cell until
  82 Jailhouse is deactivated again.
  83
  84 Prototype: int entry(unsigned int cpu_id)
  85
  86 Calling convention: as used by Linux kernel on target architecture
  87
  88 Arguments: cpu_id - unique logical ID of caller's CPU
  89
  90 Return code: 0 on success, negative error code otherwise
  91
  92     Possible errors are:
  93         -EIO (-5)     - lacking hardware capabilities or unsupported hardware
  94                         state (as configured by Linux)
  95         -ENOMEM (-12) - insufficient hypervisor-internal memory
  96         -EBUSY  (-16) - a required hardware resource is already in use
  97         -ENODEV (-19) - CPU or I/O virtualization unit missing
  98         -EINVAL (-22) - invalid system configuration
  99         -ERANGE (-34) - a resource ID is out of supported range
 100
 101 The initialization function will always return the same code on all CPUs for a
 102 single initialization attempt.
 103
 104
 105 References
 106 ----------
 107
 108 [1] Documentation/configuration-format.txt
 109 [2] Documentation/memory-layout.txt