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 *receive_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 94