[PATCH] Add errseq_t documentation to the tree
- Add it under 'Core API' because I think that's where it lives. - 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). Signed-off-by: Matthew Wilcox diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index eb16ba30aeb6..b8ec120c24f9 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -22,6 +22,7 @@ Core utilities flexible-arrays librs genalloc + ../errseq Interfaces for kernel debugging === diff --git a/Documentation/errseq.rst b/Documentation/errseq.rst index 4c29bd5afbc5..7c3ac9639ebf 100644 --- a/Documentation/errseq.rst +++ b/Documentation/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..131211..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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Add errseq_t documentation to the tree
On Fri, 2017-12-22 at 05:04 -0800, Matthew Wilcox wrote: > - Add it under 'Core API' because I think that's where it lives. > - 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). > > Signed-off-by: Matthew Wilcox > > diff --git a/Documentation/core-api/index.rst > b/Documentation/core-api/index.rst > index eb16ba30aeb6..b8ec120c24f9 100644 > --- a/Documentation/core-api/index.rst > +++ b/Documentation/core-api/index.rst > @@ -22,6 +22,7 @@ Core utilities > flexible-arrays > librs > genalloc > + ../errseq > Should we also move the file into core-api/ dir? > > Interfaces for kernel debugging > === > diff --git a/Documentation/errseq.rst b/Documentation/errseq.rst > index 4c29bd5afbc5..7c3ac9639ebf 100644 > --- a/Documentation/errseq.rst > +++ b/Documentation/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..131211..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 Thanks for the cleanup, looks good. Reviewed-by: Jeff Layton -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Add errseq_t documentation to the tree
On Fri, Dec 22, 2017 at 08:29:34AM -0500, Jeff Layton wrote: > > +++ b/Documentation/core-api/index.rst > > @@ -22,6 +22,7 @@ Core utilities > > flexible-arrays > > librs > > genalloc > > + ../errseq > > > > Should we also move the file into core-api/ dir? I was wondering the same thing. I'll do a v2. I was also thinking about including the kernel-doc from lib/errseq.c into this file. Seems like the logical thing to do. > Reviewed-by: Jeff Layton Merci! -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
