6 LIBRARIES

This chapter contains the following sections:

Introduction
Building Libraries
Libraries Overview
Input/Output Functions
Header Files
C Libraries
C Library Implementation Details
C Library Interface Description
Printf and Scanf Formatting Routines
Run-time Library
Floating Point Library

6.1 Introduction

This chapter describes the library functions delivered with the compiler. Some functions (e.g. printf(), scanf() ) can be edited to match your needs. c563 comes with libraries in object format per memory model and with header files containing the appropriate prototype of the library functions. The library functions are also shipped in source code (C or assembly).

A number of standard operations within C are too complex to generate inline code for (e.g. 32 bit signed divide). These operations are implemented as run-time library functions. The run-time library routines are added to the C library.

The C libraries supplied with the compiler are suitable for -Mx (the default data space X memory). In the following cases you must rebuild the libraries to avoid conflicts:

Use the same options for both rebuilding the libraries as building your application.

The sources of these libraries and a makefile are included in the compiler package.

6.2 Rebuilding Libraries

Use the following procedure to rebuild the libraries for the c563 compiler (similar steps can be followed for the c56):

1. Check if the bin directory of the installed c563 product is included in your path environment setting. If it is not there you should add it.

2. In the directory lib\src you will find the library sources. For each type of library it also contains a subdirectory with a makefile for creating the specific library. Select the directory, depending on which library you want to build, and make this directory the working directory.

3. Edit the concerning makefile and add the new options to the line which defines CFLAGS. For example:

4. Type:

to build libraries for c563.

5. When building is finished you will find the library in the current directory. You can copy the library to the lib\563xx or lib\566xx directory of the product. But before you do so, you may want to make a backup copy of the original library in that directory.

When the hardware stack extension has to be disabled on the DSP, you also have to retranslate start.asm with the NOESTACK macro defined. When retranslating the libraries, you can set this option also in the concerning makefile, by adding -DNOESTACK to the ASFLAGS definition.

6.3 Libraries Overview

The table below lists the libraries included in the DSP5600x (c56) and DSP563xx/6xx (c563) toolchains. What libraries are to be linked depends on the memory model selected. The Control Program and EDE will automatically select the correct libraries depending on the memory model specified.

The lib directory contains the subdirectories with the library files for the DSP5600x, DSP563xx and DSP566xx.

Compiler Processor Model Libraries
C Run-time Floating point
c56 DSP5600x Static libcs.a librt.a libfp.a
Reentrant libcr.a
Mixed libcm.a
c563 DSP563xx 16 bit libc16.a librt16.a libfp16.a
16/24 bit libc1624.a
24 bit libc24.a librt24.a libfp24.a
DSP566xx - libc6.a librt6.a libfp6.a

Table 6-1: Overview of Libraries

The lk563 linker uses this naming convention when specifying the -l option. For example, with -lc16 the linker looks for libc16.a in the DSP type specific subdirectory of the system lib directory. Specifying the libraries is a job taken care of by the control program.

When you use floating point, the floating point library must always be the last library linked, it should be placed after the C library. Arithmetic routines like sin(), cos(), etc. are not present in these libraries, only basic floating point operations can be done.

6.4 Input/Output Functions

Figure 6-1: Calling mechanism of input function in C library

Figure 6-2: Calling mechanism of output function in C library

* = function is implemented as a macro (if stdio.h is included); the C libraries contain them as well, for example, in cases where a function pointer needs the address of such a function.

** = internal function.

6.5 Header Files

The following header files are delivered with the C compiler:

<assert.h> assert

<c56.h> Special file with c563 definitions. No C functions. Can be used for prototyping your application on a host using a standard C compiler.

<conio.h> _insize, kbhit().

<ctype.h> isalnum, isalpha, isascii, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit, toascii, _tolower, tolower, _toupper, toupper

<errno.h> Error numbers. No C functions.

<fcntl.h> Definition of flags used by open().

<float.h> Constants related to floating point arithmetic.

<limits.h> Limits and sizes of integral types. No C functions.

<locale.h> localeconv, setlocale. Delivered as skeletons.

<math.h> acos, asin, atan, atan2, ceil, cos, cosh, exp, fabs, floor, fmod, frexp, ldexp, log, log10, modf, pow, sin, sinh, sqrt, tan, tanh

<reg56xxx.h>
Include files with all special function register definitions for the DSP56xxx .

<setjmp.h> longjmp, setjmp

<signal.h> raise, signal. Functions are delivered as skeletons.

<stdarg.h> va_arg, va_end, va_start

<stddef.h> offsetof, definition of special types.

<stdio.h> clearerr, _close, fclose, feof, ferror, fflush, fgetc, fgetpos, fgets, fopen, _fopen, fprintf, fputc, fputs, fread, freopen, fscanf, fseek, fsetpos, ftell, fwrite, getc, getchar, gets, _lseek, _open, perror, printf, putc, putchar, puts, _read, remove, rename, rewind, scanf, setbuf, setvbuf, sprintf, sscanf, tmpfile, tmpnam, ungetc, vfprintf, vprintf, vsprintf, _write

<stdlib.h> abort, abs, atexit, atof, atoi, atol, bsearch, calloc, div, exit, free, getenv, labs, ldiv, malloc, mblen, mbstowcs, mbtowc, qsort, rand, realloc, srand, strtod, strtol, strtoul, system, wcstombs, wctomb

<string.h> memchr, memcmp, memcpy, memmove, memset, _packsize, _packstr, _pstr_get, _pstr_put, strcat, strchr, strcmp, strcol, strcpy, strcspn, strerror, strlen, strncat, strncmp, strncpy, strpbrk, strrchr, strspn, strstr, strtok, strxfrm, _unpackstr, _unpstrlen

<time.h> asctime, clock, ctime, difftime, gmtime, localtime, mktime, strftime, time.

6.6 C Libraries

