include/qemu/rng.h

   1 /*
   2  * QEMU Random Number Generator Backend
   3  *
   4  * Copyright IBM, Corp. 2012
   5  *
   6  * Authors:
   7  *  Anthony Liguori   <aliguori@us.ibm.com>
   8  *
   9  * This work is licensed under the terms of the GNU GPL, version 2 or later.
  10  * See the COPYING file in the top-level directory.
  11  */
  12
  13 #ifndef QEMU_RNG_H
  14 #define QEMU_RNG_H
  15
  16 #include "qom/object.h"
  17 #include "qemu-common.h"
  18 #include "qapi/error.h"
  19
  20 #define TYPE_RNG_BACKEND "rng-backend"
  21 #define RNG_BACKEND(obj) \
  22     OBJECT_CHECK(RngBackend, (obj), TYPE_RNG_BACKEND)
  23 #define RNG_BACKEND_GET_CLASS(obj) \
  24     OBJECT_GET_CLASS(RngBackendClass, (obj), TYPE_RNG_BACKEND)
  25 #define RNG_BACKEND_CLASS(klass) \
  26     OBJECT_CLASS_CHECK(RngBackendClass, (klass), TYPE_RNG_BACKEND)
  27
  28 typedef struct RngBackendClass RngBackendClass;
  29 typedef struct RngBackend RngBackend;
  30
  31 typedef void (EntropyReceiveFunc)(void *opaque,
  32                                   const void *data,
  33                                   size_t size);
  34
  35 struct RngBackendClass
  36 {
  37     ObjectClass parent_class;
  38
  39     void (*request_entropy)(RngBackend *s, size_t size,
  40                             EntropyReceiveFunc *recieve_entropy, void *opaque);
  41     void (*cancel_requests)(RngBackend *s);
  42
  43     void (*opened)(RngBackend *s, Error **errp);
  44 };
  45
  46 struct RngBackend
  47 {
  48     Object parent;
  49
  50     /*< protected >*/
  51     bool opened;
  52 };
  53
  54 /**
  55  * rng_backend_request_entropy:
  56  * @s: the backend to request entropy from
  57  * @size: the number of bytes of data to request
  58  * @receive_entropy: a function to be invoked when entropy is available
  59  * @opaque: data that should be passed to @receive_entropy
  60  *
  61  * This function is used by the front-end to request entropy from an entropy
  62  * source.  This function can be called multiple times before @receive_entropy
  63  * is invoked with different values of @receive_entropy and @opaque.  The
  64  * backend will queue each request and handle appropriately.
  65  *
  66  * The backend does not need to pass the full amount of data to @receive_entropy
  67  * but will pass a value greater than 0.
  68  */
  69 void rng_backend_request_entropy(RngBackend *s, size_t size,
  70                                  EntropyReceiveFunc *receive_entropy,
  71                                  void *opaque);
  72
  73 /**
  74  * rng_backend_cancel_requests:
  75  * @s: the backend to cancel all pending requests in
  76  *
  77  * Cancels all pending requests submitted by @rng_backend_request_entropy.  This
  78  * should be used by a device during reset or in preparation for live migration
  79  * to stop tracking any request.
  80  */
  81 void rng_backend_cancel_requests(RngBackend *s);
  82
  83 /**
  84  * rng_backend_open:
  85  * @s: the backend to open
  86  * @errp: a pointer to return the #Error object if an error occurs.
  87  *
  88  * This function will open the backend if it is not already open.  Calling this
  89  * function on an already opened backend will not result in an error.
  90  */
  91 void rng_backend_open(RngBackend *s, Error **errp);
  92
  93 #endif