errseq: Add to documentation tree

- Move errseq.rst into core-api
 - Add errseq to the core-api index
 - Promote the header to a more prominent header type, otherwise we get three
   entries in the table of contents.
 - Reformat the table to look nicer and be a little more proportional in
   terms of horizontal width per bit (the SF bit is still disproportionately
   large, but there's no way to fix that).
 - Include errseq kernel-doc in the errseq.rst
 - Neaten some kernel-doc markup

Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Reviewed-by: Jeff Layton <jlayton@redhat.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Matthew Wilcox 2017-12-22 06:32:16 -08:00 committed by Jonathan Corbet
parent aa931b44ae
commit 14ebc28e07
4 changed files with 38 additions and 22 deletions

View File

@ -1,5 +1,7 @@
=====================
The errseq_t datatype
=====================
An errseq_t is a way of recording errors in one place, and allowing any
number of "subscribers" to tell whether it has changed since a previous
point where it was sampled.
@ -21,12 +23,13 @@ a flag to tell whether the value has been sampled since a new value was
recorded. That allows us to avoid bumping the counter if no one has
sampled it since the last time an error was recorded.
Thus we end up with a value that looks something like this::
Thus we end up with a value that looks something like this:
bit: 31..13 12 11..0
+-----------------+----+----------------+
+--------------------------------------+----+------------------------+
| 31..13 | 12 | 11..0 |
+--------------------------------------+----+------------------------+
| counter | SF | errno |
+-----------------+----+----------------+
+--------------------------------------+----+------------------------+
The general idea is for "watchers" to sample an errseq_t value and keep
it as a running cursor. That value can later be used to tell whether
@ -42,6 +45,7 @@ has ever been an error set since it was first initialized.
API usage
=========
Let me tell you a story about a worker drone. Now, he's a good worker
overall, but the company is a little...management heavy. He has to
report to 77 supervisors today, and tomorrow the "big boss" is coming in
@ -125,6 +129,7 @@ not usable by anyone else.
Serializing errseq_t cursor updates
===================================
Note that the errseq_t API does not protect the errseq_t cursor during a
check_and_advance_operation. Only the canonical error code is handled
atomically. In a situation where more than one task might be using the
@ -147,3 +152,8 @@ errseq_check_and_advance after taking the lock. e.g.::
That avoids the spinlock in the common case where nothing has changed
since the last time it was checked.
Functions
=========
.. kernel-doc:: lib/errseq.c

View File

@ -22,6 +22,7 @@ Core utilities
flexible-arrays
librs
genalloc
errseq
printk-formats
Interfaces for kernel debugging

View File

@ -1,6 +1,6 @@
/* SPDX-License-Identifier: GPL-2.0 */
/*
* See Documentation/errseq.rst and lib/errseq.c
* See Documentation/core-api/errseq.rst and lib/errseq.c
*/
#ifndef _LINUX_ERRSEQ_H
#define _LINUX_ERRSEQ_H

View File

@ -46,14 +46,14 @@
* @eseq: errseq_t field that should be set
* @err: error to set (must be between -1 and -MAX_ERRNO)
*
* This function sets the error in *eseq, and increments the sequence counter
* This function sets the error in @eseq, and increments the sequence counter
* if the last sequence was sampled at some point in the past.
*
* Any error set will always overwrite an existing error.
*
* We do return the latest value here, primarily for debugging purposes. The
* return value should not be used as a previously sampled value in later calls
* as it will not have the SEEN flag set.
* Return: The previous value, primarily for debugging purposes. The
* return value should not be used as a previously sampled value in later
* calls as it will not have the SEEN flag set.
*/
errseq_t errseq_set(errseq_t *eseq, int err)
{
@ -108,11 +108,13 @@ errseq_t errseq_set(errseq_t *eseq, int err)
EXPORT_SYMBOL(errseq_set);
/**
* errseq_sample - grab current errseq_t value
* @eseq: pointer to errseq_t to be sampled
* errseq_sample() - Grab current errseq_t value.
* @eseq: Pointer to errseq_t to be sampled.
*
* This function allows callers to sample an errseq_t value, marking it as
* "seen" if required.
*
* Return: The current errseq value.
*/
errseq_t errseq_sample(errseq_t *eseq)
{
@ -134,15 +136,15 @@ errseq_t errseq_sample(errseq_t *eseq)
EXPORT_SYMBOL(errseq_sample);
/**
* errseq_check - has an error occurred since a particular sample point?
* @eseq: pointer to errseq_t value to be checked
* @since: previously-sampled errseq_t from which to check
* errseq_check() - Has an error occurred since a particular sample point?
* @eseq: Pointer to errseq_t value to be checked.
* @since: Previously-sampled errseq_t from which to check.
*
* Grab the value that eseq points to, and see if it has changed "since"
* the given value was sampled. The "since" value is not advanced, so there
* Grab the value that eseq points to, and see if it has changed @since
* the given value was sampled. The @since value is not advanced, so there
* is no need to mark the value as seen.
*
* Returns the latest error set in the errseq_t or 0 if it hasn't changed.
* Return: The latest error set in the errseq_t or 0 if it hasn't changed.
*/
int errseq_check(errseq_t *eseq, errseq_t since)
{
@ -155,11 +157,11 @@ int errseq_check(errseq_t *eseq, errseq_t since)
EXPORT_SYMBOL(errseq_check);
/**
* errseq_check_and_advance - check an errseq_t and advance to current value
* @eseq: pointer to value being checked and reported
* @since: pointer to previously-sampled errseq_t to check against and advance
* errseq_check_and_advance() - Check an errseq_t and advance to current value.
* @eseq: Pointer to value being checked and reported.
* @since: Pointer to previously-sampled errseq_t to check against and advance.
*
* Grab the eseq value, and see whether it matches the value that "since"
* Grab the eseq value, and see whether it matches the value that @since
* points to. If it does, then just return 0.
*
* If it doesn't, then the value has changed. Set the "seen" flag, and try to
@ -170,6 +172,9 @@ EXPORT_SYMBOL(errseq_check);
* value. The caller must provide that if necessary. Because of this, callers
* may want to do a lockless errseq_check before taking the lock and calling
* this.
*
* Return: Negative errno if one has been stored, or 0 if no new error has
* occurred.
*/
int errseq_check_and_advance(errseq_t *eseq, errseq_t *since)
{