The C library contains C library functions. All C library functions are described in this chapter. These functions are only called by explicit function calls in your application program.

6.6.1 C Library Implementation Details

A detailed description of the delivered C library is shown in the following list.

Explanation :

Y - Fully implemented
I - Implemented, using file system simulation
L - Delivered as a skeleton

File Imple-
mented
Routine name Description / Reason
assert.h Y 'assert()' macro Macro definition
conio.h Y _insize
kbhit()
ctype.h Y




Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y





isalnum
isalpha
iscntrl
isdigit
isgraph
islower
isprint
ispunct
isspace
isupper
isxdigit
tolower
toupper
_tolower
_toupper
isascii
toascii
Most of the routines are
delivered as macro AND as
function (as prescribed by
ANSI).














Not defined by ANSI
Not defined by ANSI
Not defined by ANSI
Not defined by ANSI
errno.h Y Only Macros
fcntl.h Y
I

open
Definitions of flags used by _open
float.h Y
limits.h Y Only Macros
locale.h Y
L
L

localeconv
setlocale

No OS present
No OS present
math.h Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y

acos
asin
atan
atan2
ceil
cos
cosh
exp
fabs
floor
fmod
frexp
ldexp
log
log10
modf
pow
sin
sinh
sqrt
tan
tanh
setjmp.h Y
Y
Y

longjmp
setjmp
signal.h Y
L
L

raise
signal

No OS present
No OS present
stdarg.h Y
Y
Y
Y

va_arg
va_end
va_start
stddef.h Y Only Macros
stdio.h Y



Y
I
Y
Y
I
I




clearerr
fclose
feof
ferror
fflush
fgetc
Due to 'stdarg.h/varargs.h'
conflicts, the routines
'vprintf()', 'vfprintf()',
'vsprintf()' are not ANSI yet.

Needs _fclose


Needs _write
Needs _read
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
Y
I
I
I
I
L
L
I
I
Y
Y
Y
Y
L
L


Y
I
I
Y
I
I
I

I
I
I
fgetpos
fgets
fopen
fprintf
fputc
fputs
fread
freopen
fscanf
fseek
fsetpos
ftell
fwrite
getc
getchar
gets
perror
printf
putc
putchar
puts
remove
rename
rewind
scanf
setbuf
setvbuf
sprintf
sscanf
tmpfile
tmpnam


ungetc
vfprintf
vprintf
vsprintf
_close
_fopen
_lseek

_open
_read
_write
Needs _lseek
Needs _read
Needs _fopen
Needs _write
Needs _write
Needs _write
Needs _read
Needs _fclose/_fopen
Needs _read
Needs _lseek
Needs _lseek
Needs _lseek
Needs _write
Needs _read
Needs _read
Needs _read

Needs _write
Needs _write
Needs _write
Needs _write


Needs _lseek
Needs _read





Delivered as a random name
generator, but should use
some process ID.

Needs _write
Needs _write

Low level file close routine
Low level file open routine
Low level file positioning
routine
Low level file open routine
Low level input routine
Low level output routine
stdlib.h Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
L
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y

L
L
L
L
L
L

abort
abs
atexit
atof
atoi
atol
bsearch
calloc
div
exit
free
getenv
labs
ldiv
malloc
qsort
strtod
strtol
strtoul
rand
realloc
srand

system
mblen
mbstowcs
mbtowc
wcstombs
wctomb

Calls _exit() in cstart








Calls _exit() in cstart

No OS present











No OS present
wide chars not supported
wide chars not supported
wide chars not supported
wide chars not supported
wide chars not supported
string.h Y
Y
Y
Y
Y
Y
Y
Y
Y
L
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
L

memchr
memcmp
memcpy
memmove
memset
strcat
strchr
strcmp
strcoll
strcpy
strcspn
strerror
strlen
strncat
strncmp
strncpy
strpbrk
strrchr
strspn
strstr
strtok
strxfrm









wide chars not supported












wide chars not supported
time.h Y
Y
Y
Y
Y
Y
Y
Y
Y
Y

asctime
clock
ctime
difftime
gmtime
localtime
mktime
strftime
time
real time clock not supported, but the DSP timer is used to maintain relative time

6.6.2 C Library Interface Description

_close

Low level file close function. _close is used by the function fclose. The given file descriptor should be properly closed, any buffer is already flushed. The delivered library is targeted at TASKING or Motorola FSS (File System Simulation). The source file contains versions for TASKING and Motorola FSS, and an 'empty' function. This function must be customized to perform I/O on different file systems. See the file _close.c in the lib\src directory for the example implementations of this low level close function.

_filbuf

Low level file input function. Read a character from a file, buffering when necessary. Filling the buffer is done through calls to _read.

Returns the character written, or EOF.

_flsbuf

Low level file output function. Write a character to a file, flushing the buffer when necessary. Flushing is done through calls to _write.

Returns the character written, or EOF.

_fopen

Low level file open function. Opens a file with name filename and access type mode in iop. _fopen is used by the functions fopen and freopen, and in turn passes control to _open. Note that for text modes the file functions will work on character basis, whereas for binary modes they will work on memory-cell-wide objects (integers in most models). Files opened in binary mode will read/write full DSP words, whereas files opened in text mode will read/write the low 8 bits only.

Returns the descriptor of the file opened, or NULL if an error occurred.

_insize

Low level function for investigating the size of stdin.

Returns queue size for stdin.

_ioread

Low level input function. This function reads a character from a file. _ioread is used by all input functions (scanf, getc, gets, etc.). The delivered library is targeted at TASKING or Motorola FSS (File System Simulation). The source file contains versions for TASKING and Motorola FSS, and an 'empty' function. This function must be customized to perform I/O on different file systems. See the file _ioread.c in the lib\src directory for the example implementations of this low level input function.

Returns the character read, or EOF if an error occurred.

_iowrite

