generator/generator_xdr.ml

   1 (* libguestfs
   2  * Copyright (C) 2009-2010 Red Hat Inc.
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  17  *)
  18
  19 (* Please read generator/README first. *)
  20
  21 open Printf
  22
  23 open Generator_types
  24 open Generator_utils
  25 open Generator_pr
  26 open Generator_docstrings
  27 open Generator_optgroups
  28 open Generator_actions
  29 open Generator_structs
  30
  31 (* Generate the protocol (XDR) file, 'guestfs_protocol.x' and
  32  * indirectly 'guestfs_protocol.h' and 'guestfs_protocol.c'.
  33  *
  34  * We have to use an underscore instead of a dash because otherwise
  35  * rpcgen generates incorrect code.
  36  *
  37  * This header is NOT exported to clients, but see also generate_structs_h.
  38  *)
  39 let generate_xdr () =
  40   generate_header CStyle LGPLv2plus;
  41
  42   (* This has to be defined to get around a limitation in Sun's rpcgen. *)
  43   pr "typedef string guestfs_str<>;\n";
  44   pr "\n";
  45
  46   (* Internal structures. *)
  47   List.iter (
  48     function
  49     | typ, cols ->
  50         pr "struct guestfs_int_%s {\n" typ;
  51         List.iter (function
  52                    | name, FChar -> pr "  char %s;\n" name
  53                    | name, FString -> pr "  string %s<>;\n" name
  54                    | name, FBuffer -> pr "  opaque %s<>;\n" name
  55                    | name, FUUID -> pr "  opaque %s[32];\n" name
  56                    | name, (FInt32|FUInt32) -> pr "  int %s;\n" name
  57                    | name, (FInt64|FUInt64|FBytes) -> pr "  hyper %s;\n" name
  58                    | name, FOptPercent -> pr "  float %s;\n" name
  59                   ) cols;
  60         pr "};\n";
  61         pr "\n";
  62         pr "typedef struct guestfs_int_%s guestfs_int_%s_list<>;\n" typ typ;
  63         pr "\n";
  64   ) structs;
  65
  66   List.iter (
  67     fun (shortname, (ret, args, optargs), _, _, _, _, _) ->
  68       if optargs <> [] then
  69         failwithf "optional arguments not supported in XDR yet";
  70
  71       let name = "guestfs_" ^ shortname in
  72
  73       (match args with
  74        | [] -> ()
  75        | args ->
  76            pr "struct %s_args {\n" name;
  77            List.iter (
  78              function
  79              | Pathname n | Device n | Dev_or_Path n | String n | Key n ->
  80                  pr "  string %s<>;\n" n
  81              | OptString n -> pr "  guestfs_str *%s;\n" n
  82              | StringList n | DeviceList n -> pr "  guestfs_str %s<>;\n" n
  83              | Bool n -> pr "  bool %s;\n" n
  84              | Int n -> pr "  int %s;\n" n
  85              | Int64 n -> pr "  hyper %s;\n" n
  86              | BufferIn n ->
  87                  pr "  opaque %s<>;\n" n
  88              | FileIn _ | FileOut _ -> ()
  89            ) args;
  90            pr "};\n\n"
  91       );
  92       (match ret with
  93        | RErr -> ()
  94        | RInt n ->
  95            pr "struct %s_ret {\n" name;
  96            pr "  int %s;\n" n;
  97            pr "};\n\n"
  98        | RInt64 n ->
  99            pr "struct %s_ret {\n" name;
 100            pr "  hyper %s;\n" n;
 101            pr "};\n\n"
 102        | RBool n ->
 103            pr "struct %s_ret {\n" name;
 104            pr "  bool %s;\n" n;
 105            pr "};\n\n"
 106        | RConstString _ | RConstOptString _ ->
 107            failwithf "RConstString|RConstOptString cannot be used by daemon functions"
 108        | RString n ->
 109            pr "struct %s_ret {\n" name;
 110            pr "  string %s<>;\n" n;
 111            pr "};\n\n"
 112        | RStringList n ->
 113            pr "struct %s_ret {\n" name;
 114            pr "  guestfs_str %s<>;\n" n;
 115            pr "};\n\n"
 116        | RStruct (n, typ) ->
 117            pr "struct %s_ret {\n" name;
 118            pr "  guestfs_int_%s %s;\n" typ n;
 119            pr "};\n\n"
 120        | RStructList (n, typ) ->
 121            pr "struct %s_ret {\n" name;
 122            pr "  guestfs_int_%s_list %s;\n" typ n;
 123            pr "};\n\n"
 124        | RHashtable n ->
 125            pr "struct %s_ret {\n" name;
 126            pr "  guestfs_str %s<>;\n" n;
 127            pr "};\n\n"
 128        | RBufferOut n ->
 129            pr "struct %s_ret {\n" name;
 130            pr "  opaque %s<>;\n" n;
 131            pr "};\n\n"
 132       );
 133   ) daemon_functions;
 134
 135   (* Table of procedure numbers. *)
 136   pr "enum guestfs_procedure {\n";
 137   List.iter (
 138     fun (shortname, _, proc_nr, _, _, _, _) ->
 139       pr "  GUESTFS_PROC_%s = %d,\n" (String.uppercase shortname) proc_nr
 140   ) daemon_functions;
 141   pr "  GUESTFS_PROC_NR_PROCS\n";
 142   pr "};\n";
 143   pr "\n";
 144
 145   (* Having to choose a maximum message size is annoying for several
 146    * reasons (it limits what we can do in the API), but it (a) makes
 147    * the protocol a lot simpler, and (b) provides a bound on the size
 148    * of the daemon which operates in limited memory space.
 149    *)
 150   pr "const GUESTFS_MESSAGE_MAX = %d;\n" (4 * 1024 * 1024);
 151   pr "\n";
 152
 153   (* Message header, etc. *)
 154   pr "\
 155 /* The communication protocol is now documented in the guestfs(3)
 156  * manpage.
 157  */
 158
 159 const GUESTFS_PROGRAM = 0x2000F5F5;
 160 const GUESTFS_PROTOCOL_VERSION = 2;
 161
 162 /* These constants must be larger than any possible message length. */
 163 const GUESTFS_LAUNCH_FLAG = 0xf5f55ff5;
 164 const GUESTFS_CANCEL_FLAG = 0xffffeeee;
 165 const GUESTFS_PROGRESS_FLAG = 0xffff5555;
 166
 167 enum guestfs_message_direction {
 168   GUESTFS_DIRECTION_CALL = 0,        /* client -> daemon */
 169   GUESTFS_DIRECTION_REPLY = 1        /* daemon -> client */
 170 };
 171
 172 enum guestfs_message_status {
 173   GUESTFS_STATUS_OK = 0,
 174   GUESTFS_STATUS_ERROR = 1
 175 };
 176
 177 ";
 178
 179   pr "const GUESTFS_ERROR_LEN = %d;\n" (64 * 1024);
 180   pr "\n";
 181
 182   pr "\
 183 struct guestfs_message_error {
 184   int linux_errno;                   /* Linux errno if available. */
 185   string error_message<GUESTFS_ERROR_LEN>;
 186 };
 187
 188 struct guestfs_message_header {
 189   unsigned prog;                     /* GUESTFS_PROGRAM */
 190   unsigned vers;                     /* GUESTFS_PROTOCOL_VERSION */
 191   guestfs_procedure proc;            /* GUESTFS_PROC_x */
 192   guestfs_message_direction direction;
 193   unsigned serial;                   /* message serial number */
 194   guestfs_message_status status;
 195 };
 196
 197 const GUESTFS_MAX_CHUNK_SIZE = 8192;
 198
 199 struct guestfs_chunk {
 200   int cancel;                        /* if non-zero, transfer is cancelled */
 201   /* data size is 0 bytes if the transfer has finished successfully */
 202   opaque data<GUESTFS_MAX_CHUNK_SIZE>;
 203 };
 204
 205 /* Progress notifications.  Daemon self-limits these messages to
 206  * at most one per second.  The daemon can send these messages
 207  * at any time, and the caller should discard unexpected messages.
 208  * 'position' and 'total' have undefined units; however they may
 209  * have meaning for some calls.
 210  *
 211  * NB. guestfs___recv_from_daemon assumes the XDR-encoded
 212  * structure is 24 bytes long.
 213  */
 214 struct guestfs_progress {
 215   guestfs_procedure proc;            /* @0:  GUESTFS_PROC_x */
 216   unsigned serial;                   /* @4:  message serial number */
 217   unsigned hyper position;           /* @8:  0 <= position <= total */
 218   unsigned hyper total;              /* @16: total size of operation */
 219                                      /* @24: size of structure */
 220 };
 221 "