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