Low level output function. This function writes a character to a file. _iowrite is used by all output functions (printf, putc, puts, etc.). The delivered library is targeted at TASKING or Motorola FSS (File System Simulation). The source file contains versions for TASKING and Motorola FSS, and an 'empty' function. This function must be customized to perform I/O on different file systems. See the file _iowrite.c in the lib\src directory for the example implementations of this low level output function.

Returns the character written, or EOF if an error occurred.

_lseek

Low level file positioning function. This function sets the file position of a file. _lseek is used by all file positioning functions (fgetpos, fseek, fsetpos, ftell, rewind). The delivered library is targeted at TASKING or Motorola FSS (File System Simulation). The source file contains versions for TASKING and Motorola FSS, and an 'empty' function. This function must be customized to perform I/O on different file systems. See the file _lseek.c in the lib\src directory for the example implementations of this low level file function.

Returns the new file position, or EOF if an error occurred.

_open

Low level file open function. This function opens a file with name filename and access type flags. _open is called from the function _fopen and from system initialization (for stdin, stdout and stderr). With FSS (File System Simulation), this function opens a file on the host system. The source file contains versions for TASKING and Motorola FSS, and an 'empty' function. This function can be adapted to work on different file systems; the given stream should be properly opened.

Returns the descriptor of the file opened, or -1 if an error occurred.

_packsize

Returns the size of a string when it is packed.

_packstr

Pack string pointed to by unp in the buffer pointed to by p.

Returns a pointer to the packed string.

_pstr_get

This function should be used to obtain one character from a packed string. The packed string is supplied via the p argument. The index in the string is supplied via the idx argument. This index is the count in bytes starting at zero.

Returns the character at the given index in the packed string.

Example:

See also section section 3.18 Packed Strings.

_pstr_put

This function updates one character (one byte) in a packed string pointed to by p. The character is supplied in the argument c and the index in idx. This index is the count in bytes starting at zero.

Returns nothing.

Example:

See also section section 3.18 Packed Strings.

_read

Low level block input function. This function reads a block of data from the given stream. It is used by all input functions. The delivered library is targeted at TASKING or Motorola FSS (File System Simulation). The source file contains versions for TASKING and Motorola FSS, and an 'empty' function. This function must be customized to perform I/O on different file systems. When not customized it will use _ioread().

Returns the number of characters read.

_tolower

Converts c to a lowercase character, does not check if c really is an uppercase character. This is a non-ANSI function.

Returns the converted character.

_toupper

Converts c to an uppercase character, does not check if c really is a lowercase character. This is a non-ANSI function.

Returns the converted character.

_unpackstr

Unpack string pointed to by p in the buffer pointed to by unp.

Returns a pointer to unpacked string.

_unpstrlen

Returns the length in number of characters of the packed string pointed to by p. This is the number of characters when the string would be unpacked.

_write

Low level block output function. This function writes a block of data to the given stream. It is used by all output functions. The delivered library is targeted at TASKING or Motorola FSS (File System Simulation). The source file contains versions for TASKING and Motorola FSS, and an 'empty' function. This function must be customized to perform I/O on different file systems. When not customized it will use _iowrite().

Returns the number of characters correctly written.

abort

Terminates the program abnormally. It calls the function _exit, which is defined in the start-up module.

Returns nothing.

abs

Returns the absolute value of the signed int argument.

acos

Returns the arccosine cos-1(x) of x in the range [0, pi],
x c [-1, 1].

asctime

Converts the time in the structure *tp into a string of the form:

Returns the time in string form.

asin

Returns the arcsine sin-1(x) of x in the range [-pi/2, pi/2],
x c [-1, 1].

assert

When compiled with NDEBUG, this is an empty macro. When compiled without NDEBUG defined, it checks if expr is true. If it is true, then a line like:

is printed.

Returns nothing.

atan

Returns the arctangent tan-1(x) of x in the range [-pi/2, pi/2].

atan2

Returns the result of: tan-1(y/x) in the range [-pi, pi] where y/x are coordinates. x and y cannot be both zero.

atexit

Registers the function fcn to be called when the program terminates normally.

Returns zero, if program terminates normally.
non-zero, if the registration cannot be made.

atof

Converts the given string to a double value. White space is skipped, conversion is terminated at the first unrecognized character.

Returns the double value.

atoi

Converts the given string to an integer value. White space is skipped, conversion is terminated at the first unrecognized character.

Returns the integer value.

atol

Converts the given string to a long value. White space is skipped, conversion is terminated at the first unrecognized character.

Returns the long value.

bsearch

This function searches in an array of n members, for the object pointed to by ptr. The initial base of the array is given by base. The size of each member is specified by size. The given array must be sorted in ascending order, according to the results of the function pointed to by cmp.

Returns a pointer to the matching member in the array, or NULL when not found.

calloc

The allocated space is filled with zeros. The maximum space that can be allocated can be changed by customizing the heap size (see the section Heap ). By default no heap is allocated. When "calloc()" is used while no heap is defined, the locator gives an error.

Returns a pointer to space in external memory for nobj items of size bytes length.
NULL if there is not enough space left.

See also free() .

ceil

Returns the smallest integer not less than x, as a double.

clearerr

Clears the end of file and error indicators for stream.

Returns nothing.

clock

Determines the processor time used.

Returns number of seconds since the last reset, assuming a 66 MHz cpu.

cos

Returns the cosine of x.

cosh

Returns the hyperbolic cosine of x.

ctime

Converts the calender time *tp into local time, in string form. This function is the same as:

Returns the local time in string form.

difftime

Returns the result of time2 - time1 in seconds.

div

Both arguments are integers. The returned quotient and remainder are also integers.

Returns a structure containing the quotient and remainder of num divided by denom.

exit

Terminates the program normally. Acts as if 'main()' returns with status as the return value.

Returns zero, on successful termination.

exp

Returns the result of the exponential function ex.

fabs

Returns the absolute double value of x. |x|

fclose

