stand/userboot/userboot.h

   1 /*-
   2  * Copyright (c) 2011 Doug Rabson
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  *
  14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24  * SUCH DAMAGE.
  25  *
  26  * $FreeBSD$
  27  */
  28
  29 /*
  30  * USERBOOT interface versions
  31  */
  32 #define USERBOOT_VERSION_1      1
  33 #define USERBOOT_VERSION_2      2
  34 #define USERBOOT_VERSION_3      3
  35
  36 /*
  37  * Version 4 added more generic callbacks for setting up
  38  * registers and descriptors. The callback structure is
  39  * backward compatible (new callbacks have been added at
  40  * the tail end).
  41  */
  42 #define USERBOOT_VERSION_4      4
  43
  44 /*
  45  * Version 5 added a callback for indicating that the guest
  46  * should be restarted with a different interpreter.  The callback
  47  * structure is still backward compatible.
  48  */
  49 #define USERBOOT_VERSION_5      5
  50
  51 /*
  52  * Exit codes from the loader
  53  */
  54 #define USERBOOT_EXIT_QUIT      1
  55 #define USERBOOT_EXIT_REBOOT    2
  56
  57 struct loader_callbacks {
  58         /*
  59          * Console i/o
  60          */
  61
  62         /*
  63          * Wait until a key is pressed on the console and then return it
  64          */
  65         int             (*getc)(void *arg);
  66
  67         /*
  68          * Write the character ch to the console
  69          */
  70         void            (*putc)(void *arg, int ch);
  71
  72         /*
  73          * Return non-zero if a key can be read from the console
  74          */
  75         int             (*poll)(void *arg);
  76
  77         /*
  78          * Host filesystem i/o
  79          */
  80
  81         /*
  82          * Open a file in the host filesystem
  83          */
  84         int             (*open)(void *arg, const char *filename, void **h_return);
  85
  86         /*
  87          * Close a file
  88          */
  89         int             (*close)(void *arg, void *h);
  90
  91         /*
  92          * Return non-zero if the file is a directory
  93          */
  94         int             (*isdir)(void *arg, void *h);
  95
  96         /*
  97          * Read size bytes from a file. The number of bytes remaining
  98          * in dst after reading is returned in *resid_return
  99          */
 100         int             (*read)(void *arg, void *h, void *dst, size_t size,
 101             size_t *resid_return);
 102
 103         /*
 104          * Read an entry from a directory. The entry's inode number is
 105          * returned in *fileno_return, its type in *type_return and
 106          * the name length in *namelen_return. The name itself is
 107          * copied to the buffer name which must be at least PATH_MAX
 108          * in size.
 109          */
 110         int             (*readdir)(void *arg, void *h, uint32_t *fileno_return,
 111             uint8_t *type_return, size_t *namelen_return, char *name);
 112
 113         /*
 114          * Seek to a location within an open file
 115          */
 116         int             (*seek)(void *arg, void *h, uint64_t offset,
 117             int whence);
 118
 119         /*
 120          * Return some stat(2) related information about the file
 121          */
 122         int             (*stat)(void *arg, void *h, struct stat *stp);
 123
 124         /*
 125          * Disk image i/o
 126          */
 127
 128         /*
 129          * Read from a disk image at the given offset
 130          */
 131         int             (*diskread)(void *arg, int unit, uint64_t offset,
 132             void *dst, size_t size, size_t *resid_return);
 133
 134         /*
 135          * Write to a disk image at the given offset
 136          */
 137         int             (*diskwrite)(void *arg, int unit, uint64_t offset,
 138             void *src, size_t size, size_t *resid_return);
 139
 140         /*
 141          * Guest virtual machine i/o
 142          */
 143
 144         /*
 145          * Copy to the guest address space
 146          */
 147         int             (*copyin)(void *arg, const void *from,
 148             uint64_t to, size_t size);
 149
 150         /*
 151          * Copy from the guest address space
 152          */
 153         int             (*copyout)(void *arg, uint64_t from,
 154             void *to, size_t size);
 155
 156         /*
 157          * Set a guest register value
 158          */
 159         void            (*setreg)(void *arg, int, uint64_t);
 160
 161         /*
 162          * Set a guest MSR value
 163          */
 164         void            (*setmsr)(void *arg, int, uint64_t);
 165
 166         /*
 167          * Set a guest CR value
 168          */
 169         void            (*setcr)(void *arg, int, uint64_t);
 170
 171         /*
 172          * Set the guest GDT address
 173          */
 174         void            (*setgdt)(void *arg, uint64_t, size_t);
 175
 176         /*
 177          * Transfer control to the guest at the given address
 178          */
 179         void            (*exec)(void *arg, uint64_t pc);
 180
 181         /*
 182          * Misc
 183          */
 184
 185         /*
 186          * Sleep for usec microseconds
 187          */
 188         void            (*delay)(void *arg, int usec);
 189
 190         /*
 191          * Exit with the given exit code
 192          */
 193         void            (*exit)(void *arg, int v);
 194
 195         /*
 196          * Return guest physical memory map details
 197          */
 198         void            (*getmem)(void *arg, uint64_t *lowmem,
 199             uint64_t *highmem);
 200
 201         /*
 202          * ioctl interface to the disk device
 203          */
 204         int             (*diskioctl)(void *arg, int unit, u_long cmd,
 205             void *data);
 206
 207         /*
 208          * Returns an environment variable in the form "name=value".
 209          *
 210          * If there are no more variables that need to be set in the
 211          * loader environment then return NULL.
 212          *
 213          * 'num' is used as a handle for the callback to identify which
 214          * environment variable to return next. It will begin at 0 and
 215          * each invocation will add 1 to the previous value of 'num'.
 216          */
 217         char *          (*getenv)(void *arg, int num);
 218
 219         /*
 220          * Version 4 additions.
 221          */
 222         int     (*vm_set_register)(void *arg, int vcpu, int reg, uint64_t val);
 223         int     (*vm_set_desc)(void *arg, int vcpu, int reg, uint64_t base,
 224             u_int limit, u_int access);
 225
 226         /*
 227          * Version 5 addition.
 228          */
 229         void    (*swap_interpreter)(void *arg, const char *interp);
 230 };