LXR qemu/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 "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
  28typedef struct RngBackendClass RngBackendClass;
  29typedef struct RngBackend RngBackend;
  30
  31typedef void (EntropyReceiveFunc)(void *opaque,
  32                                  const void *data,
  33                                  size_t size);
  34
  35struct RngBackendClass
  36{
  37    ObjectClass parent_class;
  38
  39    void (*request_entropy)(RngBackend *s, size_t size,
  40                            EntropyReceiveFunc *receive_entropy, void *opaque);
  41    void (*cancel_requests)(RngBackend *s);
  42
  43    void (*opened)(RngBackend *s, Error **errp);
  44};
  45
  46struct 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 */
  69void 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 */
  81void rng_backend_cancel_requests(RngBackend *s);
  82#endif
  83