Flushes any unwritten data for stream, discards any unread buffered input, frees any automatically allocated buffer, then closes the stream.

Returns zero if the stream is successfully closed, or EOF on error.

feof

Returns a non-zero value if the end-of-file indicator for stream is set.

ferror

Returns a non-zero value if the error indicator for stream is set.

fflush

Writes any buffered but unwritten data, if stream is an output stream. If stream is an input stream, the effect is undefined.

Returns zero if successful, or EOF on a write error.

fgetc

Reads one character from the given stream.

Returns the read character, or EOF on error.

fgetpos

Stores the current value of the file position indicator for the stream pointed to by stream in the object pointed to by ptr. The type fpos_t is suitable for recording such values.

Returns zero if successful,
a non-zero value on error.

fgets

Reads at most the next n-1 characters from the given stream into the array s until a newline is found.

Returns s, or NULL on EOF or error.

floor

Returns the largest integer not greater than x, as a double.

fmod

Returns the floating-point remainder of x/y, with the same sign as x. If y is zero, the result is implementation-defined.

fopen

Opens a file for a given mode.

Returns a stream. If the file cannot not be opened, NULL is returned.

You can specify the following values for mode:

 "r" read; open text file for reading

"w" write; create text file for writing; if the file already exists its contents is discarded

"a" append; open existing text file or create new text file for writing at end of file

"r+" open text file for update; reading and writing

"w+" create text file for update; previous contents if any is discarded

"a+" append; open or create text file for update, writes at end of file

The update mode (with a '+') allows reading and writing of the same file. In this mode the function fflush must be called between a read and a write or vice versa. By including the letter 'b' after the initial letter, you can indicate that the file is a binary file. By including a '8' the file will also be opened in binary mode but the read/write uses only the lower 8 bits as in text mode. E.g. "rb" means read binary, "w+b" means create binary file for update. The filename is limited to FILENAME_MAX characters. At most FOPEN_MAX files may be open at once.

Files opened in binary mode will read/write full DSP words (except when you used '8'), whereas files opened in text mode will read/write the low 8 bits only.

fprintf

Performs a formatted write to the given stream.

See also printf(), _write() and section Printf and Scanf Formatting Routines.

fputc

Puts one character onto the given stream.

See also _write().

Returns EOF on error.

fputs

Writes the string to a stream. The terminating NULL character is not written.

See also _write().

Returns NULL if successful, or EOF on error.

fread

Reads nobj members of size bytes from the given stream into the array pointed to by ptr.

See also _read().

Returns the number of successfully read objects.

free

Deallocates the space pointed to by p. p Must point to space earlier allocated by a call to "calloc()", "malloc()" or "realloc()". Otherwise the behavior is undefined.

See also calloc(), malloc() and realloc().

Returns nothing

freopen

Opens a file for a given mode and associates the stream with it. This function is normally used to change the files associated with stdin, stdout, or stderr.

See also fopen().

Returns stream, or NULL on error.

frexp

