Commit | Line | Data |
---|---|---|
84cbadad JL |
1 | #include <linux/err.h> |
2 | #include <linux/bug.h> | |
3 | #include <linux/atomic.h> | |
4 | #include <linux/errseq.h> | |
5 | ||
6 | /* | |
7 | * An errseq_t is a way of recording errors in one place, and allowing any | |
8 | * number of "subscribers" to tell whether it has changed since a previous | |
9 | * point where it was sampled. | |
10 | * | |
11 | * It's implemented as an unsigned 32-bit value. The low order bits are | |
12 | * designated to hold an error code (between 0 and -MAX_ERRNO). The upper bits | |
13 | * are used as a counter. This is done with atomics instead of locking so that | |
14 | * these functions can be called from any context. | |
15 | * | |
16 | * The general idea is for consumers to sample an errseq_t value. That value | |
17 | * can later be used to tell whether any new errors have occurred since that | |
18 | * sampling was done. | |
19 | * | |
20 | * Note that there is a risk of collisions if new errors are being recorded | |
21 | * frequently, since we have so few bits to use as a counter. | |
22 | * | |
23 | * To mitigate this, one bit is used as a flag to tell whether the value has | |
24 | * been sampled since a new value was recorded. That allows us to avoid bumping | |
25 | * the counter if no one has sampled it since the last time an error was | |
26 | * recorded. | |
27 | * | |
28 | * A new errseq_t should always be zeroed out. A errseq_t value of all zeroes | |
29 | * is the special (but common) case where there has never been an error. An all | |
30 | * zero value thus serves as the "epoch" if one wishes to know whether there | |
31 | * has ever been an error set since it was first initialized. | |
32 | */ | |
33 | ||
34 | /* The low bits are designated for error code (max of MAX_ERRNO) */ | |
35 | #define ERRSEQ_SHIFT ilog2(MAX_ERRNO + 1) | |
36 | ||
37 | /* This bit is used as a flag to indicate whether the value has been seen */ | |
38 | #define ERRSEQ_SEEN (1 << ERRSEQ_SHIFT) | |
39 | ||
40 | /* The lowest bit of the counter */ | |
41 | #define ERRSEQ_CTR_INC (1 << (ERRSEQ_SHIFT + 1)) | |
42 | ||
43 | /** | |
3acdfd28 | 44 | * errseq_set - set a errseq_t for later reporting |
84cbadad | 45 | * @eseq: errseq_t field that should be set |
3acdfd28 | 46 | * @err: error to set (must be between -1 and -MAX_ERRNO) |
84cbadad JL |
47 | * |
48 | * This function sets the error in *eseq, and increments the sequence counter | |
49 | * if the last sequence was sampled at some point in the past. | |
50 | * | |
51 | * Any error set will always overwrite an existing error. | |
52 | * | |
3acdfd28 JL |
53 | * We do return the latest value here, primarily for debugging purposes. The |
54 | * return value should not be used as a previously sampled value in later calls | |
55 | * as it will not have the SEEN flag set. | |
84cbadad | 56 | */ |
3acdfd28 | 57 | errseq_t errseq_set(errseq_t *eseq, int err) |
84cbadad JL |
58 | { |
59 | errseq_t cur, old; | |
60 | ||
61 | /* MAX_ERRNO must be able to serve as a mask */ | |
62 | BUILD_BUG_ON_NOT_POWER_OF_2(MAX_ERRNO + 1); | |
63 | ||
64 | /* | |
65 | * Ensure the error code actually fits where we want it to go. If it | |
66 | * doesn't then just throw a warning and don't record anything. We | |
67 | * also don't accept zero here as that would effectively clear a | |
68 | * previous error. | |
69 | */ | |
70 | old = READ_ONCE(*eseq); | |
71 | ||
72 | if (WARN(unlikely(err == 0 || (unsigned int)-err > MAX_ERRNO), | |
73 | "err = %d\n", err)) | |
74 | return old; | |
75 | ||
76 | for (;;) { | |
77 | errseq_t new; | |
78 | ||
79 | /* Clear out error bits and set new error */ | |
80 | new = (old & ~(MAX_ERRNO|ERRSEQ_SEEN)) | -err; | |
81 | ||
82 | /* Only increment if someone has looked at it */ | |
83 | if (old & ERRSEQ_SEEN) | |
84 | new += ERRSEQ_CTR_INC; | |
85 | ||
86 | /* If there would be no change, then call it done */ | |
87 | if (new == old) { | |
88 | cur = new; | |
89 | break; | |
90 | } | |
91 | ||
92 | /* Try to swap the new value into place */ | |
93 | cur = cmpxchg(eseq, old, new); | |
94 | ||
95 | /* | |
96 | * Call it success if we did the swap or someone else beat us | |
97 | * to it for the same value. | |
98 | */ | |
99 | if (likely(cur == old || cur == new)) | |
100 | break; | |
101 | ||
102 | /* Raced with an update, try again */ | |
103 | old = cur; | |
104 | } | |
105 | return cur; | |
106 | } | |
3acdfd28 | 107 | EXPORT_SYMBOL(errseq_set); |
84cbadad JL |
108 | |
109 | /** | |
110 | * errseq_sample - grab current errseq_t value | |
111 | * @eseq: pointer to errseq_t to be sampled | |
112 | * | |
113 | * This function allows callers to sample an errseq_t value, marking it as | |
114 | * "seen" if required. | |
115 | */ | |
116 | errseq_t errseq_sample(errseq_t *eseq) | |
117 | { | |
118 | errseq_t old = READ_ONCE(*eseq); | |
119 | errseq_t new = old; | |
120 | ||
121 | /* | |
122 | * For the common case of no errors ever having been set, we can skip | |
123 | * marking the SEEN bit. Once an error has been set, the value will | |
124 | * never go back to zero. | |
125 | */ | |
126 | if (old != 0) { | |
127 | new |= ERRSEQ_SEEN; | |
128 | if (old != new) | |
129 | cmpxchg(eseq, old, new); | |
130 | } | |
131 | return new; | |
132 | } | |
133 | EXPORT_SYMBOL(errseq_sample); | |
134 | ||
135 | /** | |
136 | * errseq_check - has an error occurred since a particular sample point? | |
137 | * @eseq: pointer to errseq_t value to be checked | |
138 | * @since: previously-sampled errseq_t from which to check | |
139 | * | |
140 | * Grab the value that eseq points to, and see if it has changed "since" | |
141 | * the given value was sampled. The "since" value is not advanced, so there | |
142 | * is no need to mark the value as seen. | |
143 | * | |
144 | * Returns the latest error set in the errseq_t or 0 if it hasn't changed. | |
145 | */ | |
146 | int errseq_check(errseq_t *eseq, errseq_t since) | |
147 | { | |
148 | errseq_t cur = READ_ONCE(*eseq); | |
149 | ||
150 | if (likely(cur == since)) | |
151 | return 0; | |
152 | return -(cur & MAX_ERRNO); | |
153 | } | |
154 | EXPORT_SYMBOL(errseq_check); | |
155 | ||
156 | /** | |
157 | * errseq_check_and_advance - check an errseq_t and advance to current value | |
158 | * @eseq: pointer to value being checked and reported | |
159 | * @since: pointer to previously-sampled errseq_t to check against and advance | |
160 | * | |
161 | * Grab the eseq value, and see whether it matches the value that "since" | |
162 | * points to. If it does, then just return 0. | |
163 | * | |
164 | * If it doesn't, then the value has changed. Set the "seen" flag, and try to | |
165 | * swap it into place as the new eseq value. Then, set that value as the new | |
166 | * "since" value, and return whatever the error portion is set to. | |
167 | * | |
168 | * Note that no locking is provided here for concurrent updates to the "since" | |
169 | * value. The caller must provide that if necessary. Because of this, callers | |
170 | * may want to do a lockless errseq_check before taking the lock and calling | |
171 | * this. | |
172 | */ | |
173 | int errseq_check_and_advance(errseq_t *eseq, errseq_t *since) | |
174 | { | |
175 | int err = 0; | |
176 | errseq_t old, new; | |
177 | ||
178 | /* | |
179 | * Most callers will want to use the inline wrapper to check this, | |
180 | * so that the common case of no error is handled without needing | |
181 | * to take the lock that protects the "since" value. | |
182 | */ | |
183 | old = READ_ONCE(*eseq); | |
184 | if (old != *since) { | |
185 | /* | |
186 | * Set the flag and try to swap it into place if it has | |
187 | * changed. | |
188 | * | |
189 | * We don't care about the outcome of the swap here. If the | |
190 | * swap doesn't occur, then it has either been updated by a | |
191 | * writer who is altering the value in some way (updating | |
192 | * counter or resetting the error), or another reader who is | |
193 | * just setting the "seen" flag. Either outcome is OK, and we | |
194 | * can advance "since" and return an error based on what we | |
195 | * have. | |
196 | */ | |
197 | new = old | ERRSEQ_SEEN; | |
198 | if (new != old) | |
199 | cmpxchg(eseq, old, new); | |
200 | *since = new; | |
201 | err = -(new & MAX_ERRNO); | |
202 | } | |
203 | return err; | |
204 | } | |
205 | EXPORT_SYMBOL(errseq_check_and_advance); |