
This is the "poor programmer's" printf implementation. It is meant to
be used in small environments, like microcontrollers or soft
processors.  Actually, that's where I needed it years ago and where
I'm still using it.

It is a complete printf (it only misses the %[charset] feature, and
obviously floating point support). It relies on an external "puts"
function for the actual output; the full version also needs strnlen.
Unfortunately, the stdio puts adds a trailing newline (while most
embedded implementations do not). The sprintf function is included
as pp_sprintf.

The printf engine, vsprintf(), comes in four flavours:

In summary:

    - the "full" version is a normal printf (GPL2, from older Linux kernel)
      (as a build-time option, it supports int64_t items, as "ll" or "L")

    - the "xint" version accepts all formats and prints hex and int only

    - the "mini" version accepts all formats but only prints hex (GPL2)

    - the "none" version accepts all formats and prints nothing (PD)

The version you use can be selected at compile time, so you can
develop with a full-featured printf and install the minimal one in
production, saving a few kilobytes and still not loosing information
in messages.  At the end I list compiled sizes for a few use cases.

While I use this very code in several projects, the only example here
is a stupid main that prints something.  You are expected to pick these
files and copy them to your projects, rather than use this "package"
as a system library.


	The full implementation in detail
	=================================

This comes from u-boot, which means that it is an earlier printf as
used in the Linux kernel. It is licensed according to the GNU GPL
version 2.  It includes all formats and prefixes and so on. It is
clearly bugless because everybody is using it.

In July 2014 I made some changes, which includes adding 64-bit items,
but the feature is disabled by default. There is a whole section later
in this file about this.

It is selected at compile time by setting the make variable
"CONFIG_PRINTF_FULL" to "y". You can do that in the environment,
or use Kconfig in your application.

(The Makefile selects this by default if you set nothing in the
environment or make variables)

Example calls (example-printf.c):

    pp_printf("integer %5i %5i %05i\n", 1024, 666, 53);
    pp_printf("octal   %5o %5o %05o\n", 1024, 666, 53);
    pp_printf("hex     %5x %5x %05x\n", 1024, 666, 53);
    pp_printf("HEX etc %5X %+5d %-5i\n", 1024, 666, 53);
    pp_printf("neg     %5i %05i %05x\n", -5, -10, -15);
    pp_printf("char: %c  string %s %5s %.5s\n", 65, "foo", "foo",
              "verylongstring");
    pp_printf("hour    %02d:%02d:%02d\n", 12, 9, 0);

Result (as you see, format modifiers are respected):

    integer  1024   666 00053
    octal    2000  1232 00065
    hex       400   29a 00035
    HEX etc   400  +666 53
    neg        -5 -0010 fffffff1
    char: A  string foo   foo veryl
    hour    12:09:00

Footprint: 1400-3200 bytes, plus 100-400 bytes for the frontend.

(With the 2014 changes the footprint is a few hundred bytes less, but
I lacked the time to make comprehensive builds; if you enable 64-bit
support, you'll get a size impact of a few hunderd bytes: for ARM,
around 200 bytes in vsprintf-full plus 200 for div64.o).

	The xint implementation in detail
	================================

This prints correctly "%c", "%s", "%i", "%x". Formats "%u" and "%d"
are synonyms of "%i", and "%p" is a synonym for "%x".  The only
supported attributes are '0' and a one-digit width (e.g.: "%08x"
works).  I personally use it a lot but I don't like it much, because it
is not powerful enough nor low-level as real hacker's too should be.
However, it matches the requirement of some projects with a little
user interface, where the "full" code reveals too large and the "mini"
code is too unfair to the reader.  To compile it and link the example,
please set "CONFIG_PRINTF_XINT=y" in your environment or Makefile.

This is the result of the example. As expected, data is aligned and
has leading zeroes when requested, but bot other formats are obeyed:

    integer  1024   666 00053
    octal    2000  1232 00065
    hex       400   29a 00035
    HEX etc   400   666    53
    neg        -5 -0010 fffffff1
    char: A  string foo foo verylongstring
    hour    12:09:00

Footprint: 350-800 bytes, plus 100-400 bytes for the frontend


	The miminal implementation in detail
	===================================

It is derived from the full one. I left all format parsing intact, but
only print "%s" and "%c". Everything else is printed as hex numbers
like "<badc0ffe>". This means your 47 printed as "%03i" will be output
as "<0000002f>" instead of "047".  Still, the standard format is
accepted without errors and no information is lost.

I have made no checks nor reasoning about 32-bit vs 64-bit. I only
used it on 32-bit computers and never printed "long long". Now that it
is published, I have an incentive to do it, though.

It is selected at compile time by setting CONFIG_PRINTF_MINI=y as a
make variable, possibly inherited by the environment.  It is licensed
as GPL version 2 because it's derived from the full one -- I left the
parsing as I found in there.