Splits x into a normalized fraction in the interval [1/2, 1>, which is returned, and a power of 2, which is stored in *exp. If x is zero, both parts of the result are zero. For example: frexp( 4.0, &var ) results in 0.5·2^3. The function returns 0.5, and 3 is stored in var.

See also ldexp().

Returns the normalized fraction.

fscanf

Performs a formatted read from the given stream.

See also scanf(), _read() and section Printf and Scanf Formatting Routines.

Returns the number of items converted successfully.

fseek

Sets the file position indicator for stream. A subsequent read or write will access data beginning at the new position. For a binary file, the position is set to offset characters from origin, which may be SEEK_SET for the beginning of the file, SEEK_CUR for the current position in the file, or SEEK_END for the end-of-file. For a text stream, offset must be zero, or a value returned by ftell. In this case origin must be SEEK_SET.

Returns zero if successful,
a non-zero value on error.

fsetpos

Positions stream at the position recorded by fgetpos in *ptr.

Returns zero if successful,
a non-zero value on error.

ftell

Returns the current file position for stream, or
-1L on error.

fwrite

Writes nobj members of size bytes to the given stream from the array pointed to by ptr.

Returns the number of successfully written objects.

getc

Reads one character out of the given stream. Currently #defined as getchar(), because FILE I/O is not supported.

See also _read().

Returns the character read or EOF on error.

getchar

Reads one character from standard input.

See also _read().

Returns the character read or EOF on error.

getenv

Returns the environment string associated with name, or NULL if no string exists.

gets

Reads all characters from standard input until a newline is found. The newline is replaced by a NULL-character.

See also _read().

Returns a pointer to the read string or NULL on error.

gmtime

Converts the calender time *tp into Coordinated Universal Time (UTC).

Returns a structure representing the UTC, or NULL if UTC is not available.

isalnum

Returns a non-zero value when c is an alphabetic character or a number ([A-Z][a-z][0-9]).

isalpha

Returns a non-zero value when c is an alphabetic character ([A-Z][a-z]).

isascii

Returns a non-zero value when c is in the range of 0 and 127. This is a non-ANSI function.

iscntrl

Returns a non-zero value when c is a control character.

isdigit

Returns a non-zero value when c is a numeric character ([0-9]).

isgraph

Returns a non-zero value when c is printable, but not a space.

islower

Returns a non-zero value when c is a lowercase character ([a-z]).

isprint

Returns a non-zero value when c is printable, including spaces.

ispunct

Returns a non-zero value when c is a punctuation character (such as '.', ',', '!', etc.).

isspace

Returns a non-zero value when c is a space type character (space, tab, vertical tab, formfeed, linefeed, carriage return).

isupper

Returns a non-zero value when c is an uppercase character ([A-Z]).

isxdigit

Returns a non-zero value when c is a hexadecimal digit ([0-9][A-F][a-f]).

labs

Returns the absolute value of the signed long argument.

ldexp

See also frexp().

Returns the result of: 2 n.

ldiv

Both arguments are long integers. The returned quotient and remainder are also long integers.

Returns a structure containing the quotient and remainder of num divided by denom.

localeconv

Sets the components of an object with type struct lconv with values appropriate for the formatting of numeric quantities according to the rules of the current locale.

Returns a pointer to the filled-in object.

localtime

Converts the calender time *tp into local time.

Returns a structure representing the local time.

log

Returns the natural logarithm ln(x), x>0.

log10

Returns the base 10 logarithm log10(x), x>0.

longjmp

Restores the environment previously saved with a call to setjmp(). The function calling the corresponding call to setjmp() may not be terminated yet. The value of val may not be zero.

Because of the low-level nature of this routine it will not work correctly with the -Cc switch (all functions compatible). With minor changes to adapt it to the compatible calling convention this can be changed, but it cannot run under both calling conventions. On the DSP563xx , this routine will also fail when the stack extension is in use and the required stack level is located in the extension area.

malloc

The allocated space is not initialized. The maximum space that can be allocated can be changed by customizing the heap size (see the section Heap ). By default no heap is allocated. When "malloc()" is used while no heap is defined, the locator gives an error.

Returns a pointer to space in external memory of size bytes length. NULL if there is not enough space left.

See also free() .

mblen

Determines the number of bytes comprising the multi-byte character pointed to by s, if s is not a null pointer. Except that the shift state is not affected. At most n characters will be examined, starting at the character pointed to by s.

Returns the number of bytes, or 0 if s points to the null character, or -1 if the bytes do not form a valid multi-byte character.

mbstowcs

Converts a sequence of multi-byte characters that begins in the initial shift state from the array pointed to by s, into a sequence of corresponding codes and stores these codes into the array pointed to by pwcs, stopping after n codes are stored or a code with value zero is stored.

Returns the number of array elements modified (not including a terminating zero code, if any), or (size_t)-1 if an invalid multi-byte character is encountered.

mbtowc

Determines the number of bytes that comprise the multi-byte character pointed to by s. It then determines the code for value of type wchar_t that corresponds to that multi-byte character. If the multi-byte character is valid and pwc is not a null pointer, the mbtowc function stores the code in the object pointed to by pwc. At most n characters will be examined, starting at the character pointed to by s.

Returns the number of bytes, or 0 if s points to the null character, or -1 if the bytes do not form a valid multi-byte character.

memchr

Checks the first n bytes of cs on the occurrence of character c.

Returns NULL when not found, otherwise a pointer to the found character is returned.

memcmp

Compares the first n bytes of cs with the contents of ct.

Returns a value < 0 if cs < ct,
0 if cs = = ct,
or a value > 0 if cs > ct.

memcpy

Copies n characters from ct to s. No care is taken if the two objects overlap.

Returns s

memmove

Copies n characters from ct to s. Overlapping objects will be
handled correctly.

Returns s

memset

Fills the first n bytes of s with character c.

Returns s

mktime

Converts the local time in the structure *tp into calendar time.

Returns the calendar time, or -1 if it cannot be represented.

modf

Splits x into integral and fractional parts, each with the same sign as x. It stores the integral part in *ip.

Returns the fractional part.

offsetof

Returns the offset for the given member in an object of type.

perror

Prints s and an implementation-defined error message corresponding to the integer errno, as if by:

fprintf( stderr, "%s: %s\n", s, "error message" );

The contents of the error message are the same as those returned by the strerror function with the argument errno.

See also the strerror() function.

Returns nothing.

pow

A domain error occurs if x=0 and y<=0, or if x<0 and y is not an integer.

Returns the result of x raised to the power of y: xy.

printf

Performs a formatted write to the standard output stream.

See also _write() and section Printf and Scanf Formatting Routines.

Returns the number of characters written to the output stream.

The format string may contain plain text mixed with conversion specifiers. Each conversion specifier should be preceded by a '%' character. The conversion specifier should be build in order:

- Flags (in any order):

- specifies left adjustment of the converted argument.

+ a number is always preceded with a sign character.
+ has higher precedence as space.

space a negative number is preceded with a sign, positive numbers with a space.

0 specifies padding to the field width with zeros (only for numbers).

# specifies an alternate output form. For o, the first digit will be zero. For x or X, "0x" and "0X" will be prefixed to the number. For e, E, f, g, G, the output always contains a decimal point, trailing zeros are not removed.

- A number specifying a minimum field width. The converted argument is printed in a field with at least the length specified here. If the converted argument has fewer characters than specified, it will be padded at the left side (or at the right when the flag '-' was specified) with spaces. Padding to numeric fields will be done with zeros when the flag '0' is also specified (only when padding left). Instead of a numeric value, also '*' may be specified, the value is then taken from the next argument, which is assumed to be of type int.

- A period. This separates the minimum field width from the precision.

- A number specifying the maximum length of a string to be printed. Or the number of digits printed after the decimal point (only for floating point conversions). Or the minimum number of digits to be printed for an integer conversion. Instead of a numeric value, also '*' may be specified, the value is then taken from the next argument, which is assumed to be of type int.

- A length modifier 'h', 'l' or 'L'. 'h' indicates that the argument is to be treated as a short or unsigned short number. 'l' should be used if the argument is a long integer. 'L' indicates that the argument is a long double.

Flags, length specifier, period, precision and length modifier are optional, the conversion character is not. The conversion character must be one of the following, if a character following '%' is not in the list, the behavior is undefined:

Character Printed as
d, i int, signed decimal
o int, unsigned octal
x, X int, unsigned hexadecimal in lowercase or uppercase respectively
u int, unsigned decimal
c int, single character (converted to unsigned char)
s, S char * or _packed char * respectively, the characters from the string or packed string respectively are printed until a NULL character is found. When the given precision is met before, printing will also stop
f double
e, E double; [-]m.dddddde+xx or [-]m.ddddddE+xx, where the number of d's is specified by the precision.
g, G double; uses %e or %E if the exponent is less than -4 or greater than or equal to the precision; otherwise uses %f.
n int *, the number of characters written so far is written into the argument. This should be a pointer to an integer in default memory. No value is printed.
p pointer (hexadecimal 32-bit value)
% No argument is converted, a '%' is printed.

Table 6-2: Printf conversion characters

To print fractional numbers, the value can be cast to a float and printed as a float. For single-precision fractional numbers the printed value is exact, for long _fract it is rounded. If you need more precision when printing long _fract values you can print them in hexadecimal form:

putc

Puts one character onto the given stream.

See also _write().

Returns EOF on error.

putchar

Puts one character onto standard output.

See also _write().

Returns the character written or EOF on error.

puts

Writes the string to stdout, the string is terminated by a newline.

See also _write().

Returns NULL if successful, or EOF on error.

qsort

This function sorts an array of n members. The initial base of the array is given by base. The size of each member is specified by size. The given array is sorted in ascending order, according to the results of the function pointed to by cmp.

raise

Sends the signal sig to the program.

See also signal().

Returns zero if successful, or a non-zero value if unsuccessful.

rand

Returns a sequence of pseudo-random integers, in the range 0 to RAND_MAX.

See also srand().

realloc

Reallocates the space for the object pointed to by p. The contents of the object will be the same as before calling realloc(). The maximum space that can be allocated can be changed by customizing the heap size (see the section Heap ). By default no heap is allocated. When "realloc()" is used while no heap is defined, the linker gives an error. See also malloc().

In this implementation the returned address will be the same as the original address if realloc() is successfully used to decrease the size of a buffer. The minimal amount of extra memory is allocated when a buffer size is increased.

Returns NULL and *p is not changed, if there is not enough space for the new allocation. Otherwise a pointer to the newly allocated space for the object is returned.

See also free() .

remove

Removes the named file, so that a subsequent attempt to open it fails.

Returns zero if file is successfully removed, or
a non-zero value, if the attempt fails.

rename

Changes the name of the file.

Returns zero if file is successfully renamed, or
a non-zero value, if the attempt fails.

rewind

Sets the file position indicator for the stream pointed to by stream to the beginning of the file. This function is equivalent to:

(void) fseek( stream, 0L, SEEK_SET );
clearerr( stream );

Returns nothing.

scanf

Performs a formatted read from the standard input stream.

See also _read() and section Printf and Scanf Formatting Routines.

Returns the number of items converted successfully.

All arguments to this function should be pointers to variables (in default memory) of the type which is specified in the format string.

The format string may contain :

- Blanks or tabs, which are skipped.

- Normal characters (not '%'), which should be matched exactly in the input stream.

- Conversion specifications, starting with a '%' character.

Conversion specifications should be build as follows (in order) :

- A '*', meaning that no assignment is done for this field.

- A number specifying the maximum field width.

- The conversion characters d, i, n, o, u and x may be precede by 'h' if the argument is a pointer to short rather than int, or by 'l' (letter ell) if the argument is a pointer to long. The conversion characters e, f, and g may be precede by 'l' if a pointer double rather than float is in the argument list, and by 'L' if a pointer to a long double.

- A conversion specifier. '*', maximum field width and length modifier are optional, the conversion character is not. The conversion character must be one of the following, if a character following '%' is not in the list, the behavior is undefined.

Length specifier and length modifier are optional, the conversion character is not. The conversion character must be one of the following, if a character following '%' is not in the list, the behavior is undefined.

Character Scanned as
d int, signed decimal.
i int, the integer may be given octal (i.e. a leading 0 is entered) or hexadecimal (leading "0x" or "0X"), or just decimal.
o int, unsigned octal.
u int, unsigned decimal.
x int, unsigned hexadecimal in lowercase or uppercase.
c single character (converted to unsigned char).
s, S char * or _packed char * respectively, a string of non white space characters. The argument should point to an array of characters or packed characters respectively, large enough to hold the string and a terminating NULL character.
f float
e, E float; [-]m.dddddde+xx or [-]m.ddddddE+xx, where the number of d's is specified by the precision.
g, G float; uses %e or %E if the exponent is less than -4 or greater than or equal to the precision; otherwise uses %f.
n int *, the number of characters written so far is written into the argument. No scanning is done.
p pointer; hexadecimal 32-bit value which must be entered without 0x- prefix.
[...] Matches a string of input characters from the set between the brackets. A NULL character is added to terminate the string. Specifying []...] includes the ']' character in the set of scanning characters.
[^...] Matches a string of input characters not in the set between the brackets. A NULL character is added to terminate the string. Specifying [^]...] includes the ']' character in the set.
% Literal '%', no assignment is done.

