Re: [PATCH v2 3/5] docs: ABI: add /sys/kernel/error_report/ documentation

[Greg KH]

On Fri, Jan 15, 2021 at 02:03:34PM +0100, Alexander Potapenko wrote:
> Add ABI documentation for files in /sys/kernel/error_report/
> 
> Requested-by: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx>
> Cc: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx>
> Cc: Andrey Konovalov <andreyknvl@xxxxxxxxxx>
> Cc: Dmitry Vyukov <dvyukov@xxxxxxxxxx>
> Cc: Ingo Molnar <mingo@xxxxxxxxxx>
> Cc: Marco Elver <elver@xxxxxxxxxx>
> Cc: Petr Mladek <pmladek@xxxxxxxx>
> Cc: Steven Rostedt <rostedt@xxxxxxxxxxx>
> Cc: Sergey Senozhatsky <sergey.senozhatsky@xxxxxxxxx>
> Cc: linux-mm@xxxxxxxxx
> Signed-off-by: Alexander Potapenko <glider@xxxxxxxxxx>
> ---
>  .../ABI/testing/sysfs-kernel-error_report     | 41 +++++++++++++++++++
>  1 file changed, 41 insertions(+)
>  create mode 100644 Documentation/ABI/testing/sysfs-kernel-error_report
> 
> diff --git a/Documentation/ABI/testing/sysfs-kernel-error_report b/Documentation/ABI/testing/sysfs-kernel-error_report
> new file mode 100644
> index 000000000000..666d039f93a9
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-kernel-error_report
> @@ -0,0 +1,41 @@
> +What:		/sys/kernel/error_report/
> +Date:		January 2021
> +Contact:	Alexander Potapenko <glider@xxxxxxxxxx>,
> +		Marco Elver <elver@xxxxxxxxxx>
> +Description:
> +		/sys/kernel/error_report/ contains two files: "report_count"
> +		and "last_report". These files are used to notify userspace
> +		about error reports from the enrolled kernel subsystems (those
> +		that use error_report_start/error_report_end tracepoints).
> +
> +		"report_count" contains the current number of reported errors.
> +		This number is incremented every time the error_report_end
> +		trace event occurs in the kernel.
> +
> +		"last_report" contains the most recent error report; concurrent
> +		report generation results in collection of any one report
> +		("last_report" may not be the last shown on the console).
> +		A "report" is everything the task had printed to the console
> +		between issuing the error_report_start and error_report_end
> +		trace events.
> +
> +		Due to sysfs limitations, the report size is truncated at
> +		PAGE_SIZE. To save space, the leading info in square brackets
> +		printed by CONFIG_PRINTK_TIME and CONFIG_PRINTK_CALLER is
> +		trimmed from the output lines.
> +
> +		Both files use sysfs_notify() to notify userspace about
> +		changes. Userspace programs can use poll() to block until an
> +		error is reported:
> +
> +			pfd.fd = fd;
> +			pfd.events = POLLPRI;
> +			while (1) {
> +				lseek(pfd.fd, 0, SEEK_SET);
> +				poll(&pfd, 1, -1);
> +				read(pfd.fd, buffer, PAGE_SIZE);
> +				/* Process the report in @buffer. */
> +			}
> +
> +		Files in /sys/kernel/error_report/ are available when
> +		CONFIG_ERROR_REPORT_NOTIFY is enabled.

sysfs is "one value per file", please put something like this in
tracefs, as there is no such rules there.  Or debugfs, but please, not
sysfs.

Also, any reason you didn't cc: the sysfs maintainers?

thanks,

greg k-h