Result of example-printf (you can "make CONFIG_PRINTF_MINI=y):

    integer <00000400> <0000029a> <00000035>
    octal   <00000400> <0000029a> <00000035>
    hex     <00000400> <0000029a> <00000035>
    HEX etc <00000400> <0000029a> <00000035>
    neg     <fffffffb> <fffffff6> <fffffff1>
    char: A  string foo foo verylongstring
    hour    <0000000c>:<00000009>:<00000000>

As promised, %c and %s is printed correctly, but without obeying the
format modifiers, but all integer value are printed in hex.

Footprint: 200-600 bytes, plus 100-400 for the frontend.


	The empty implementation in detail
	==================================

The empty implementation, called "none" to respect the 4-letter
pattern of "full" and "mini" doesn't parse any format. It simply
prints the format string and nothing more.  This allows to keep the
most important messages, like the welcome string or a "Panic" string,
while saving code space.

It is selected at compile time by setting CONFIG_PRINTF_NONE.

Result of example-printf (you can "make CONFIG_PRINTF_MINI=y):

    integer %5i %5i %05i
    octal   %5o %5o %05o
    hex     %5x %5x %05x
    HEX etc %5X %+5d %-5i
    neg     %5i %05i %05x
    char: %c  string %s %5s %.5s
    hour    %02d:%02d:%02d

Footprint: 25-110 bytes, plus 100-400 for the frontend.

If you want to remove all printf overhead in production, you should
use a preprocessor macro to completely kill the printf calls. This
would save you the parameter-passing overhead in the caller and all
the constant strings in .rodata.  I don't support this in the package,
though, and I discourage from doing it, for the usual
preprocessor-related reasons.

	int64_t support
	===============

vsprintf-full.c now supports printing 64-bit items. It works in all
platforms, including the 16-bit AVR CPU.  The feature is disabled by
default because it has run-time impact (all integer conversions are
performed using 64-bit division.

Moreover, 64-bit supports requires 64-bit division. As customary in
the kernel/bootloader world we avoid picking the libgcc
implementation, and rely on the smaller __div64_32() function,
instead, which only supports a 32-bit divisor and thus a 32-bit
remainder; but this is all we need.  The function is available in
"lib64.c", by Bernardo Innocenti, which is used in the kernel and many
other projects.

So, to enable 64-bit support in pp-printf, please use

   CONFIG_PRINTF_64BIT=y

in your environment or command-line of make. If your project uses
Kconfig, you'll rely on it instead (I'm running pp-printf in 3
Kconfig-based projects and it works great).

If you already have __div64_32() in your project, you are done:
vsprintf-full.o will have an undefined symbol, that your final link
will resolve.  If you miss the function, you can use the local
version. To do that, set

   CONFIG_PRINTF_LOCAL_DIV64=y

in your environment or the command line of make.

The test program for 64-bit formats is not built by default. To build
it, you should

   make CONFIG_PRINTF_64BIT=y example-printf64

This automatically picks div64.o: you'll get a link error if you also
set CONFIG_PRINTF_LOCAL_DIV64=y. This is not a problem as the test
is meant to be run locally, only once or so.

The test prints one thousand, one million and so on using the various
formats, ending with the maximum positive and maximum negative::

    positive:                     1000
    negative:                    -1000
    neg-unsigned: 18446744073709550616
    pos-hex:        0x00000000000003e8
    pos-HEX:        0x00000000000003E8
    neg-hex:        0xfffffffffffffc18

    [...]

    positive:      1000000000000000000
    negative:     -1000000000000000000
    neg-unsigned: 17446744073709551616
    pos-hex:        0x0de0b6b3a7640000
    pos-HEX:        0x0DE0B6B3A7640000
    neg-hex:        0xf21f494c589c0000

    max positive:  9223372036854775807
    max negative: -9223372036854775808

You may want to verify with your own target platform, before using the
code in production (you can avoid that if you trust me, but I wouldn't
blindly trust programmers, in general).


	Footprint of the various implementations
	========================================

NOTE: these figures refer to the 2012 master. The "full"
implementation is now a few hundred bytes smaller.
Also, I made no measures for the 64-bit version, which adds a few
hundred bytes (and run-time overhead of every integer print).

This table excludes the static buffer (256 in .bss by default) and
only lists the code size (command "size", column "text"), compiled
with -Os as for this Makefile.

printf.o is the frontend and is linked in all four configurations,
the other ones are exclusive one another:

                        printf.o       full  xint  mini  none

   x86, gcc-4.4.5           87         1715   476   258    48
   x86-64, gcc-4.4.5       418         2325   712   433    77
   x86, gcc-4.6.2          255         2210   577   330   110
   arm, gcc-4.2.2          156         2408   684   356    52
   arm, gcc-4.5.2          128         2235   645   353    44
   arm, gcc-4.5.2 thumb2    80         1443   373   209    26
   lm32, gcc-4.5.3         196         3228   792   576    44
   mips, gcc-4.4.1         184         2616   824   504    72
   powerpc, gcc-4.4.1      328         2895   881   521    48
   coldfire, gcc-4.4.1      96         2025   485   257    42
   sh4, gcc-4.4.1          316         2152   608   408    34