Table 6-3: Scanf conversion characters

setbuf

Buffering is turned off for the stream, if buf is NULL.
Otherwise, setbuf is equivalent to:

(void) setvbuf( stream, buf, _IOFBF, BUFSIZ )

See also setvbuf().

setjmp

Saves the current environment for a subsequent call to longjmp.

Returns the value 0 after a direct call to setjmp(). Calling the function "longjmp()" using the saved env will restore the current environment and jump to this place with a non-zero return value.

Because of the low-level nature of this routine it will not work correctly with the -Cc switch (all functions compatible). With minor changes to adapt it to the compatible calling convention this can be changed, but it cannot run under both calling conventions. On the DSP563xx , this routine will also fail when the stack extension is in use and the required stack level is located in the extension area.

See also longjmp().

setlocale

Selects the appropriate portion of the program's locale as specified by the category and locale arguments.

Returns the string associated with the specified category for the new locale if the selection can be honored.
null pointer if the selection cannot be honored.

setvbuf

Controls buffering for the stream; this function must be called before reading or writing. mode can have the following values:

_IOFBF causes full buffering
_IOLBF causes line buffering of text files
_IONBF causes no buffering

If buf is not NULL, it will be used as a buffer; otherwise a buffer will be allocated. size determines the buffer size.

Returns zero if successful
a non-zero value for an error.

