Re: [PATCH v10 1/4] random: add vgetrandom_alloc() syscall

[Thomas Gleixner <tglx@linutronix.de>]

Jason!

On Tue, Nov 29 2022 at 22:06, Jason A. Donenfeld wrote:
> +
> +/********************************************************************
> + *
> + * 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_VGETRANDOM_ALLOC_SYSCALL
> +/**
> + * 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 :)

> + *
> + * 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.

Think about this comment and documentation as a boiler plate for the
mandatory man page for a new syscall (hint...)

> + *
> + */

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

> +{
> diff --git a/include/vdso/getrandom.h b/include/vdso/getrandom.h
> new file mode 100644
> index 000000000000..5f04c8bf4bd4
> --- /dev/null
> +++ b/include/vdso/getrandom.h
> @@ -0,0 +1,24 @@
> +/* SPDX-License-Identifier: GPL-2.0 */
> +/*
> + * Copyright (C) 2022 Jason A. Donenfeld <Jason@zx2c4.com>. All Rights Reserved.
> + */
> +
> +#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.

Thanks,

        tglx