Commit 14ebc28e authored by Matthew Wilcox's avatar Matthew Wilcox Committed by Jonathan Corbet
Browse files

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: default avatarMatthew Wilcox <mawilcox@microsoft.com>
Reviewed-by: default avatarJeff Layton <jlayton@redhat.com>
Reviewed-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent aa931b44

Documentation/errseq.rst→Documentation/core-api/errseq.rst

+15 −5
Original line number Diff line number Diff line 
=====================

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

Documentation/core-api/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -22,6 +22,7 @@ Core utilities 
   flexible-arrays

   librs

   genalloc

   errseq

   printk-formats



Interfaces for kernel debugging

include/linux/errseq.h

+1 −1
Original line number Diff line number Diff line 
/* 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

lib/errseq.c

+21 −16
Original line number Diff line number Diff line
@@ -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)

{

CRA Git | Maintained and supported by SUSTech CRA and CCSE