Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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>
authored by
Matthew Wilcox
and committed by
Jonathan Corbet
14ebc28e
aa931b44
+38
-22
+1
Documentation/core-api/index.rst
+1
Documentation/core-api/index.rst
+15
-5
Documentation/errseq.rst
Documentation/core-api/errseq.rst
+15
-5
Documentation/errseq.rst
Documentation/core-api/errseq.rst
···
1
+
=====================
1
2
The errseq_t datatype
2
3
=====================
4
+
3
5
An errseq_t is a way of recording errors in one place, and allowing any
4
6
number of "subscribers" to tell whether it has changed since a previous
5
7
point where it was sampled.
···
23
21
recorded. That allows us to avoid bumping the counter if no one has
24
22
sampled it since the last time an error was recorded.
25
23
26
-
Thus we end up with a value that looks something like this::
24
+
Thus we end up with a value that looks something like this:
27
25
28
-
bit: 31..13 12 11..0
29
-
+-----------------+----+----------------+
30
-
| counter | SF | errno |
31
-
+-----------------+----+----------------+
26
+
+--------------------------------------+----+------------------------+
27
+
| 31..13 | 12 | 11..0 |
28
+
+--------------------------------------+----+------------------------+
29
+
| counter | SF | errno |
30
+
+--------------------------------------+----+------------------------+
32
31
33
32
The general idea is for "watchers" to sample an errseq_t value and keep
34
33
it as a running cursor. That value can later be used to tell whether
···
45
42
46
43
API usage
47
44
=========
45
+
48
46
Let me tell you a story about a worker drone. Now, he's a good worker
49
47
overall, but the company is a little...management heavy. He has to
50
48
report to 77 supervisors today, and tomorrow the "big boss" is coming in
···
129
125
130
126
Serializing errseq_t cursor updates
131
127
===================================
128
+
132
129
Note that the errseq_t API does not protect the errseq_t cursor during a
133
130
check_and_advance_operation. Only the canonical error code is handled
134
131
atomically. In a situation where more than one task might be using the
···
152
147
153
148
That avoids the spinlock in the common case where nothing has changed
154
149
since the last time it was checked.
150
+
151
+
Functions
152
+
=========
153
+
154
+
.. kernel-doc:: lib/errseq.c
+1
-1
include/linux/errseq.h
+1
-1
include/linux/errseq.h
+21
-16
lib/errseq.c
+21
-16
lib/errseq.c
···
46
46
* @eseq: errseq_t field that should be set
47
47
* @err: error to set (must be between -1 and -MAX_ERRNO)
48
48
*
49
-
* This function sets the error in *eseq, and increments the sequence counter
49
+
* This function sets the error in @eseq, and increments the sequence counter
50
50
* if the last sequence was sampled at some point in the past.
51
51
*
52
52
* Any error set will always overwrite an existing error.
53
53
*
54
-
* We do return the latest value here, primarily for debugging purposes. The
55
-
* return value should not be used as a previously sampled value in later calls
56
-
* as it will not have the SEEN flag set.
54
+
* Return: The previous value, primarily for debugging purposes. The
55
+
* return value should not be used as a previously sampled value in later
56
+
* calls as it will not have the SEEN flag set.
57
57
*/
58
58
errseq_t errseq_set(errseq_t *eseq, int err)
59
59
{
···
108
108
EXPORT_SYMBOL(errseq_set);
109
109
110
110
/**
111
-
* errseq_sample - grab current errseq_t value
112
-
* @eseq: pointer to errseq_t to be sampled
111
+
* errseq_sample() - Grab current errseq_t value.
112
+
* @eseq: Pointer to errseq_t to be sampled.
113
113
*
114
114
* This function allows callers to sample an errseq_t value, marking it as
115
115
* "seen" if required.
116
+
*
117
+
* Return: The current errseq value.
116
118
*/
117
119
errseq_t errseq_sample(errseq_t *eseq)
118
120
{
···
136
134
EXPORT_SYMBOL(errseq_sample);
137
135
138
136
/**
139
-
* errseq_check - has an error occurred since a particular sample point?
140
-
* @eseq: pointer to errseq_t value to be checked
141
-
* @since: previously-sampled errseq_t from which to check
137
+
* errseq_check() - Has an error occurred since a particular sample point?
138
+
* @eseq: Pointer to errseq_t value to be checked.
139
+
* @since: Previously-sampled errseq_t from which to check.
142
140
*
143
-
* Grab the value that eseq points to, and see if it has changed "since"
144
-
* the given value was sampled. The "since" value is not advanced, so there
141
+
* Grab the value that eseq points to, and see if it has changed @since
142
+
* the given value was sampled. The @since value is not advanced, so there
145
143
* is no need to mark the value as seen.
146
144
*
147
-
* Returns the latest error set in the errseq_t or 0 if it hasn't changed.
145
+
* Return: The latest error set in the errseq_t or 0 if it hasn't changed.
148
146
*/
149
147
int errseq_check(errseq_t *eseq, errseq_t since)
150
148
{
···
157
155
EXPORT_SYMBOL(errseq_check);
158
156
159
157
/**
160
-
* errseq_check_and_advance - check an errseq_t and advance to current value
161
-
* @eseq: pointer to value being checked and reported
162
-
* @since: pointer to previously-sampled errseq_t to check against and advance
158
+
* errseq_check_and_advance() - Check an errseq_t and advance to current value.
159
+
* @eseq: Pointer to value being checked and reported.
160
+
* @since: Pointer to previously-sampled errseq_t to check against and advance.
163
161
*
164
-
* Grab the eseq value, and see whether it matches the value that "since"
162
+
* Grab the eseq value, and see whether it matches the value that @since
165
163
* points to. If it does, then just return 0.
166
164
*
167
165
* If it doesn't, then the value has changed. Set the "seen" flag, and try to
···
172
170
* value. The caller must provide that if necessary. Because of this, callers
173
171
* may want to do a lockless errseq_check before taking the lock and calling
174
172
* this.
173
+
*
174
+
* Return: Negative errno if one has been stored, or 0 if no new error has
175
+
* occurred.
175
176
*/
176
177
int errseq_check_and_advance(errseq_t *eseq, errseq_t *since)
177
178
{