DOC: add printk-formats.txt

Add printk-formats.txt so that we don't have to keep fixing the
same things over and over again.  <wishful thinking>

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: Alexey Dobriyan <adobriyan@gmail.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index edef85ce1195e0a0e98f2f135d4051c1b5844947..50f99eab0e1fae2b825c8a9339d055877c0c3f7b 100644 (file)
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -290,6 +290,8 @@ powerpc/
        - directory with info on using Linux with the PowerPC.
 preempt-locking.txt
        - info on locking under a preemptive kernel.
+printk-formats.txt
+       - how to get printk format specifiers right
 prio_tree.txt
        - info on radix-priority-search-tree use for indexing vmas.
 ramdisk.txt

diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt
new file mode 100644 (file)
index 0000000..1b5a5dd
--- /dev/null
+++ b/Documentation/printk-formats.txt
@@ -0,0 +1,35 @@
+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
+
+Raw pointer value SHOULD be printed with %p.
+
+u64 SHOULD be printed with %llu/%llx, (unsigned long long):
+
+       printk("%llu", (unsigned long long)u64_var);
+
+s64 SHOULD be printed with %lld/%llx, (long long):
+
+       printk("%lld", (long long)s64_var);
+
+If <type> is dependent on a config option for its size (e.g., sector_t,
+blkcnt_t, phys_addr_t, resource_size_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.
+
+Thank you for your cooperation and attention.
+
+
+By Randy Dunlap <rdunlap@xenotime.net>