See also setbuf().

signal

Determines how subsequent signals will be handled. If handler is SIG_DFL, the default behavior is used; if handler is SIG_IGN, the signal is ignored; otherwise, the function pointed to by handler will be called, with the argument of the type of signal. Valid signals are:

SIGABRT abnormal termination, e.g. from abort
SIGFPE arithmetic error, e.g. zero divide or overflow
SIGILL illegal function image, e.g. illegal instruction
SIGINT interactive attention, e.g. interrupt
SIGSEGV illegal storage access, e.g. access outside
memory limits
SIGTERM termination request sent to this program

When a signal sig subsequently occurs, the signal is restored to its default behavior; then the signal-handler function is called, as if by (*handler)(sig). If the handler returns, the execution will resume where it was when the signal occurred.

Returns the previous value of handler for the specific signal, or SIG_ERR if an error occurs.

sin

Returns the sine of x.

sinh

Returns the hyperbolic sine of x.

sprintf

Performs a formatted write to a string.

See also printf() and section Printf and Scanf Formatting Routines.

sqrt

Returns the square root of x. Vx, where x >= 0.

srand

This function uses seed as the start of a new sequence of pseudo-random numbers to be returned by subsequent calls to srand(). When srand is called with the same seed value, the sequence of pseudo-random numbers generated by rand() will be repeated.

Returns pseudo random numbers.

See also rand() .

sscanf

Performs a formatted read from a string.

See also scanf() and section Printf and Scanf Formatting Routines.

strcat

Concatenates string ct to string s, including the trailing NULL character.

Returns s

strchr

Returns a pointer to the first occurrence of character c in the string cs. If not found, NULL is returned.

strcmp

Compares string cs to string ct.

Returns <0 if cs < ct,
0 if cs == ct,
>0 if cs > ct.

strcoll

Compares string cs to string ct. The comparison is based on strings interpreted as appropriate to the program's locale.

Returns <0 if cs < ct,
0 if cs = = ct,
>0 if cs > ct.

strcpy

Copies string ct into the string s, including the trailing NULL character.

Returns s

strcspn

Returns the length of the prefix in string cs, consisting of characters not in the string ct.

strerror

Returns pointer to implementation-defined string corresponding to error n.

strftime

Formats date and time information from the structure *tp into s according to the specified format fmt. fmt is analogous to a printf format. Each %c is replaced as described below:

Ordinary characters (including the terminating `\0`) are copied into s. No more than smax characters are placed into s.

Returns the number of characters ('\0' not included), or
zero if more than smax characters where produced.

strlen

Returns the length of the string in cs, not counting the NULL character.

strncat

Concatenates string ct to string s, at most n characters are copied. Add a trailing NULL character.

Returns s

strncmp

Compares at most n bytes of string cs to string ct.

Returns <0 if cs < ct,
0 if cs == ct,
>0 if cs > ct.

strncpy

Copies string ct onto the string s, at most n characters are copied. Add a trailing NULL character if the string is smaller than n characters.

Returns s

strpbrk

Returns a pointer to the first occurrence in cs of any character out of string ct. If none are found, NULL is returned.

strrchr

Returns a pointer to the last occurrence of c in the string cs. If not found, NULL is returned.

strspn

Returns the length of the prefix in string cs, consisting of characters in the string ct.

strstr

Returns a pointer to the first occurrence of string ct in the string cs. Returns NULL if not found.

strtod

Converts the initial portion of the string pointed to by s to a double value. Initial white spaces are skipped. When endp is not a NULL pointer, after this function is called, *endp will point to the first character not used by the conversion.

Returns the read value.

strtok

Search the string s for tokens delimited by characters from string ct. It terminates the token with a NULL character.

Returns a pointer to the token. A subsequent call with
s == NULL will return the next token in the string.

strtol

Converts the initial portion of the string pointed to by s to a long integer. Initial white spaces are skipped. Then a value is read using the given base. When base is zero, the base is taken as defined for integer constants. I.e. numbers starting with an '0' are taken octal, numbers starting with '0x' or '0X' are taken hexadecimal. Other numbers are taken decimal. When endp is not a NULL pointer, after this function is called, *endp will point to the first character not used by the conversion.

Returns the read value.

strtoul

Converts the initial portion of the string pointed to by s to an unsigned long integer. Initial white spaces are skipped. Then a value is read using the given base. When base is zero, the base is taken as defined for integer constants. I.e. numbers starting with an '0' are taken octal, numbers starting with '0x' or '0X' are taken hexadecimal. Other numbers are taken decimal. When endp is not a NULL pointer, after this function is called, *endp will point to the first character not used by the conversion.

Returns the read value.

strxfrm

Transforms the string pointed to by cs and places the resulting string into the array pointed to by ct. No more than n characters are placed into the resulting string pointed to by ct, including the terminating null character.

Returns the length of the transformed string.

system

Passes the string s to the environment for execution.

Returns a non-zero value if there is a command processor, if s is NULL; or an implementation-dependent value, if s is not NULL.

tan

Returns the tangent of x.

tanh

Returns the hyperbolic tangent of x.

time

The return value is also assigned to *tp, if tp is not NULL.

Returns the current calendar time, or -1 if the time is not available.

tmpfile

Creates a temporary file of the mode "wb+" that will be automatically removed when closed or when the program terminates normally.

Returns a stream if successful, or NULL if the file could not be created.

tmpnam

Creates a temporary name (not a file). Each time tmpnam is called a different name is created.
tmpnam(NULL) creates a string that is not the name of an existing file, and returns a pointer to an internal static array. tmpnam(s) creates a string and stores it in s and also returns it as the function value. s must have room for at least L_tmpnam characters. At most TMP_MAX different names are guaranteed during execution of the program.

