Re: [PATCH v2] doc: convert printk-formats.txt to rst
On Thu, Dec 07, 2017 at 02:30:53PM -0700, Jonathan Corbet wrote: > On Fri, 8 Dec 2017 08:21:09 +1100 > "Tobin C. Harding" wrote: > > > Unless I'm a proper wombat that entry is not in the mainline MAINTAINERS > > file. > > Um...from current git... Foiled by me automatic Emacs buffer syncing (maggit), who knows what version of MAINTAINERS I was looking at. Please accept my apologies. > DOCUMENTATION > M:Jonathan Corbet > L:linux-...@vger.kernel.org > S:Maintained > F:Documentation/ > F:scripts/kernel-doc > X:Documentation/ABI/ > X:Documentation/devicetree/ > X:Documentation/acpi > X:Documentation/power > X:Documentation/spi > X:Documentation/media > T:git git://git.lwn.net/linux.git docs-next > > I've never called anybody a "wombat" before and don't plan to start now, > but...you might want to take another look? It's a totally acceptable term in the Australian vernacular, similar to calling someone a 'goose'. A perfectly pleasant form of abuse :) thanks, Tobin.
Re: [PATCH v2] doc: convert printk-formats.txt to rst
On Thu, Dec 07, 2017 at 08:44:37AM +0100, Markus Heiser wrote: > > > Am 07.12.2017 um 06:49 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 > > > [...] > > > > Signed-off-by: Tobin C. Harding > > --- > > > > v2: > > - Revert to use ASCII table. > > - Implement (or revert) changes as suggested by Randy Dunlap. > > - Change file location to core-api/ (inc required index changes) > > - Remove some of the double back ticks. > > > > Last two suggested by Jonathan Corbet. > > > > Hm, can't apply v2 on Jon's docs-next .. is the v2 patch on top of your v1? Ok, this doesn't apply because of a commit Linus did to lib/vsprintf.c Not that that matters because it has been pointed out in another thread that the kptr_restrict documentation is incomplete. Please drop, will amend and re-spin. thanks, Tobin.
Re: [PATCH v2] doc: convert printk-formats.txt to rst
On Fri, 2017-12-08 at 08:21 +1100, Tobin C. Harding wrote: > On Thu, Dec 07, 2017 at 01:52:56PM -0700, Jonathan Corbet wrote: > > On Fri, 8 Dec 2017 07:44:34 +1100 > > "Tobin C. Harding" wrote: > > > > > Where is Jon's tree hosted please, I don't see it on kernel.org > > > > From the MAINTAINERS file: > > > > T: git git://git.lwn.net/linux.git docs-next > > Unless I'm a proper wombat You are not proper until you have the cosplay attire. > that entry is not in the mainline MAINTAINERS file. $ ./scripts/get_maintainer.pl --sections -f Documentation/ DOCUMENTATION M: Jonathan Corbet L: linux-...@vger.kernel.org S: Maintained F: Documentation/ F: scripts/kernel-doc X: Documentation/ABI/ X: Documentation/devicetree/ X: Documentation/acpi/ X: Documentation/power/ X: Documentation/spi/ X: Documentation/media/ T: git git://git.lwn.net/linux.git docs-next THE REST M: Linus Torvalds L: linux-kernel@vger.kernel.org Q: http://patchwork.kernel.org/project/LKML/list/ T: git git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git S: Buried alive in reporters F: * F: */
Re: [PATCH v2] doc: convert printk-formats.txt to rst
On Fri, 8 Dec 2017 08:21:09 +1100 "Tobin C. Harding" wrote: > Unless I'm a proper wombat that entry is not in the mainline MAINTAINERS > file. Um...from current git... DOCUMENTATION M: Jonathan Corbet L: linux-...@vger.kernel.org S: Maintained F: Documentation/ F: scripts/kernel-doc X: Documentation/ABI/ X: Documentation/devicetree/ X: Documentation/acpi X: Documentation/power X: Documentation/spi X: Documentation/media T: git git://git.lwn.net/linux.git docs-next I've never called anybody a "wombat" before and don't plan to start now, but...you might want to take another look? > Adding a remote using the above URL > > # Jon's docs tree > [remote "corbet"] > url = git://git.lwn.net/linux.git > fetch = +refs/heads/*:refs/remotes/corbet/* > pushurl = no_push > > > fails to git fetch, but ping showed me > > git://git3.lwn.net/linux.git > > Using that URL, fetched just fine. $ host git.lwn.net git.lwn.net is an alias for git3.lwn.net. Either should work just fine (except that git3 will almost certainly break someday). Not sure why you're having trouble there. jon
Re: [PATCH v2] doc: convert printk-formats.txt to rst
On Thu, Dec 07, 2017 at 01:52:56PM -0700, Jonathan Corbet wrote: > On Fri, 8 Dec 2017 07:44:34 +1100 > "Tobin C. Harding" wrote: > > > Where is Jon's tree hosted please, I don't see it on kernel.org > > From the MAINTAINERS file: > > T: git git://git.lwn.net/linux.git docs-next Just in case it is of any use to you Jon Adding a remote using the above URL # Jon's docs tree [remote "corbet"] url = git://git.lwn.net/linux.git fetch = +refs/heads/*:refs/remotes/corbet/* pushurl = no_push fails to git fetch, but ping showed me git://git3.lwn.net/linux.git Using that URL, fetched just fine. thanks, Tobin.
Re: [PATCH v2] doc: convert printk-formats.txt to rst
On Thu, Dec 07, 2017 at 01:52:56PM -0700, Jonathan Corbet wrote: > On Fri, 8 Dec 2017 07:44:34 +1100 > "Tobin C. Harding" wrote: > > > Where is Jon's tree hosted please, I don't see it on kernel.org > > From the MAINTAINERS file: > > T: git git://git.lwn.net/linux.git docs-next Unless I'm a proper wombat that entry is not in the mainline MAINTAINERS file. You have two entries CAFE CMOS INTEGRATED CAMERA CONTROLLER DRIVER OMNIVISION OV7670 SENSOR DRIVER but none for docs? thanks, Tobin.
Re: [PATCH v2] doc: convert printk-formats.txt to rst
On Thu, Dec 07, 2017 at 01:52:56PM -0700, Jonathan Corbet wrote: > On Fri, 8 Dec 2017 07:44:34 +1100 > "Tobin C. Harding" wrote: > > > Where is Jon's tree hosted please, I don't see it on kernel.org > > From the MAINTAINERS file: > > T: git git://git.lwn.net/linux.git docs-next > > jon Amateur hour at my house. thanks Jon, Tobin
Re: [PATCH v2] doc: convert printk-formats.txt to rst
On Fri, 8 Dec 2017 07:44:34 +1100 "Tobin C. Harding" wrote: > Where is Jon's tree hosted please, I don't see it on kernel.org >From the MAINTAINERS file: T: git git://git.lwn.net/linux.git docs-next jon
Re: [PATCH v2] doc: convert printk-formats.txt to rst
On Thu, Dec 07, 2017 at 08:44:37AM +0100, Markus Heiser wrote: > > > Am 07.12.2017 um 06:49 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 > > > [...] > > > > Signed-off-by: Tobin C. Harding > > --- > > > > v2: > > - Revert to use ASCII table. > > - Implement (or revert) changes as suggested by Randy Dunlap. > > - Change file location to core-api/ (inc required index changes) > > - Remove some of the double back ticks. > > > > Last two suggested by Jonathan Corbet. > > > > Hm, can't apply v2 on Jon's docs-next .. is the v2 patch on top of your v1? My mistake, it applies on top of the mainline commit: "ae64f9bd1d36 Linux 4.15-rc2"" Where is Jon's tree hosted please, I don't see it on kernel.org thanks, Tobin.
Re: [PATCH v2] doc: convert printk-formats.txt to rst
> Am 07.12.2017 um 06:49 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 > [...] > > Signed-off-by: Tobin C. Harding > --- > > v2: > - Revert to use ASCII table. > - Implement (or revert) changes as suggested by Randy Dunlap. > - Change file location to core-api/ (inc required index changes) > - Remove some of the double back ticks. > > Last two suggested by Jonathan Corbet. > Hm, can't apply v2 on Jon's docs-next .. is the v2 patch on top of your v1? If so, please take a look at our fabulously ;) documentation .. https://www.kernel.org/doc/html/latest/process/submitting-patches.html """ When you submit or resubmit a patch or patch series, include the complete patch description and justification for it. Don’t just say that this is version N of the patch (series). Don’t expect the subsystem maintainer to refer back to earlier patch versions or referenced URLs to find the patch description and put that into the patch. I.e., the patch (series) and its description should be self-contained. This benefits both the maintainers and reviewers. Some reviewers probably didn’t even receive earlier versions of the patch. """ -- Markus --
[PATCH v2] 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
- Move printk-formats.txt to core-api/printk-formats.rst
- Add entry to Documentation/core-api/index.rst
- Remove entry from Documentation/00-INDEX
- Fix minor grammatical errors.
- Order heading adornments as suggested by rst docs.
- 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
---
v2:
- Revert to use ASCII table.
- Implement (or revert) changes as suggested by Randy Dunlap.
- Change file location to core-api/ (inc required index changes)
- Remove some of the double back ticks.
Last two suggested by Jonathan Corbet.
This patch is quite a bit bigger because of removing the extra double
back ticks. It has been already (lightheartedly) observed that I may be
making more changes than necessary. The back ticks stuff may incur the
same reaction :)
Documentation/00-INDEX | 2 -
Documentation/core-api/index.rst | 1 +
.../printk-formats.rst}| 268 +++--
lib/vsprintf.c | 155 +---
4 files changed, 196 insertions(+), 230 deletions(-)
rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (59%)
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3bec49c33bbb..7023bfaec21c 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -346,8 +346,6 @@ prctl/
- directory with info on the priveledge control subsystem
preempt-locking.txt
- info on locking under a preemptive kernel.
-printk-formats.txt
- - how to get printk format specifiers right
process/
- how to work with the mainline kernel development process.
pps/
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d5bbe035316d..2f9df634a726 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -21,6 +21,7 @@ Core utilities
flexible-arrays
librs
genalloc
+ printk-formats
Interfaces for kernel debugging
===
diff --git a/Documentation/printk-formats.txt
b/Documentation/core-api/printk-formats.rst
similarity index 59%
rename from Documentation/printk-formats.txt
rename to Documentation/core-api/printk-formats.rst
index aa0a776c817a..f1262a617dec 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/core-api/printk-formats.rst
@@ -5,6 +5,7 @@ How to get printk format specifiers right
:Author: Randy Dunlap
:Author: Andrew Murray
+
Integer types
=
@@ -25,39 +26,49 @@ Integer types
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.
+
+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);
-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
-point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
+The kernel's printf does not support %n. Floating point formats (%e, %f,
+%g, %a) are also not recognized, for obvious reasons. Use of any
unsupported specifier or length qualifier results in a WARN and early
-return from vsnprintf.
-
-Raw pointer value SHOULD be printed with %p. The kernel supports
-the following extended format specifiers for pointer types:
+return from vsnprintf().
-Pointer Types
+Pointer types
=
-Pointers printed without a specifier extension (i.e unadorned %p) are
-hashed to give a unique identifier without leaking kernel addresses to user
-space. On 64 bit machines the first 32 bits are zeroed. If you _really_
-want the address see %px below.
+A raw pointer value may be printed with %p which will hash the address
+before printing. The Kernel also supports extended specifiers for printing
+pointers of different types.
+
+.. kernel-doc:: lib/vsprintf.c
+ :doc: Extended Format Pointer Specifiers
+
+
+Plain pointers
+--
::
