src/dumm/guest.h

   1 /*
   2  * Copyright (C) 2007 Martin Willi
   3  * Hochschule fuer Technik Rapperswil
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * for more details.
  14  */
  15
  16 #ifndef GUEST_H
  17 #define GUEST_H
  18
  19 #include <library.h>
  20 #include <utils/enumerator.h>
  21
  22 #include "iface.h"
  23
  24 typedef enum guest_state_t guest_state_t;
  25 typedef struct guest_t guest_t;
  26
  27 /**
  28  * @brief State of a guest (started, stopped, ...)
  29  */
  30 enum guest_state_t {
  31         /** guest kernel not running at all */
  32         GUEST_STOPPED,
  33         /** kernel started, but not yet available */
  34         GUEST_STARTING,
  35         /** guest is up and running */
  36         GUEST_RUNNING,
  37         /** guest has been paused */
  38         GUEST_PAUSED,
  39         /** guest is stopping (shutting down) */
  40         GUEST_STOPPING,
  41 };
  42
  43 /**
  44  * string mappings for guest_state_t
  45  */
  46 extern enum_name_t *guest_state_names;
  47
  48 /**
  49  * Invoke function which lauches the UML guest.
  50  *
  51  * Consoles are all set to NULL, you may change them by adding additional UML
  52  * options to args before invocation.
  53  *
  54  * @param data          callback data
  55  * @param guest         guest to start
  56  * @param args          args to use for guest invocation, args[0] is kernel
  57  * @param argc          number of elements in args
  58  * @param idle
  59  * @return                      PID of child, 0 if failed
  60  */
  61 typedef pid_t (*invoke_function_t)(void *data, guest_t *guest,
  62                                                                    char *args[], int argc);
  63
  64 /**
  65  * Idle function to pass to start().
  66  */
  67 typedef void (*idle_function_t)(void);
  68
  69 /**
  70  * @brief A guest is a UML instance running on the host.
  71  **/
  72 struct guest_t {
  73
  74         /**
  75          * @brief Get the name of this guest.
  76          *
  77          * @return              name of the guest
  78          */
  79         char* (*get_name) (guest_t *this);
  80
  81         /**
  82          * @brief Get the process ID of the guest child process.
  83          *
  84          * @return              name of the guest
  85          */
  86         pid_t (*get_pid) (guest_t *this);
  87
  88         /**
  89          * @brief Get the state of the guest (stopped, started, etc.).
  90          *
  91          * @return              guests state
  92          */
  93         guest_state_t (*get_state)(guest_t *this);
  94
  95         /**
  96          * @brief Start the guest.
  97          *
  98          * @param invoke        UML guest invocation function
  99          * @param data          data to pass back to invoke function
 100          * @param idle          idle function to call while waiting on child
 101          * @return                      TRUE if guest successfully started
 102          */
 103         bool (*start) (guest_t *this, invoke_function_t invoke, void *data,
 104                                    idle_function_t idle);
 105
 106         /**
 107          * @brief Kill the guest.
 108          *
 109          * @param idle          idle function to call while waiting to termination
 110          * @return                      TRUE if guest was running and killed
 111          */
 112         bool (*stop) (guest_t *this, idle_function_t idle);
 113
 114         /**
 115          * @brief Create a new interface in the current scenario.
 116          *
 117          * @param name  name of the interface in the guest
 118          * @return              created interface, or NULL if failed
 119          */
 120         iface_t* (*create_iface)(guest_t *this, char *name);
 121
 122         /**
 123          * @brief Destroy an interface on guest.
 124          *
 125          * @param iface interface to destroy
 126          */
 127         void (*destroy_iface)(guest_t *this, iface_t *iface);
 128
 129         /**
 130          * @brief Create an enumerator over all guest interfaces.
 131          *
 132          * @return              enumerator over iface_t's
 133          */
 134         enumerator_t* (*create_iface_enumerator)(guest_t *this);
 135
 136         /**
 137          * @brief Set the template COWFS overlay to use.
 138          *
 139          * @param parent        parent directory where template diff should point to
 140          * @return                      FALSE if failed
 141          */
 142         bool (*load_template)(guest_t *this, char *parent);
 143
 144         /**
 145          * @brief Called whenever a SIGCHILD for the guests PID is received.
 146          */
 147         void (*sigchild)(guest_t *this);
 148
 149         /**
 150          * @brief Close and destroy a guest with all interfaces
 151          */
 152         void (*destroy) (guest_t *this);
 153 };
 154
 155 /**
 156  * @brief Create a new, unstarted guest.
 157  *
 158  * @param parent        parent directory to create the guest in
 159  * @param name          name of the guest to create
 160  * @param kernel        kernel this guest uses
 161  * @param master        read-only master filesystem for guest
 162  * @param mem           amount of memory to give the guest
 163  */
 164 guest_t *guest_create(char *parent, char *name, char *kernel,
 165                                           char *master, int mem);
 166
 167 /**
 168  * @brief Load a guest created with guest_create().
 169  *
 170  * @param parent        parent directory to look for a guest
 171  * @param name          name of the guest directory
 172  */
 173 guest_t *guest_load(char *parent, char *name);
 174
 175 #endif /* GUEST_H */
 176