diff options
| -rw-r--r-- | Documentation/core-api/errseq.rst (renamed from Documentation/errseq.rst) | 20 | ||||
| -rw-r--r-- | Documentation/core-api/index.rst | 1 | ||||
| -rw-r--r-- | include/linux/errseq.h | 2 | ||||
| -rw-r--r-- | lib/errseq.c | 37 |
4 files changed, 38 insertions, 22 deletions
diff --git a/Documentation/errseq.rst b/Documentation/core-api/errseq.rst index 4c29bd5afbc5..ff332e272405 100644 --- a/Documentation/errseq.rst +++ b/Documentation/core-api/errseq.rst @@ -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 - +-----------------+----+----------------+ - | counter | SF | errno | - +-----------------+----+----------------+ ++--------------------------------------+----+------------------------+ +| 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 diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index d55ee6b006ed..1b1fd01990b5 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -22,6 +22,7 @@ Core utilities flexible-arrays librs genalloc + errseq printk-formats Interfaces for kernel debugging diff --git a/include/linux/errseq.h b/include/linux/errseq.h index 6ffae9c5052d..fc2777770768 100644 --- a/include/linux/errseq.h +++ b/include/linux/errseq.h @@ -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 diff --git a/lib/errseq.c b/lib/errseq.c index 79cc66897db4..df782418b333 100644 --- a/lib/errseq.c +++ b/lib/errseq.c @@ -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) { |