* Jason A. Donenfeld: > +/******************************************************************** > + * > + * vDSO support helpers. > + * > + * The actual vDSO function is defined over in lib/vdso/getrandom.c, > + * but this section contains the kernel-mode helpers to support that. > + * > + ********************************************************************/ > + > +#ifdef CONFIG_VDSO_GETRANDOM > +/** > + * sys_vgetrandom_alloc - Allocate opaque states for use with vDSO getrandom(). > + * > + * @num: On input, a pointer to a suggested hint of how many states to > + * allocate, and on return the number of states actually allocated. > + * > + * @size_per_each: On input, must be zero. On return, the size of each state allocated, > + * so that the caller can split up the returned allocation into > + * individual states. > + * > + * @addr: Reserved, must be zero. > + * > + * @flags: Reserved, must be zero. > + * > + * The getrandom() vDSO function in userspace requires an opaque state, which > + * this function allocates by mapping a certain number of special pages into > + * the calling process. It takes a hint as to the number of opaque states > + * desired, and provides the caller with the number of opaque states actually > + * allocated, the size of each one in bytes, and the address of the first > + * state, which may be split up into @num states of @size_per_each bytes each, > + * by adding @size_per_each to the returned first state @num times. > + * > + * Returns the address of the first state in the allocation on success, or a > + * negative error value on failure. > + * > + * The returned address of the first state may be passed to munmap(2) with a > + * length of `(size_t)num * (size_t)size_per_each`, in order to deallocate the > + * memory, after which it is invalid to pass it to vDSO getrandom(). > + * > + * States allocated by this function must not be dereferenced, written, read, > + * or otherwise manipulated. The *only* supported operations are: > + * - Splitting up the states in intervals of @size_per_each, no more than > + * @num times from the first state. > + * - Passing a state to the getrandom() vDSO function's @opaque_state > + * parameter, but not passing the same state at the same time to two such > + * calls. > + * - Passing the first state to munmap(2), as described above. > + * All other uses are undefined behavior, which is subject to change or removal Suggest: “Passing the first state *and total length* to munmap(2)” Rest of the documentation looks good to me. It addresses my concerns about future evolution of this interface. Thanks, Florian
