4.3 <pending: this is messy and incomplete> Library Routines

The following library routines are provided for your convenience.

stdio.h - Contains the following functions printf & sprintf these routines are developed by Martijn van Balen <balen@natlab.research.philips.com>.

%[flags][width][b|B|l|L]type

           flags: -        left justify output in specified field width
                 +        prefix output with +/- sign if output is signed type
                 space    prefix output with a blank if it's a signed positive value
          width:          specifies minimum number of characters outputted for numbers
                          or strings.
                          - For numbers, spaces are added on the left when needed.
                            If width starts with a zero character, zeroes and used
                            instead of spaces.
                          - For strings, spaces are are added on the left or right (when
                            flag '-' is used) when needed.
                         
          b/B:            byte argument (used by d, u, o, x, X)
          l/L:            long argument (used by d, u, o, x, X)
          type:  d        decimal number
                 u        unsigned decimal number
                 o        unsigned octal number
                 x        unsigned hexadecimal number (0-9, a-f)
                 X        unsigned hexadecimal number (0-9, A-F)
                 c        character
                 s        string (generic pointer)
                 p        generic pointer (I:data/idata, C:code, X:xdata, P:paged)
                 f        float (still to be implemented)

Also contains a very simple version of printf (printf_small). This simplified version of printf supports only the following formats.

format     output type     argument-type
%d         decimal       short/int
%ld        decimal       long
%hd        decimal       char
%x        hexadecimal    short/int
%lx       hexadecimal    long
%hx       hexadecimal    char
%o         octal         short/int
%lo        octal         long
%ho        octal         char
%c        character      char
%s        character     _generic pointer

The routine is very stack intesive, -stack-after-data parameter should be used when using this routine, the routine also takes about 1K of code space. It also expects an external function named putchar(char) to be present (this can be changed). When using the %s format the string / pointer should be cast to a generic pointer. eg.

printf_small(``my str %s, my int %d\n'',(char _generic *)mystr,myint);

• stdarg.h - contains definition for the following macros to be used for variable parameter list, note that a function can have a variable parameter list if and only if it is 'reentrant'

  va_list, va_start, va_arg, va_end.

• setjmp.h - contains defintion for ANSI setjmp & longjmp routines. Note in this case setjmp & longjmp can be used between functions executing within the same register bank, if long jmp is executed from a function that is using a different register bank from the function issuing the setjmp function, the results may be unpredictable. The jump buffer requires 3 bytes of data (the stack pointer & a 16 byte return address), and can be placed in any address space.
• stdlib.h - contains the following functions.

  atoi, atol.

• string.h - contains the following functions.

  strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn, strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset.

• ctype.h - contains the following routines.

  iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace, isxdigit, isalnum, isalpha.

• malloc.h - The malloc routines are developed by Dmitry S. Obukhov (dso@usa.net). These routines will allocate memory from the external ram. Here is a description on how to use them (as described by the author).

  //Example:
       //     #define DYNAMIC_MEMORY_SIZE 0x2000
       //     .....
       //     unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
       //     unsigned char xdata * current_buffer;
       //     .....
       //     void main(void)
       //     {
       //         ...
       //         init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
       //         //Now it's possible to use malloc.
       //         ...
       //         current_buffer = malloc(0x100);
       //

• serial.h - Serial IO routines are also developed by Dmitry S. Obukhov (dso@usa.net). These routines are interrupt driven with a 256 byte circular buffer, they also expect external ram to be present. Please see documentation in file SDCCDIR/sdcc51lib/serial.c. Note the header file ``serial.h'' MUST be included in the file containing the 'main' function.
• ser.h - Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMinds.com> these routines are more compact and faster. Please see documentation in file SDCCDIR/sdcc51lib/ser.c
• ser_ir.h - Another alternate set of serial routines provided by Josef Wolf <jw@raven.inka.de>, these routines do not use the external ram.
• reg51.h - contains register definitions for a standard 8051
• float.h - contains min, max and other floating point related stuff.

All library routines are compiled as -model-small, they are all non-reentrant, if you plan to use the large model or want to make these routines reentrant, then they will have to be recompiled with the appropriate compiler option.

Have not had time to do the more involved routines like printf, will get to them shortly.