Returns a pointer to the temporary name, as described above.

toascii

Converts c to an ascii value (strip highest bit). This is a non-ANSI function.

Returns the converted value.

tolower

Returns c converted to a lowercase character if it is an uppercase character, otherwise c is returned.

toupper

Returns c converted to an uppercase character if it is a lowercase character, otherwise c is returned.

ungetc

Pushes at the most one character back onto the input buffer.

Returns EOF on error.

va_arg

Returns the value of the next argument in the variable argument list. Its return type has the type of the given argument type. A next call to this macro will return the value of the next argument.

va_end

This macro must be called after the arguments have been processed. It should be called before the function using the macro 'va_start' is terminated (ANSI specification).

va_start

This macro initializes ap. After this call, each call to va_arg() will return the value of the next argument. In our implementation, va_list cannot contain any bit type variables. Also the given argument lastarg must be the last non-bit type argument in the list.

vfprintf

Is equivalent to vprintf, but writes to the given stream.

See also vprintf(), _write() and section Printf and Scanf Formatting Routines.

vprintf

Does a formatted write to standard output. Instead of a variable argument list as for printf(), this function expects a pointer to the list.

See also printf(), _write() and section Printf and Scanf Formatting Routines.

vsprintf

Does a formatted write a string. Instead of a variable argument list as for printf(), this function expects a pointer to the list.

See also printf(), _write() and section Printf and Scanf Formatting Routines.

wcstombs

Converts a sequence of codes that correspond to multi-byte characters from the array pointed to by pwcs, into a sequence of multi-byte characters that begins in the initial shift state and stores these multi-byte characters into the array pointed to by s, stopping if a multi-byte character would exceed the limit of n total bytes or if a null character is stored.

Returns the number of bytes modified (not including a terminating null character, if any), or (size_t)-1 if a code is encountered that does not correspond to a valid multi-byte character.

wctomb

Determines the number of bytes needed to represent the multi-byte corresponding to the code whose value is wchar (including any change in the shift state). It stores the multi-byte character representation in the array pointed to by s (if s is not a null pointer). At most MB_CUR_MAX characters are stored. If the value of wchar is zero, the wctomb function is left in the initial shift state.

Returns the number of bytes, or -1 if the value of wchar does not correspond to a valid multi-byte character.

6.6.3 Printf and Scanf Formatting Routines

The functions printf(), fprintf(), vfprintf(), vsprintf(), ... call one single function that deals with the format string and arguments. This function is _doprint(). This is a rather big function because the number of possibilities of the format specifiers in a format string are large. If you do not use all the possibilities of the format specifiers a smaller _doprint() function can be used. Three different versions exist:

The same applies to all scanf type functions, which all call the function _doscan().

The formatters included in the libraries are LARGE. You can select different formatters by linking separate objects of _doscan() and _doprint() with your application. The following objects are included:

For the DSP563xx:

lib/563xx /libc16
_doprnts.obj _doprint(), 16-bit model, SMALL formatter
_doprntm.obj _doprint(), 16-bit model, MEDIUM formatter
_doscans.obj _doscan(), 16-bit model, SMALL formatter

lib/563xx /libc1624
_doprnts.obj _doprint(), 16/24-bit model, SMALL formatter
_doprntm.obj _doprint(), 16/24-bit model, MEDIUM formatter
_doscans.obj _doscan(), 16/24-bit model, SMALL formatter

lib/563xx /libc24
_doprnts.obj _doprint(), 24-bit model, SMALL formatter
_doprntm.obj _doprint(), 24-bit model, MEDIUM formatter
_doscans.obj _doscan(), 24-bit model, SMALL formatter

For the DSP566xx:

lib/566xx/libc6
_doprnts.obj _doprint(), SMALL formatter
_doprntm.obj _doprint(), MEDIUM formatter
_doscans.obj _doscan(), SMALL formatter

For the DSP5600x :

lib/5600x /libcm
_doprnts.obj _doprint(), mixed model, SMALL formatter
_doprntm.obj _doprint(), mixed model, MEDIUM formatter
_doscans.obj _doscan(), mixed model, SMALL formatter

lib/5600x /libcr
_doprnts.obj _doprint(), reentrant model, SMALL formatter
_doprntm.obj _doprint(), reentrant model, MEDIUM formatter
_doscans.obj _doscan(), reentrant model, SMALL formatter

lib/5600x /libcs
_doprnts.obj _doprint(), static model, SMALL formatter
_doprntm.obj _doprint(), static model, MEDIUM formatter
_doscans.obj _doscan(), static model, SMALL formatter

Example (PC):

cc563 -M24 hello.obj c:\c563\lib\563xx\libc24\_doprntm.obj

6.7 Run-time Library

Some basic operations take up a lot of memory if generated as inline code. For example, code to perform a 48-bit integer division. The compiler can generate code with calls to library functions for these situations. This depends on the optimization level (optimize for size or speed). These routines are stored in the run-time library. The run-time library also contains some default versions of routines required by the C library (e.g., exit).

Because c563 generates assembly code (and not object code) it prepends an 'F' for the names of (public) C variables to distinguish these symbols from internal symbols. So if you use a function name starting with an underscore, the assembly label for this function will start with 'F_'. Run-time library functions have no prepended 'F', they have a prepended 'R'.

The routines from the run-time library are stored in special sections (.rttext, .petext and .zerotext) to allow precise locating of these routines.

6.8 Floating Point Library

The DSP56xxx does not have a hardware floating point unit, so floating point calculations must be emulated in software. The floating-point routines are stored in the floating-point library. For a detailed description of the floating-point format, see chapter 7 . The floating point library is reentrant and independent of the memory model, except for the data precision (16 or 24-bit). All routines from the floating-point library are stored in a special section, .fptext, to allow precise locating of these routines. Floating-point library functions have no prepended 'F', their names start with 'Rfp'.


Copyright © 2002 Altium BV