Hi Thomas,
Thanks again for the big review. Comments inline below.
On Tue, Nov 29, 2022 at 11:02:29PM +0100, Thomas Gleixner wrote:
> > +/**
> > + * 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 output the number of states actually allocated.
> > + *
> > + * @size_per_each: the size of each state allocated, so that the caller can
> > + * split up the returned allocation into individual states.
> > + *
> > + * @flags: currently always zero.
>
> NIT!
>
> I personally prefer and ask for it in stuff I maintain:
>
> * @num: On input, a pointer to a suggested hint of how many states to
> * allocate, and on output the number of states actually allocated.
> *
> * @size_per_each: The size of each state allocated, so that the caller can
> * split up the returned allocation into individual states.
> *
> * @flags: Currently always zero.
>
> But your turf :)
Hm. Caps and punctuation seem mostly missing in kernel/time/, though it
is that way in some places, so I'll do it with caps and punctuation.
Presumably that's the "newer" style you prefer, though I didn't look at
the dates in git-blame to confirm that supposition.
>
> > + *
> > + * 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.
>
> make W=1 rightfully complains about:
>
> > +
>
> drivers/char/random.c:182: warning: bad line:
>
> > + * Returns a pointer to the first state in the allocation.
>
> I have serious doubts that this statement is correct.
"Returns the address of the first state in the allocation" is better I
guess.
> and W=1 also complains rightfully here:
>
> > +SYSCALL_DEFINE3(vgetrandom_alloc, unsigned int __user *, num,
> > + unsigned int __user *, size_per_each, unsigned int, flags)
>
> drivers/char/random.c:188: warning: expecting prototype for vgetrandom_alloc(). Prototype was for sys_vgetrandom_alloc() instead
Squinted at a lot of headers before realizing that's a kernel-doc
warning. Fixed, thanks.
> > +#ifndef _VDSO_GETRANDOM_H
> > +#define _VDSO_GETRANDOM_H
> > +
> > +#include <crypto/chacha.h>
> > +
> > +struct vgetrandom_state {
> > + union {
> > + struct {
> > + u8 batch[CHACHA_BLOCK_SIZE * 3 / 2];
> > + u32 key[CHACHA_KEY_SIZE / sizeof(u32)];
> > + };
> > + u8 batch_key[CHACHA_BLOCK_SIZE * 2];
> > + };
> > + unsigned long generation;
> > + u8 pos;
> > + bool in_use;
> > +};
>
> Again, please make this properly tabular:
>
> struct vgetrandom_state {
> union {
> struct {
> u8 batch[CHACHA_BLOCK_SIZE * 3 / 2];
> u32 key[CHACHA_KEY_SIZE / sizeof(u32)];
> };
> u8 batch_key[CHACHA_BLOCK_SIZE * 2];
> };
> unsigned long generation;
> u8 pos;
> bool in_use;
> };
>
> Plus some kernel doc which explains what this is about.
Will do. Though, I'm going to move this to the vDSO commit, and for the
syscall commit, which needs the struct to merely exist, I'll have no
members in it. This should make review a bit easier.
Jason
