Re: [PATCH] doc: convert printk-formats.txt to rst
On 12/08/2017 10:33 PM, Tobin C. Harding wrote: [Adding Laura] On Fri, Dec 08, 2017 at 06:18:45PM -0800, Joe Perches wrote: On Sat, 2017-12-09 at 12:27 +1100, Tobin C. Harding wrote: On Fri, Dec 08, 2017 at 01:22:37PM -0800, Joe Perches wrote: Outside of the documentation, what could be useful is for someone to add a tool to verify %p extension to the typeof address actually passed as an argument. This sounds interesting to work no. At first glance I have no idea how one would go about this. Some form of static analysis would be a good place to start, right? I'd like to allocate some cycles to this, any pointers most appreciated. A gcc-plugin would likely work best. What's the learning curve like in your opinion to do a gcc-plugin. I recall reading someplace 'deep understanding of how the compiler works' or some such thing. I suppose reading the Dragon book would be a good place to start? The hardest part of doing a gcc-plugin is understanding the gccisms. There isn't much documentation and most of what there is ends up being "here's how you hook into the compiler at point X" without showing how you do anything with it. The Dragon book (also known as "Compilers: Principles, Techniques, and Tools" for those who haven't heard of it before) is a great resource for general compiler concepts but it's not helpful for gcc-specific work. Writing about some of my experiments on my gcc-plugins has been on my TODO list for a while. 2018 resolution on actually finishing it perhaps. We could also catch pointers being cast to longs and printed with %x (and %u) or so I would guess. There was some discussion about such a thing here: http://www.openwall.com/lists/kernel-hardening/2017/02/14/38 Did you make much progress with this Laura? Not particularly. I wanted to re-use the kernel's print functionality in the plugin to automatically check new formats but I went down a rathole trying to make it work and got side tracked with other things and never picked it up again. I vaguely recall someone else doing a broader use tool which I believe was not smatch, but my google-fu isn't finding it. It might have been coccinelle based. thanks, Tobin. Thanks, Laura -- 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] doc: convert printk-formats.txt to rst
On Sat, Dec 9, 2017 at 3:48 AM, Dan Carpenter wrote: > On Fri, Dec 08, 2017 at 06:18:45PM -0800, Joe Perches wrote: >> On Sat, 2017-12-09 at 12:27 +1100, Tobin C. Harding wrote: >> > On Fri, Dec 08, 2017 at 01:22:37PM -0800, Joe Perches wrote: >> >> > > Outside of the documentation, what could be useful is for >> > > someone to add a tool to verify %p extension to >> > > the typeof address actually passed as an argument. >> > >> > This sounds interesting to work no. At first glance I have no idea how >> > one would go about this. Some form of static analysis would be a good >> > place to start, right? I'd like to allocate some cycles to this, any >> > pointers most appreciated. >> >> A gcc-plugin would likely work best. >> >> There was some discussion about such a thing here: >> http://www.openwall.com/lists/kernel-hardening/2017/02/14/38 >> >> I vaguely recall someone else doing a broader use tool >> which I believe was not smatch, but my google-fu isn't >> finding it. > > Yeah. Smatch has a check for this. Rasmus Villemoes wrote it. There's been some other work on format strings by Rasmus too. Thread is here, which I still haven't caught back up on: http://www.openwall.com/lists/kernel-hardening/2017/11/08/25 -Kees -- Kees Cook Pixel Security -- 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] doc: convert printk-formats.txt to rst
On Fri, Dec 08, 2017 at 06:18:45PM -0800, Joe Perches wrote: > On Sat, 2017-12-09 at 12:27 +1100, Tobin C. Harding wrote: > > On Fri, Dec 08, 2017 at 01:22:37PM -0800, Joe Perches wrote: > > > > Outside of the documentation, what could be useful is for > > > someone to add a tool to verify %p extension to > > > the typeof address actually passed as an argument. > > > > This sounds interesting to work no. At first glance I have no idea how > > one would go about this. Some form of static analysis would be a good > > place to start, right? I'd like to allocate some cycles to this, any > > pointers most appreciated. > > A gcc-plugin would likely work best. > > There was some discussion about such a thing here: > http://www.openwall.com/lists/kernel-hardening/2017/02/14/38 > > I vaguely recall someone else doing a broader use tool > which I believe was not smatch, but my google-fu isn't > finding it. Yeah. Smatch has a check for this. Rasmus Villemoes wrote it. regards, dan carpenter -- 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] doc: convert printk-formats.txt to rst
[Adding Laura] On Fri, Dec 08, 2017 at 06:18:45PM -0800, Joe Perches wrote: > On Sat, 2017-12-09 at 12:27 +1100, Tobin C. Harding wrote: > > On Fri, Dec 08, 2017 at 01:22:37PM -0800, Joe Perches wrote: > > > > Outside of the documentation, what could be useful is for > > > someone to add a tool to verify %p extension to > > > the typeof address actually passed as an argument. > > > > This sounds interesting to work no. At first glance I have no idea how > > one would go about this. Some form of static analysis would be a good > > place to start, right? I'd like to allocate some cycles to this, any > > pointers most appreciated. > > A gcc-plugin would likely work best. What's the learning curve like in your opinion to do a gcc-plugin. I recall reading someplace 'deep understanding of how the compiler works' or some such thing. I suppose reading the Dragon book would be a good place to start? We could also catch pointers being cast to longs and printed with %x (and %u) or so I would guess. > There was some discussion about such a thing here: > http://www.openwall.com/lists/kernel-hardening/2017/02/14/38 Did you make much progress with this Laura? > I vaguely recall someone else doing a broader use tool > which I believe was not smatch, but my google-fu isn't > finding it. > > It might have been coccinelle based. thanks, Tobin. -- 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] doc: convert printk-formats.txt to rst
On Sat, 2017-12-09 at 12:27 +1100, Tobin C. Harding wrote: > On Fri, Dec 08, 2017 at 01:22:37PM -0800, Joe Perches wrote: > > Outside of the documentation, what could be useful is for > > someone to add a tool to verify %p extension to > > the typeof address actually passed as an argument. > > This sounds interesting to work no. At first glance I have no idea how > one would go about this. Some form of static analysis would be a good > place to start, right? I'd like to allocate some cycles to this, any > pointers most appreciated. A gcc-plugin would likely work best. There was some discussion about such a thing here: http://www.openwall.com/lists/kernel-hardening/2017/02/14/38 I vaguely recall someone else doing a broader use tool which I believe was not smatch, but my google-fu isn't finding it. It might have been coccinelle based. -- 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] doc: convert printk-formats.txt to rst
On Fri, Dec 08, 2017 at 01:22:37PM -0800, Joe Perches wrote: > On Fri, 2017-12-08 at 13:06 -0800, Kees Cook wrote: > > Well ... my sense is that lib/vsprintf.c should remain the canonical > > documentation. > > I agree. > > > Anyone working on the code has the docs all together in > > one file. If it helps the .rst file to reformat the comments into > > kernel-doc, that's fine, but it shouldn't reduce the detail that is > > present, IMO. Now, expanding on it in printk-formats.rst is certainly > > a great idea, but I don't think it should come at the expense of > > someone just reading through vsprintf.c. That said, I can certainly > > see that redundancy is annoying, and it's possible for > > printk-formats.rst and vsprintf.c get get out of sync, but that > > doesn't seem to be a new problem. > > Nor has it been a real problem in practice. > > There is a comment in vsprintf.c that tells people > to update the doc. > > * ** Please update also Documentation/printk-formats.txt when making changes > ** > > > > I'd be curious to see what Jon or Joe think about this. > > > > (Perhaps the best first step would be to leave vsprintf.c as-is > > without kernel-doc-ification?) > > I think adding kernel-doc to vsprintf.c is unnecessary. Ok, thanks. Will re-spin without kernel-doc-ification in vsprintf.c > Outside of the documentation, what could be useful is for > someone to add a tool to verify %p extension to > the typeof address actually passed as an argument. This sounds interesting to work no. At first glance I have no idea how one would go about this. Some form of static analysis would be a good place to start, right? I'd like to allocate some cycles to this, any pointers most appreciated. thanks, Tobin. -- 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] doc: convert printk-formats.txt to rst
On Fri, 2017-12-08 at 13:06 -0800, Kees Cook wrote: > Well ... my sense is that lib/vsprintf.c should remain the canonical > documentation. I agree. > Anyone working on the code has the docs all together in > one file. If it helps the .rst file to reformat the comments into > kernel-doc, that's fine, but it shouldn't reduce the detail that is > present, IMO. Now, expanding on it in printk-formats.rst is certainly > a great idea, but I don't think it should come at the expense of > someone just reading through vsprintf.c. That said, I can certainly > see that redundancy is annoying, and it's possible for > printk-formats.rst and vsprintf.c get get out of sync, but that > doesn't seem to be a new problem. Nor has it been a real problem in practice. There is a comment in vsprintf.c that tells people to update the doc. * ** Please update also Documentation/printk-formats.txt when making changes ** > > I'd be curious to see what Jon or Joe think about this. > > (Perhaps the best first step would be to leave vsprintf.c as-is > without kernel-doc-ification?) I think adding kernel-doc to vsprintf.c is unnecessary. Outside of the documentation, what could be useful is for someone to add a tool to verify %p extension to the typeof address actually passed as an argument. -- 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] doc: convert printk-formats.txt to rst
On Thu, Dec 7, 2017 at 4:46 PM, Tobin C. Harding wrote: > On Thu, Dec 07, 2017 at 04:19:56PM -0800, Kees Cook wrote: >> On Thu, Dec 7, 2017 at 3:44 PM, Tobin C. Harding wrote: >> > Cheers Kees. FTR, changes to implement are: >> > >> > - Fix the capitalization of 'kernel'. >> >> I don't really have an opinion about which way is right. I personally >> don't capitalize it unless I speak about it as a single thing "The >> Linux Kernel". In this case I just noticed you had mixed usage. >> >> > - Add ESCAPE_* flags back into kernel-docs in lib/vsprintf.c >> >> I actually meant each of the sections. Several of the formats have >> per-item breakdowns that went missing in the new kernel-doc (ESCAPE_* >> was just an example). > > Oh dear, you don't like that. This is actually the part of the patch > that I was least sure about doing. I'm happy to revert, can I give you > my thought process for comment? > > When the kernel-docs get included into printk-formats.rst it seems > overly verbose to have all the information given twice. And then it > seems odd to bother having the extra descriptions in printk-formats.rst > if _all_ the required information is already in the kernel-docs? > > So I guessed that it would be nice for devs to get a bit of a hint at > the specifiers when having lib/vsprintf.c open (and they have the code > too) then if they needed more information going to printk-formats.rst. > > Also, since there is more space in printk-fomats.rst the info can be > spaced better and easier to read. > > Your thoughts? Well ... my sense is that lib/vsprintf.c should remain the canonical documentation. Anyone working on the code has the docs all together in one file. If it helps the .rst file to reformat the comments into kernel-doc, that's fine, but it shouldn't reduce the detail that is present, IMO. Now, expanding on it in printk-formats.rst is certainly a great idea, but I don't think it should come at the expense of someone just reading through vsprintf.c. That said, I can certainly see that redundancy is annoying, and it's possible for printk-formats.rst and vsprintf.c get get out of sync, but that doesn't seem to be a new problem. I'd be curious to see what Jon or Joe think about this. (Perhaps the best first step would be to leave vsprintf.c as-is without kernel-doc-ification?) -Kees -- Kees Cook Pixel Security -- 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] doc: convert printk-formats.txt to rst
On Thu, Dec 07, 2017 at 04:19:56PM -0800, Kees Cook wrote: > On Thu, Dec 7, 2017 at 3:44 PM, Tobin C. Harding wrote: > > Cheers Kees. FTR, changes to implement are: > > > > - Fix the capitalization of 'kernel'. > > I don't really have an opinion about which way is right. I personally > don't capitalize it unless I speak about it as a single thing "The > Linux Kernel". In this case I just noticed you had mixed usage. > > > - Add ESCAPE_* flags back into kernel-docs in lib/vsprintf.c > > I actually meant each of the sections. Several of the formats have > per-item breakdowns that went missing in the new kernel-doc (ESCAPE_* > was just an example). Oh dear, you don't like that. This is actually the part of the patch that I was least sure about doing. I'm happy to revert, can I give you my thought process for comment? When the kernel-docs get included into printk-formats.rst it seems overly verbose to have all the information given twice. And then it seems odd to bother having the extra descriptions in printk-formats.rst if _all_ the required information is already in the kernel-docs? So I guessed that it would be nice for devs to get a bit of a hint at the specifiers when having lib/vsprintf.c open (and they have the code too) then if they needed more information going to printk-formats.rst. Also, since there is more space in printk-fomats.rst the info can be spaced better and easier to read. Your thoughts? thanks, Tobin. -- 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] doc: convert printk-formats.txt to rst
On Thu, Dec 7, 2017 at 3:44 PM, Tobin C. Harding wrote: > Cheers Kees. FTR, changes to implement are: > > - Fix the capitalization of 'kernel'. I don't really have an opinion about which way is right. I personally don't capitalize it unless I speak about it as a single thing "The Linux Kernel". In this case I just noticed you had mixed usage. > - Add ESCAPE_* flags back into kernel-docs in lib/vsprintf.c I actually meant each of the sections. Several of the formats have per-item breakdowns that went missing in the new kernel-doc (ESCAPE_* was just an example). -Kees -- Kees Cook Pixel Security -- 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] doc: convert printk-formats.txt to rst
On Thu, Dec 07, 2017 at 04:01:46PM -0700, Jonathan Corbet wrote: > On Thu, 7 Dec 2017 14:50:42 -0800 > Kees Cook wrote: > > > > +These guides contain general information useful when writing kernel code. > > > + > > > +.. toctree:: > > > + :maxdepth: 1 > > > + > > > + printk-formats > > > > I actually think this belongs in the kernel core API documentation > > list (Documentation/core-api/index.rst). I defer to Jon's opinion, > > though. > > That's my opinion too, and what I had suggested in response to the > previous version. I suspect the pernicious influence of wombats! :) Steady on! Don't overuse it, you'll hurt my feelings :) Just kidding. I believe I got this right in the current version. If you are getting confused trying to follow these patches just try and follow the discussion my previous effort when hashing %p I'll let it settle a bit and re-spin after the weekend. thanks, Tobin. -- 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] doc: convert printk-formats.txt to rst
On Thu, Dec 07, 2017 at 02:50:42PM -0800, Kees Cook wrote:
> On Tue, Dec 5, 2017 at 5:45 PM, Tobin C. Harding wrote:
> > Documentation/printk-formats.txt is a candidate for conversion to
> > ReStructuredText format. Some effort has already been made to do this
> > conversion even thought the suffix is currently .txt
> >
> > Changes required to complete conversion
> >
> > - Add double backticks where needed.
> > - Add entry to Documentation/index.rst
> > - Use flat-table instead of ASCII table.
> > - Fix minor grammatical errors.
> > - Capitalize headers and correctly order heading adornments.
> > - Use 'Passed by reference' uniformly.
> > - Update pointer documentation around %px specifier.
> > - Fix erroneous double backticks (to commas).
> > - Simplify documentation for kobject.
> > - Convert lib/vsnprintf.c function docs to use kernel-docs and
> > include in Documentation/printk-formats.rst
>
> Awesome!
Hi Kees,
I've managed to muddle up the patches for this. New version went in as
part of a larger patch set. As you will no doubt see I've requested that
set to be dropped so I can implement your suggestions.
> >
> > Signed-off-by: Tobin C. Harding
> > ---
> >
> > The last two need special reviewing please. In particular the conversion
> > of kernel-docs in vsnprintf.c attempt was made to reduce documentation
> > duplication with comments in the source code being simplified in order
> > to be suitable for inclusion in Documentation/printk-formats.rst
> >
> > I used -M when formatting the patch. If you don't like the diff with
> > this flag just holla.
> >
> > thanks,
> > Tobin.
> >
> > Documentation/index.rst| 10 +
> > .../{printk-formats.txt => printk-formats.rst} | 295
> > -
> > lib/vsprintf.c | 160 +--
> > 3 files changed, 235 insertions(+), 230 deletions(-)
> > rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
> >
> > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > index cb7f1ba5b3b1..83ace60efbe7 100644
> > --- a/Documentation/index.rst
> > +++ b/Documentation/index.rst
> > @@ -87,6 +87,16 @@ implementation.
> >
> > sh/index
> >
> > +Miscellaneous documentation
> > +---
> > +
> > +These guides contain general information useful when writing kernel code.
> > +
> > +.. toctree::
> > + :maxdepth: 1
> > +
> > + printk-formats
>
> I actually think this belongs in the kernel core API documentation
> list (Documentation/core-api/index.rst). I defer to Jon's opinion,
> though.
Your right, Jon has told me as such.
> > [...]
> > +.. kernel-doc:: lib/vsprintf.c
> > + :doc: Extended Format Pointer Specifiers
>
> Awesome!
>
> > [...]
> > +For printing pointers when you *really* want to print the address. Please
> > consider whether or not you are leaking sensitive information about the
> > -Kernel layout in memory before printing pointers with %px. %px is
> > -functionally equivalent to %lx. %px is preferred to %lx because it is more
> > -uniquely grep'able. If, in the future, we need to modify the way the Kernel
> > -handles printing pointers it will be nice to be able to find the call
> > -sites.
> > +kernel memory layout before printing pointers with ``%px``. ``%px`` is
> > +functionally equivalent to ``%lx`` (or ``%lu``). ``%px``, however, is
> > +preferable because it is more uniquely grep'able. If, in the future, we
> > need
> > +to modify the way the Kernel handles printing pointers we will be better
> > +equipped to find the call sites.
>
> nit? You de-capitalized Kernel at the start but not at the end. "the
> Kernel handles ..."
Yeah, this was intentional. I guess it's wrong. I'm struggling with
capitalization of 'kernel' at the moment. In previous discussion it was
suggested to me that when referring to _the_ Kernel it should be capital
because it implies the Linux Kernel. And when referring to what could be
any kernel it should be lower case. The sticking point, and why I did
this patch as it is, is that I never refer to any other kernels so its
hard to tell when it should be lowercase. On top of this, loads of other
developers just us lowercase all the time.
Grammar is harder than C :)
> > [...]
> > diff --git a/lib/vsprintf.c b/lib/vsprintf.c
> > index 01c3957b2de6..f9247b78e8ef 100644
> > --- a/lib/vsprintf.c
> > +++ b/lib/vsprintf.c
> > @@ -1727,115 +1727,73 @@ static char *ptr_to_id(char *buf, char *end, void
> > *ptr, struct printf_spec spec)
> > return number(buf, end, hashval, spec);
> > }
> >
> > +/**
> > + * DOC: Extended Format Pointer Specifiers
> > + *
> > + * Briefly we handle the following extensions:
> > + *
> > + * - ``F`` - For symbolic function descriptor pointers with offset.
> > + * - ``f`` - For simple symbolic function names without offset.
> > + *
> > + * - ``S`` - For symbolic direct pointers with offset.
> > + * - ``s`` - For symbolic direct pointers without offset.
> > + *
Re: [PATCH] doc: convert printk-formats.txt to rst
On Thu, 7 Dec 2017 14:50:42 -0800 Kees Cook wrote: > > +These guides contain general information useful when writing kernel code. > > + > > +.. toctree:: > > + :maxdepth: 1 > > + > > + printk-formats > > I actually think this belongs in the kernel core API documentation > list (Documentation/core-api/index.rst). I defer to Jon's opinion, > though. That's my opinion too, and what I had suggested in response to the previous version. I suspect the pernicious influence of wombats! :) jon -- 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] doc: convert printk-formats.txt to rst
On Tue, Dec 5, 2017 at 5:45 PM, Tobin C. Harding wrote:
> Documentation/printk-formats.txt is a candidate for conversion to
> ReStructuredText format. Some effort has already been made to do this
> conversion even thought the suffix is currently .txt
>
> Changes required to complete conversion
>
> - Add double backticks where needed.
> - Add entry to Documentation/index.rst
> - Use flat-table instead of ASCII table.
> - Fix minor grammatical errors.
> - Capitalize headers and correctly order heading adornments.
> - Use 'Passed by reference' uniformly.
> - Update pointer documentation around %px specifier.
> - Fix erroneous double backticks (to commas).
> - Simplify documentation for kobject.
> - Convert lib/vsnprintf.c function docs to use kernel-docs and
> include in Documentation/printk-formats.rst
Awesome!
>
> Signed-off-by: Tobin C. Harding
> ---
>
> The last two need special reviewing please. In particular the conversion
> of kernel-docs in vsnprintf.c attempt was made to reduce documentation
> duplication with comments in the source code being simplified in order
> to be suitable for inclusion in Documentation/printk-formats.rst
>
> I used -M when formatting the patch. If you don't like the diff with
> this flag just holla.
>
> thanks,
> Tobin.
>
> Documentation/index.rst| 10 +
> .../{printk-formats.txt => printk-formats.rst} | 295
> -
> lib/vsprintf.c | 160 +--
> 3 files changed, 235 insertions(+), 230 deletions(-)
> rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
>
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index cb7f1ba5b3b1..83ace60efbe7 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -87,6 +87,16 @@ implementation.
>
> sh/index
>
> +Miscellaneous documentation
> +---
> +
> +These guides contain general information useful when writing kernel code.
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + printk-formats
I actually think this belongs in the kernel core API documentation
list (Documentation/core-api/index.rst). I defer to Jon's opinion,
though.
> [...]
> +.. kernel-doc:: lib/vsprintf.c
> + :doc: Extended Format Pointer Specifiers
Awesome!
> [...]
> +For printing pointers when you *really* want to print the address. Please
> consider whether or not you are leaking sensitive information about the
> -Kernel layout in memory before printing pointers with %px. %px is
> -functionally equivalent to %lx. %px is preferred to %lx because it is more
> -uniquely grep'able. If, in the future, we need to modify the way the Kernel
> -handles printing pointers it will be nice to be able to find the call
> -sites.
> +kernel memory layout before printing pointers with ``%px``. ``%px`` is
> +functionally equivalent to ``%lx`` (or ``%lu``). ``%px``, however, is
> +preferable because it is more uniquely grep'able. If, in the future, we need
> +to modify the way the Kernel handles printing pointers we will be better
> +equipped to find the call sites.
nit? You de-capitalized Kernel at the start but not at the end. "the
Kernel handles ..."
> [...]
> diff --git a/lib/vsprintf.c b/lib/vsprintf.c
> index 01c3957b2de6..f9247b78e8ef 100644
> --- a/lib/vsprintf.c
> +++ b/lib/vsprintf.c
> @@ -1727,115 +1727,73 @@ static char *ptr_to_id(char *buf, char *end, void
> *ptr, struct printf_spec spec)
> return number(buf, end, hashval, spec);
> }
>
> +/**
> + * DOC: Extended Format Pointer Specifiers
> + *
> + * Briefly we handle the following extensions:
> + *
> + * - ``F`` - For symbolic function descriptor pointers with offset.
> + * - ``f`` - For simple symbolic function names without offset.
> + *
> + * - ``S`` - For symbolic direct pointers with offset.
> + * - ``s`` - For symbolic direct pointers without offset.
> + * - ``[FfSs]R`` - As above with ``__builtin_extract_return_addr()``
> translation.
> + * - ``B`` - For backtraced symbolic direct pointers with offset.
> + * - ``R`` - For decoded struct resource, e.g., [mem 0x0-0x1f 64bit pref].
> + * - ``r`` - For raw struct resource, e.g., [mem 0x0-0x1f flags 0x201].
> + * - ``b[l]`` - For a bitmap, the number of bits is determined by the field
> + * width which must be explicitly specified either as part of the format
> + * string ``32b[l]`` or through ``*b[l]``, ``[l]`` selects range-list
> format
> + * instead of hex format.
> + * - ``M`` - For a 6-byte MAC address, it prints the address in the usual
> + * colon-separated hex notation.
> + * - ``m`` - For a 6-byte MAC address, it prints the hex address without
> colons.
> + * - ``MF`` - For a 6-byte MAC FDDI address, it prints the address with a
> + * dash-separated hex notation.
> + * - ``[mM]R`` - For a 6-byte MAC address, Reverse order (Bluetooth).
> + * - ``I[46]`` - For IPv4/IPv6 addresses printed in the usual way.
> + * - ``I[S][pfs]`` - For generic IPv4/IPv6 address (struc
Re: [PATCH] doc: convert printk-formats.txt to rst
On Wed, Dec 06, 2017 at 04:39:58PM -0800, Randy Dunlap wrote:
> On 12/06/2017 01:16 PM, Tobin C. Harding wrote:
> > On Wed, Dec 06, 2017 at 10:18:49AM -0800, Randy Dunlap wrote:
> >
> > Thanks for your comments Randy.
> >
>
> >>> Documentation/index.rst| 10 +
> >>> .../{printk-formats.txt => printk-formats.rst} | 295
> >>> -
> >>> lib/vsprintf.c | 160 +--
> >>> 3 files changed, 235 insertions(+), 230 deletions(-)
> >>> rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
> >>
> >>> diff --git a/Documentation/printk-formats.txt
> >>> b/Documentation/printk-formats.rst
> >>> similarity index 61%
> >>> rename from Documentation/printk-formats.txt
> >>> rename to Documentation/printk-formats.rst
> >>> index aa0a776c817a..51449d213748 100644
> >>> --- a/Documentation/printk-formats.txt
> >>> +++ b/Documentation/printk-formats.rst
>
> >>> @@ -194,8 +233,8 @@ printing SSIDs.
> >>>
> >>> If field width is omitted the 1 byte only will be escaped.
> >>
> >> then
> >> I think...
> >
> > Ha ha, I was borderline with this change when doing this patch. It may
> > not appear so but I did try to do the minimal amount of changes while
> > improving correctness. I appreciate your comments since hopefully I can
> > better make these judgment calls next time.
>
> I wasn't so sure about that attempt (at minimal changes). :)
ROFL
> > Will change as suggested.
>
> >>> Where no additional specifiers are used the default big endian
> >>> -order with lower case hex characters will be printed.
> >>> +order with lower case hex digits will be printed.
> >>
> >> digits could imply base 10. but no big deal.
> >
> > Are you sure about this? I was under the impression that when
> > representing a number the character set used are refereed to as 'digits'
> > irrespective of base.
> >
> > hexadecimal digit
> > octal digit
> > digit (assumed base 10)
> >
> > Open to correction though.
>
> Like I said, I don't care strongly about this. (I'm easy.)
> but hex notation (like you said later) sounds good.
Got it.
thanks,
Tobin.
--
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] doc: convert printk-formats.txt to rst
On 12/06/2017 01:16 PM, Tobin C. Harding wrote:
> On Wed, Dec 06, 2017 at 10:18:49AM -0800, Randy Dunlap wrote:
>
> Thanks for your comments Randy.
>
>>> Documentation/index.rst| 10 +
>>> .../{printk-formats.txt => printk-formats.rst} | 295
>>> -
>>> lib/vsprintf.c | 160 +--
>>> 3 files changed, 235 insertions(+), 230 deletions(-)
>>> rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
>>
>>> diff --git a/Documentation/printk-formats.txt
>>> b/Documentation/printk-formats.rst
>>> similarity index 61%
>>> rename from Documentation/printk-formats.txt
>>> rename to Documentation/printk-formats.rst
>>> index aa0a776c817a..51449d213748 100644
>>> --- a/Documentation/printk-formats.txt
>>> +++ b/Documentation/printk-formats.rst
>>> @@ -194,8 +233,8 @@ printing SSIDs.
>>>
>>> If field width is omitted the 1 byte only will be escaped.
>>
>> then
>> I think...
>
> Ha ha, I was borderline with this change when doing this patch. It may
> not appear so but I did try to do the minimal amount of changes while
> improving correctness. I appreciate your comments since hopefully I can
> better make these judgment calls next time.
I wasn't so sure about that attempt (at minimal changes). :)
> Will change as suggested.
>>> Where no additional specifiers are used the default big endian
>>> -order with lower case hex characters will be printed.
>>> +order with lower case hex digits will be printed.
>>
>> digits could imply base 10. but no big deal.
>
> Are you sure about this? I was under the impression that when
> representing a number the character set used are refereed to as 'digits'
> irrespective of base.
>
> hexadecimal digit
> octal digit
> digit (assumed base 10)
>
> Open to correction though.
Like I said, I don't care strongly about this. (I'm easy.)
but hex notation (like you said later) sounds good.
--
~Randy
--
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] doc: convert printk-formats.txt to rst
On Wed, Dec 06, 2017 at 10:18:49AM -0800, Randy Dunlap wrote:
> On 12/05/2017 05:45 PM, Tobin C. Harding wrote:
> > Documentation/printk-formats.txt is a candidate for conversion to
> > ReStructuredText format. Some effort has already been made to do this
> > conversion even thought the suffix is currently .txt
> >
> > Changes required to complete conversion
> >
> > - Add double backticks where needed.
> > - Add entry to Documentation/index.rst
> > - Use flat-table instead of ASCII table.
> > - Fix minor grammatical errors.
> > - Capitalize headers and correctly order heading adornments.
>
> That's a style choice and an unneeded change (referring to Capitalize
> headers).
>
> > - Use 'Passed by reference' uniformly.
> > - Update pointer documentation around %px specifier.
> > - Fix erroneous double backticks (to commas).
> > - Simplify documentation for kobject.
> > - Convert lib/vsnprintf.c function docs to use kernel-docs and
> > include in Documentation/printk-formats.rst
>
> good idea.
>
> >
> > Signed-off-by: Tobin C. Harding
> > ---
> >
> > The last two need special reviewing please. In particular the conversion
> > of kernel-docs in vsnprintf.c attempt was made to reduce documentation
> > duplication with comments in the source code being simplified in order
> > to be suitable for inclusion in Documentation/printk-formats.rst
> >
> > I used -M when formatting the patch. If you don't like the diff with
> > this flag just holla.
> >
> > thanks,
> > Tobin.
> >
> > Documentation/index.rst| 10 +
> > .../{printk-formats.txt => printk-formats.rst} | 295
> > -
> > lib/vsprintf.c | 160 +--
> > 3 files changed, 235 insertions(+), 230 deletions(-)
> > rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
>
> > diff --git a/Documentation/printk-formats.txt
> > b/Documentation/printk-formats.rst
> > similarity index 61%
> > rename from Documentation/printk-formats.txt
> > rename to Documentation/printk-formats.rst
> > index aa0a776c817a..51449d213748 100644
> > --- a/Documentation/printk-formats.txt
> > +++ b/Documentation/printk-formats.rst
> > @@ -1,6 +1,6 @@
> > -=
> > -How to get printk format specifiers right
> > -=
> > +=
> > +How to Get ``printk`` Format Specifiers Right
> > +=
> >
> > :Author: Randy Dunlap
> > :Author: Andrew Murray
> > @@ -8,56 +8,91 @@ How to get printk format specifiers right
> > Integer types
> > =
> >
> > -::
> > +For printing integer types, we have the following format specifiers:
> > +
> > + .. flat-table::
> > + :widths: 2 2
> > +
> > + * - **Type**
> > + - **Specifier**
> > +
> > + * - ``int``
> > +- ``%d`` or ``%x``
> > +
> > + * - ``unsigned int``
> > + - ``%u`` or ``%x``
> > +
> > + * - ``long``
> > + - ``%ld`` or ``%lx``
> > +
> > + * - ``unsigned long``
> > + - ``%lu`` or ``%lx``
> > +
> > + * - ``long long``
> > + - ``%lld`` or ``%llx``
> >
> > - If variable is of Type, use printk format specifier:
> > -
> > - int %d or %x
> > - unsigned int%u or %x
> > - long%ld or %lx
> > - unsigned long %lu or %lx
> > - long long %lld or %llx
> > - unsigned long long %llu or %llx
> > - size_t %zu or %zx
> > - ssize_t %zd or %zx
> > - s32 %d or %x
> > - u32 %u or %x
> > - s64 %lld or %llx
> > - u64 %llu or %llx
> > -
> > -If is dependent on a config option for its size (e.g., ``sector_t``,
> > + * - ``unsigned long long``
> > + - ``%llu`` or ``%llx``
> > +
> > + * - ``size_t``
> > + - ``%zu`` or ``%zx``
> > +
> > + * - ``ssize_t``
> > + - ``%zd`` or ``%zx``
> > +
> > + * - ``s32``
> > + - ``%d`` or ``%x``
> > +
> > + * - ``u32``
> > + - ``%u`` or ``%x``
> > +
> > + * - ``s64``
> > + - ``%lld`` or ``%llx``
> > +
> > + * - ``u64``
> > + - ``%llu`` or ``%llx``
> > +
> > +
> > +If is dependent on a config option for its size (e.g.,
> > ``sector_t``,
> > ``blkcnt_t``) or is architecture-dependent for its size (e.g.,
> > ``tcflag_t``),
> > use a format specifier of its largest possible type and explicitly cast to
> > it.
> >
> > Example::
> >
> > - printk("test: sector number/total blocks: %llu/%llu\n",
> > - (unsigned long long)sector, (unsigned long long)blockcount);
> > + printk("test: total blocks: %llu\n", (unsigned long long)blockcount);
> >
Re: [PATCH] doc: convert printk-formats.txt to rst
On Wed, Dec 06, 2017 at 11:23:25AM -0700, Jonathan Corbet wrote: > On Wed, 6 Dec 2017 12:45:29 +1100 > "Tobin C. Harding" wrote: > > > Documentation/printk-formats.txt is a candidate for conversion to > > ReStructuredText format. Some effort has already been made to do this > > conversion even thought the suffix is currently .txt > > > > Changes required to complete conversion > > > > - Add double backticks where needed. > > - Add entry to Documentation/index.rst > > - Use flat-table instead of ASCII table. > > - Fix minor grammatical errors. > > - Capitalize headers and correctly order heading adornments. > > - Use 'Passed by reference' uniformly. > > - Update pointer documentation around %px specifier. > > - Fix erroneous double backticks (to commas). > > - Simplify documentation for kobject. > > - Convert lib/vsnprintf.c function docs to use kernel-docs and > > include in Documentation/printk-formats.rst > > > > Signed-off-by: Tobin C. Harding > > Some comments from a quick review: > > - I would just put this into the core-api manual; we don't need to create >a separate section for printk formats. Cool, I was hoping you'd give some direction on this. thanks. > - I agree with Markus and others about the table. I think I would go a >little further and encourage observance of the "use minimal markup" >rule. Lots of ``double backticks`` make for slightly nicer HTML/PDF >output, but they come at the expense of plain-text readability, which >is something we really don't want to sacrifice. Great. I personally don't read docs in HTML/PDF so I like this ruling. > - The vsprintf.c part is probably not for me to take, so it should be >split out into a separate patch. I'm much less experienced than you Jon so please say if I am wrong but since the rst file depends on the changes to vsprintf.c wouldn't it be better if the changes went into the mainline together. I can split it into a two patch set if that is cleaner but putting the two patches through different trees seems like a bad idea because of the dependency. For what it's worth, I don't believe lib/vsprintf.c has a maintainer. Linus took changes to that file from my tree just recently. I don't know how this stuff works though in regards to merge conflicts. (Please take everything I say here with a pinch of salt since I have only maintained a tree for a few weeks now.) thanks, Tobin. -- 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] doc: convert printk-formats.txt to rst
On Wed, Dec 06, 2017 at 10:18:49AM -0800, Randy Dunlap wrote:
Thanks for your comments Randy.
> On 12/05/2017 05:45 PM, Tobin C. Harding wrote:
> > Documentation/printk-formats.txt is a candidate for conversion to
> > ReStructuredText format. Some effort has already been made to do this
> > conversion even thought the suffix is currently .txt
> >
> > Changes required to complete conversion
> >
> > - Add double backticks where needed.
> > - Add entry to Documentation/index.rst
> > - Use flat-table instead of ASCII table.
> > - Fix minor grammatical errors.
> > - Capitalize headers and correctly order heading adornments.
>
> That's a style choice and an unneeded change (referring to Capitalize
> headers).
No worries, will revert.
> > - Use 'Passed by reference' uniformly.
> > - Update pointer documentation around %px specifier.
> > - Fix erroneous double backticks (to commas).
> > - Simplify documentation for kobject.
> > - Convert lib/vsnprintf.c function docs to use kernel-docs and
> > include in Documentation/printk-formats.rst
>
> good idea.
>
> >
> > Signed-off-by: Tobin C. Harding
> > ---
> >
> > The last two need special reviewing please. In particular the conversion
> > of kernel-docs in vsnprintf.c attempt was made to reduce documentation
> > duplication with comments in the source code being simplified in order
> > to be suitable for inclusion in Documentation/printk-formats.rst
> >
> > I used -M when formatting the patch. If you don't like the diff with
> > this flag just holla.
> >
> > thanks,
> > Tobin.
> >
> > Documentation/index.rst| 10 +
> > .../{printk-formats.txt => printk-formats.rst} | 295
> > -
> > lib/vsprintf.c | 160 +--
> > 3 files changed, 235 insertions(+), 230 deletions(-)
> > rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
>
> > diff --git a/Documentation/printk-formats.txt
> > b/Documentation/printk-formats.rst
> > similarity index 61%
> > rename from Documentation/printk-formats.txt
> > rename to Documentation/printk-formats.rst
> > index aa0a776c817a..51449d213748 100644
> > --- a/Documentation/printk-formats.txt
> > +++ b/Documentation/printk-formats.rst
> > @@ -1,6 +1,6 @@
> > -=
> > -How to get printk format specifiers right
> > -=
> > +=
> > +How to Get ``printk`` Format Specifiers Right
> > +=
> >
> > :Author: Randy Dunlap
> > :Author: Andrew Murray
> > @@ -8,56 +8,91 @@ How to get printk format specifiers right
> > Integer types
> > =
> >
> > -::
> > +For printing integer types, we have the following format specifiers:
> > +
> > + .. flat-table::
> > + :widths: 2 2
> > +
> > + * - **Type**
> > + - **Specifier**
> > +
> > + * - ``int``
> > +- ``%d`` or ``%x``
> > +
> > + * - ``unsigned int``
> > + - ``%u`` or ``%x``
> > +
> > + * - ``long``
> > + - ``%ld`` or ``%lx``
> > +
> > + * - ``unsigned long``
> > + - ``%lu`` or ``%lx``
> > +
> > + * - ``long long``
> > + - ``%lld`` or ``%llx``
> >
> > - If variable is of Type, use printk format specifier:
> > -
> > - int %d or %x
> > - unsigned int%u or %x
> > - long%ld or %lx
> > - unsigned long %lu or %lx
> > - long long %lld or %llx
> > - unsigned long long %llu or %llx
> > - size_t %zu or %zx
> > - ssize_t %zd or %zx
> > - s32 %d or %x
> > - u32 %u or %x
> > - s64 %lld or %llx
> > - u64 %llu or %llx
> > -
> > -If is dependent on a config option for its size (e.g., ``sector_t``,
> > + * - ``unsigned long long``
> > + - ``%llu`` or ``%llx``
> > +
> > + * - ``size_t``
> > + - ``%zu`` or ``%zx``
> > +
> > + * - ``ssize_t``
> > + - ``%zd`` or ``%zx``
> > +
> > + * - ``s32``
> > + - ``%d`` or ``%x``
> > +
> > + * - ``u32``
> > + - ``%u`` or ``%x``
> > +
> > + * - ``s64``
> > + - ``%lld`` or ``%llx``
> > +
> > + * - ``u64``
> > + - ``%llu`` or ``%llx``
> > +
> > +
> > +If is dependent on a config option for its size (e.g.,
> > ``sector_t``,
> > ``blkcnt_t``) or is architecture-dependent for its size (e.g.,
> > ``tcflag_t``),
> > use a format specifier of its largest possible type and explicitly cast to
> > it.
> >
> > Example::
> >
> > - printk("test: sector number/total blocks: %llu/%llu\n",
> > - (unsigned long long)sector, (unsigned long long)blockcount);
> > + printk("test: tota
Re: [PATCH] doc: convert printk-formats.txt to rst
On Wed, 6 Dec 2017 12:45:29 +1100 "Tobin C. Harding" wrote: > Documentation/printk-formats.txt is a candidate for conversion to > ReStructuredText format. Some effort has already been made to do this > conversion even thought the suffix is currently .txt > > Changes required to complete conversion > > - Add double backticks where needed. > - Add entry to Documentation/index.rst > - Use flat-table instead of ASCII table. > - Fix minor grammatical errors. > - Capitalize headers and correctly order heading adornments. > - Use 'Passed by reference' uniformly. > - Update pointer documentation around %px specifier. > - Fix erroneous double backticks (to commas). > - Simplify documentation for kobject. > - Convert lib/vsnprintf.c function docs to use kernel-docs and > include in Documentation/printk-formats.rst > > Signed-off-by: Tobin C. Harding Some comments from a quick review: - I would just put this into the core-api manual; we don't need to create a separate section for printk formats. - I agree with Markus and others about the table. I think I would go a little further and encourage observance of the "use minimal markup" rule. Lots of ``double backticks`` make for slightly nicer HTML/PDF output, but they come at the expense of plain-text readability, which is something we really don't want to sacrifice. - The vsprintf.c part is probably not for me to take, so it should be split out into a separate patch. Thanks for working on this, jon -- 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] doc: convert printk-formats.txt to rst
On 12/05/2017 05:45 PM, Tobin C. Harding wrote:
> Documentation/printk-formats.txt is a candidate for conversion to
> ReStructuredText format. Some effort has already been made to do this
> conversion even thought the suffix is currently .txt
>
> Changes required to complete conversion
>
> - Add double backticks where needed.
> - Add entry to Documentation/index.rst
> - Use flat-table instead of ASCII table.
> - Fix minor grammatical errors.
> - Capitalize headers and correctly order heading adornments.
That's a style choice and an unneeded change (referring to Capitalize headers).
> - Use 'Passed by reference' uniformly.
> - Update pointer documentation around %px specifier.
> - Fix erroneous double backticks (to commas).
> - Simplify documentation for kobject.
> - Convert lib/vsnprintf.c function docs to use kernel-docs and
> include in Documentation/printk-formats.rst
good idea.
>
> Signed-off-by: Tobin C. Harding
> ---
>
> The last two need special reviewing please. In particular the conversion
> of kernel-docs in vsnprintf.c attempt was made to reduce documentation
> duplication with comments in the source code being simplified in order
> to be suitable for inclusion in Documentation/printk-formats.rst
>
> I used -M when formatting the patch. If you don't like the diff with
> this flag just holla.
>
> thanks,
> Tobin.
>
> Documentation/index.rst| 10 +
> .../{printk-formats.txt => printk-formats.rst} | 295
> -
> lib/vsprintf.c | 160 +--
> 3 files changed, 235 insertions(+), 230 deletions(-)
> rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
> diff --git a/Documentation/printk-formats.txt
> b/Documentation/printk-formats.rst
> similarity index 61%
> rename from Documentation/printk-formats.txt
> rename to Documentation/printk-formats.rst
> index aa0a776c817a..51449d213748 100644
> --- a/Documentation/printk-formats.txt
> +++ b/Documentation/printk-formats.rst
> @@ -1,6 +1,6 @@
> -=
> -How to get printk format specifiers right
> -=
> +=
> +How to Get ``printk`` Format Specifiers Right
> +=
>
> :Author: Randy Dunlap
> :Author: Andrew Murray
> @@ -8,56 +8,91 @@ How to get printk format specifiers right
> Integer types
> =
>
> -::
> +For printing integer types, we have the following format specifiers:
> +
> + .. flat-table::
> + :widths: 2 2
> +
> + * - **Type**
> + - **Specifier**
> +
> + * - ``int``
> +- ``%d`` or ``%x``
> +
> + * - ``unsigned int``
> + - ``%u`` or ``%x``
> +
> + * - ``long``
> + - ``%ld`` or ``%lx``
> +
> + * - ``unsigned long``
> + - ``%lu`` or ``%lx``
> +
> + * - ``long long``
> + - ``%lld`` or ``%llx``
>
> - If variable is of Type, use printk format specifier:
> -
> - int %d or %x
> - unsigned int%u or %x
> - long%ld or %lx
> - unsigned long %lu or %lx
> - long long %lld or %llx
> - unsigned long long %llu or %llx
> - size_t %zu or %zx
> - ssize_t %zd or %zx
> - s32 %d or %x
> - u32 %u or %x
> - s64 %lld or %llx
> - u64 %llu or %llx
> -
> -If is dependent on a config option for its size (e.g., ``sector_t``,
> + * - ``unsigned long long``
> + - ``%llu`` or ``%llx``
> +
> + * - ``size_t``
> + - ``%zu`` or ``%zx``
> +
> + * - ``ssize_t``
> + - ``%zd`` or ``%zx``
> +
> + * - ``s32``
> + - ``%d`` or ``%x``
> +
> + * - ``u32``
> + - ``%u`` or ``%x``
> +
> + * - ``s64``
> + - ``%lld`` or ``%llx``
> +
> + * - ``u64``
> + - ``%llu`` or ``%llx``
> +
> +
> +If is dependent on a config option for its size (e.g.,
> ``sector_t``,
> ``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
> use a format specifier of its largest possible type and explicitly cast to
> it.
>
> Example::
>
> - printk("test: sector number/total blocks: %llu/%llu\n",
> - (unsigned long long)sector, (unsigned long long)blockcount);
> + printk("test: total blocks: %llu\n", (unsigned long long)blockcount);
>
> -Reminder: ``sizeof()`` result is of type ``size_t``.
> +Reminder: ``sizeof()`` returns type ``size_t``.
>
> -The kernel's printf does not support ``%n``. For obvious reasons, floating
> +The kernel's printf does not support ``%n``. For obvious reasons floating
> point formats (``%e, %f,
Re: [PATCH] doc: convert printk-formats.txt to rst
On 12/05/2017 11:35 PM, Joe Perches wrote: > On Wed, 2017-12-06 at 08:11 +0100, Markus Heiser wrote: >>> Am 06.12.2017 um 02:45 schrieb Tobin C. Harding : >>> Documentation/printk-formats.txt is a candidate for conversion to >>> ReStructuredText format. Some effort has already been made to do this >>> conversion even thought the suffix is currently .txt > [] >> just a question .. might it be better we stay with ASCII table >> in cases like this. I guess this table won't changed often. >> The flat-table directive is good for big and therefore frequently >> changed tables where a small precise diff reduce the patch. >> But flat-table is also hard to read in plain text. Its a balancing >> and thats my opinion, lets hear what other say ... > > I think the proposed conversion is unreadable > and the original table quite clear. Agree. -- ~Randy -- 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] doc: convert printk-formats.txt to rst
On Wed, 2017-12-06 at 08:11 +0100, Markus Heiser wrote: > > Am 06.12.2017 um 02:45 schrieb Tobin C. Harding : > > Documentation/printk-formats.txt is a candidate for conversion to > > ReStructuredText format. Some effort has already been made to do this > > conversion even thought the suffix is currently .txt [] > just a question .. might it be better we stay with ASCII table > in cases like this. I guess this table won't changed often. > The flat-table directive is good for big and therefore frequently > changed tables where a small precise diff reduce the patch. > But flat-table is also hard to read in plain text. Its a balancing > and thats my opinion, lets hear what other say ... I think the proposed conversion is unreadable and the original table quite clear. -- 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] doc: convert printk-formats.txt to rst
> Am 06.12.2017 um 02:45 schrieb Tobin C. Harding : > > Documentation/printk-formats.txt is a candidate for conversion to > ReStructuredText format. Some effort has already been made to do this > conversion even thought the suffix is currently .txt > > Changes required to complete conversion > > - Add double backticks where needed. > - Add entry to Documentation/index.rst > - Use flat-table instead of ASCII table. [...] > += > +How to Get ``printk`` Format Specifiers Right > += > > :Author: Randy Dunlap > :Author: Andrew Murray > @@ -8,56 +8,91 @@ How to get printk format specifiers right > Integer types > = > > -:: > +For printing integer types, we have the following format specifiers: > + > + .. flat-table:: > + :widths: 2 2 > + > + * - **Type** > + - **Specifier** > + > + * - ``int`` > +- ``%d`` or ``%x`` > + > + * - ``unsigned int`` > + - ``%u`` or ``%x`` > + > + * - ``long`` > + - ``%ld`` or ``%lx`` > + > + * - ``unsigned long`` > + - ``%lu`` or ``%lx`` > + > + * - ``long long`` > + - ``%lld`` or ``%llx`` > > - If variable is of Type, use printk format specifier: > - > - int %d or %x > - unsigned int%u or %x > - long%ld or %lx > - unsigned long %lu or %lx > - long long %lld or %llx > - unsigned long long %llu or %llx > - size_t %zu or %zx > - ssize_t %zd or %zx > - s32 %d or %x > - u32 %u or %x > - s64 %lld or %llx > - u64 %llu or %llx > - > -If is dependent on a config option for its size (e.g., ``sector_t``, > + * - ``unsigned long long`` > + - ``%llu`` or ``%llx`` > + > + * - ``size_t`` > + - ``%zu`` or ``%zx`` > + > + * - ``ssize_t`` > + - ``%zd`` or ``%zx`` > + > + * - ``s32`` > + - ``%d`` or ``%x`` > + > + * - ``u32`` > + - ``%u`` or ``%x`` > + > + * - ``s64`` > + - ``%lld`` or ``%llx`` > + > + * - ``u64`` > + - ``%llu`` or ``%llx`` > + > + Thanks! just a question .. might it be better we stay with ASCII table in cases like this. I guess this table won't changed often. The flat-table directive is good for big and therefore frequently changed tables where a small precise diff reduce the patch. But flat-table is also hard to read in plain text. Its a balancing and thats my opinion, lets hear what other say ... -- Markus 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
[PATCH] doc: convert printk-formats.txt to rst
Documentation/printk-formats.txt is a candidate for conversion to
ReStructuredText format. Some effort has already been made to do this
conversion even thought the suffix is currently .txt
Changes required to complete conversion
- Add double backticks where needed.
- Add entry to Documentation/index.rst
- Use flat-table instead of ASCII table.
- Fix minor grammatical errors.
- Capitalize headers and correctly order heading adornments.
- Use 'Passed by reference' uniformly.
- Update pointer documentation around %px specifier.
- Fix erroneous double backticks (to commas).
- Simplify documentation for kobject.
- Convert lib/vsnprintf.c function docs to use kernel-docs and
include in Documentation/printk-formats.rst
Signed-off-by: Tobin C. Harding
---
The last two need special reviewing please. In particular the conversion
of kernel-docs in vsnprintf.c attempt was made to reduce documentation
duplication with comments in the source code being simplified in order
to be suitable for inclusion in Documentation/printk-formats.rst
I used -M when formatting the patch. If you don't like the diff with
this flag just holla.
thanks,
Tobin.
Documentation/index.rst| 10 +
.../{printk-formats.txt => printk-formats.rst} | 295 -
lib/vsprintf.c | 160 +--
3 files changed, 235 insertions(+), 230 deletions(-)
rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb7f1ba5b3b1..83ace60efbe7 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -87,6 +87,16 @@ implementation.
sh/index
+Miscellaneous documentation
+---
+
+These guides contain general information useful when writing kernel code.
+
+.. toctree::
+ :maxdepth: 1
+
+ printk-formats
+
Korean translations
---
diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.rst
similarity index 61%
rename from Documentation/printk-formats.txt
rename to Documentation/printk-formats.rst
index aa0a776c817a..51449d213748 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/printk-formats.rst
@@ -1,6 +1,6 @@
-=
-How to get printk format specifiers right
-=
+=
+How to Get ``printk`` Format Specifiers Right
+=
:Author: Randy Dunlap
:Author: Andrew Murray
@@ -8,56 +8,91 @@ How to get printk format specifiers right
Integer types
=
-::
+For printing integer types, we have the following format specifiers:
+
+ .. flat-table::
+ :widths: 2 2
+
+ * - **Type**
+ - **Specifier**
+
+ * - ``int``
+- ``%d`` or ``%x``
+
+ * - ``unsigned int``
+ - ``%u`` or ``%x``
+
+ * - ``long``
+ - ``%ld`` or ``%lx``
+
+ * - ``unsigned long``
+ - ``%lu`` or ``%lx``
+
+ * - ``long long``
+ - ``%lld`` or ``%llx``
- If variable is of Type, use printk format specifier:
-
- int %d or %x
- unsigned int%u or %x
- long%ld or %lx
- unsigned long %lu or %lx
- long long %lld or %llx
- unsigned long long %llu or %llx
- size_t %zu or %zx
- ssize_t %zd or %zx
- s32 %d or %x
- u32 %u or %x
- s64 %lld or %llx
- u64 %llu or %llx
-
-If is dependent on a config option for its size (e.g., ``sector_t``,
+ * - ``unsigned long long``
+ - ``%llu`` or ``%llx``
+
+ * - ``size_t``
+ - ``%zu`` or ``%zx``
+
+ * - ``ssize_t``
+ - ``%zd`` or ``%zx``
+
+ * - ``s32``
+ - ``%d`` or ``%x``
+
+ * - ``u32``
+ - ``%u`` or ``%x``
+
+ * - ``s64``
+ - ``%lld`` or ``%llx``
+
+ * - ``u64``
+ - ``%llu`` or ``%llx``
+
+
+If is dependent on a config option for its size (e.g., ``sector_t``,
``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
use a format specifier of its largest possible type and explicitly cast to it.
Example::
- printk("test: sector number/total blocks: %llu/%llu\n",
- (unsigned long long)sector, (unsigned long long)blockcount);
+ printk("test: total blocks: %llu\n", (unsigned long long)blockcount);
-Reminder: ``sizeof()`` result is of type ``size_t``.
+Reminder: ``sizeof()`` returns type ``size_t``.
-The kernel's printf does not support ``%n``. For obvious reasons, floating
+The kernel's pri
