include/sysemu/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 "qemu/queue.h"
  17 #include "qom/object.h"
  18
  19 #define TYPE_RNG_BACKEND "rng-backend"
  20 OBJECT_DECLARE_TYPE(RngBackend, RngBackendClass,
  21                     RNG_BACKEND)
  22
  23 #define TYPE_RNG_BUILTIN "rng-builtin"
  24
  25 typedef struct RngRequest RngRequest;
  26
  27 typedef void (EntropyReceiveFunc)(void *opaque,
  28                                   const void *data,
  29                                   size_t size);
  30
  31 struct RngRequest
  32 {
  33     EntropyReceiveFunc *receive_entropy;
  34     uint8_t *data;
  35     void *opaque;
  36     size_t offset;
  37     size_t size;
  38     QSIMPLEQ_ENTRY(RngRequest) next;
  39 };
  40
  41 struct RngBackendClass
  42 {
  43     ObjectClass parent_class;
  44
  45     void (*request_entropy)(RngBackend *s, RngRequest *req);
  46
  47     void (*opened)(RngBackend *s, Error **errp);
  48 };
  49
  50 struct RngBackend
  51 {
  52     Object parent;
  53
  54     /*< protected >*/
  55     bool opened;
  56     QSIMPLEQ_HEAD(, RngRequest) requests;
  57 };
  58
  59
  60 /**
  61  * rng_backend_request_entropy:
  62  * @s: the backend to request entropy from
  63  * @size: the number of bytes of data to request
  64  * @receive_entropy: a function to be invoked when entropy is available
  65  * @opaque: data that should be passed to @receive_entropy
  66  *
  67  * This function is used by the front-end to request entropy from an entropy
  68  * source.  This function can be called multiple times before @receive_entropy
  69  * is invoked with different values of @receive_entropy and @opaque.  The
  70  * backend will queue each request and handle appropriately.
  71  *
  72  * The backend does not need to pass the full amount of data to @receive_entropy
  73  * but will pass a value greater than 0.
  74  */
  75 void rng_backend_request_entropy(RngBackend *s, size_t size,
  76                                  EntropyReceiveFunc *receive_entropy,
  77                                  void *opaque);
  78
  79 /**
  80  * rng_backend_free_request:
  81  * @s: the backend that created the request
  82  * @req: the request to finalize
  83  *
  84  * Used by child rng backend classes to finalize requests once they've been
  85  * processed. The request is removed from the list of active requests and
  86  * deleted.
  87  */
  88 void rng_backend_finalize_request(RngBackend *s, RngRequest *req);
  89 #endif