Standard library functions

The runtime service library comes along with a subset of the C standard library, complying with ISO C11 specifications.

The next table summarizes the available functions and definitions:

Header file	Available in the runtime service library
assert.h	assert - Upon assertion failure as described in Exceptions
ctype.h	All the functions defined by the standard
errno.h	Standard error constants and functions to report errors
inttypes.h	Character literals for formal string format
iso646.h	All the macros defined by the standard
limits.h	Minimum and maximum for elementary C types
stdalign.h	Align and offset convenience macros
stdarg.h	Variadic function arguments support
stdbool.h	The boolean type, as defined by the standard
stddef.h	All the types defined by the standard
stdint.h	Signed and unsigned integers on 8,16 and 32 bits
stdlib.h	C standard library support
stdnoreturn.h	Convenience macro for non-returning functions
string.h	All the functions defined by the standard
stdio.h	printf, puts, putchar functions

Other standard definitions are not available, since they do not fit with the context of UPMEM DPU.

The include files are located in $UPMEM_HOME/share/upmem/include/stdlib and contain a brief explanation of each function. Next is an overview of the include files.

assert.h

Standard assertions are disabled when the source code is compiled with NDEBUG defined.

By default, the assert macro executes a given expression and issues an assertion failure (see Exceptions) if the expression is not true.

ctype.h

This include contains a collection of utilities to test characters properties:

• isdigit : character is a digit, i.e. in the range [‘0’,’9’]

• islower : character is a lower-case letter, i.e. in the range [‘a’,’z’]

• isupper : character is an upper-case letter, i.e. in the range [‘A’,’Z’]

• isalpha : character is a letter, i.e. either a lower or upper-case letter

• isalnum : character is alpha-numeric, i.e. either a letter or a digit

• iscntrl : character is a control character, i.e. lower than the space character or 0x7f

• isprint : character is not a control character, implying that it is printable

• isgraph : character has a locale representation, i.e. it is printable and is not a space

• ispunct : character is a printable, non alpha-numeric character

• isspace : character is a space, i.e. one of ‘\t’, ‘\n’, ‘\v’, ‘\f’, ‘\r’ or a space

• isxdigit : character is an hexa-decimal digit, i.e. in one of the ranges [‘0’,’9’], [‘a’,’f’] or [‘A’,’F’]

• isblank : character is a common space, i.e. either a space or ‘\t’

Also, the following conversion functions are provided:

• tolower : if the character is a lower-case letter, converts it to its upper-case value

• toupper : if the character is an upper-case letter, converts it to its lower-case value

errno.h

Because of the native multi-threaded nature of DPU programs, this implementation of error numbers exposes the last error as a thread-local global variable errno

The file also defines the standard C error codes specified by default:

Constant name	Value
E2BIG	1
EACCES	2
EADDRINUSE	3
EADDRNOTAVAIL	4
EAFNOSUPPORT	5
EAGAIN	6
EALREADY	7
EBADF	8
EBADMSG	9
EBUSY	10
ECANCELED	11
ECHILD	12
ECONNABORTED	13
ECONNREFUSED	14
ECONNRESET	15
EDEADLK	16
EDESTADDRREQ	17
EDOM	18
EDQUOT	19
EEXIST	20
EFAULT	21
EFBIG	22
EHOSTUNREACH	23
EIDRM	24
EILSEQ	25
EINPROGRESS	26
EINTR	27
EINVAL	28
EIO	29
EISCONN	30
EISDIR	31
ELOOP	32
EMFILE	33
EMLINK	34
EMSGSIZE	35
EMULTIHOP	36
ENAMETOOLONG	37
ENETDOWN	38
ENETRESET	39
ENETUNREACH	40
ENFILE	41
ENOBUFS	42
ENODATA	43
ENODEV	44
ENOENT	45
ENOEXEC	46
ENOLCK	47
ENOLINK	48
ENOMEM	49
ENOMSG	50
ENOPROTOOPT	51
ENOSPC	52
ENOSR	53
ENOSTR	54
ENOSYS	55
ENOTCONN	56
ENOTDIR	57
ENOTEMPTY	58
ENOTRECOVERABLE	59
ENOTSOCK	60
ENOTSUP	61
ENOTTY	62
ENXIO	63
EOPNOTSUPP	ENOTSUP
EOVERFLOW	65
EOWNERDEAD	66
EPERM	67
EPIPE	68
EPROTO	69
EPROTONOSUPPORT	70
EPROTOTYPE	71
ERANGE	72
EROFS	73
ESPIPE	74
ESRCH	75
ESTALE	76
ETIME	77
ETIMEDOUT	78
ETXTBSY	79
EWOULDBLOCK	ENOTSUP
EXDEV	81

inttypes.h

This extension of stdint.h defines convenience functions imaxabs and imaxdiv and the normalized string prefixes to represent integers in string formatters.

iso646.h

The C90 standard introduced logical operators represented by bitwise operations:

• and : stands for &&

• and_eq : stands for &=

• bitand : stands for &

• bitor : stands for |

• compl : stands for ~

• not : stands for !

• not_eq : stands for !=

• or : stands for ||

• or_eq : stands for |=

• xor : stands for ^

• xor_eq : stands for ^=

limits.h

Defines the standard limits of elementary types:

• SCHAR_MIN

• SCHAR_MAX

• UCHAR_MAX

• SHRT_MIN

• SHRT_MAX

• USHRT_MAX

• INT_MIN

• INT_MAX

• UINT_MAX

• LONG_MIN

• LONG_MAX

• ULONG_MAX

stdalign.h

Defines the macros:

• alignas to specify the alignment of a variable (e.g. struct alignas(8) X {...}, to align on 64-bits)

• alignof to fetch the alignment of a given data type

stdarg.h

Defines the standard type va_list and the associated standard macros:

• va_start(ap, param)

• va_end(ap)

• va_arg(ap, type)

• va_copy(dest, src)

stdbool.h

This include file defines the normalized type bool and values true and false, equal to 1 and 0, respectively.

stddef.h

Defines standard common types and helpers:

• The NULL pointer

• The standard types:

  • ptrdiff_t

  • size_t

  • max_align_t

  • wchar_t

• offsetof, to get the offset of a field within a structure

stdint.h

Defines the integer types implemented by the DPU, in particular:

• int8_t, int16_t, int32_t and int64_t for signed integers of 8, 16, 32 and 64 bits, respectively

• uint8_t, uint16_t, uint32_t and uint64_t for unsigned integers of 8, 16, 32 and 64 bits, respectively

stdlib.h

Defines the following functions of the C standard library:

• abort(): sets the DPU into fault, so that the whole processor execution terminates

• exit(): aborts the execution of the invoking thread

• getenv(): returns NULL

• abs, labs and llabs: the absolute value of integers, longs and long longs

• div, ldiv and lldiv: return the numerator and denominator of a division

• atoi and atol: convert strings to integers and longs

Note: stdlib function strtol is not implemented.

stdnoreturn.h

Defines the noreturn macro, which can be used to specify that a function does not return.

string.h

The common string and buffer operations (only for WRAM pointers if not specified otherwise):

• memcmp(area1, area2, size) : compares size bytes of the buffers pointed by area1 and area2

• memset(area, value, size) : fills in size bytes of the buffer pointed by area with value (for both WRAM and MRAM pointer)

• memchr(area, character, size) : returns the first position of character within the size bytes of the buffer pointed by area, or NULL

• memcpy(destination, source, size) : copies size bytes of the buffer pointed by source into the buffer pointed by destination (for both WRAM and MRAM pointer)

• memmove : a safer (but slower) version of memcpy, considering overlapping buffers (for both WRAM and MRAM pointer)

• strlen(string) : returns the length of string

• strnlen(string, size) : returns the maximum between size and the length of string

• strcmp(string1, string2) : compares string1 with string2

• strncmp(string1, string2, size) : compares size bytes of string1 with string2

• strcat(destination, source) : appends the string source to destination

• strncat(destination, source, size) : appends the first size bytes of source to destination

• strchr(string, character) : returns the first occurrence of character within string, or NULL

• strrchr(string, character) : returns the last occurrence of character within string, or NULL

• strcpy(destination, source) : copies the string source into the buffer pointed by destination

• stpcpy(destination, source) : copies the string source into the buffer pointed by destination

• strncpy(destination, source, size) : copies at most size bytes of source into the buffer pointed by destination

• stpncpy(destination, source, size) : copies at most size bytes of source into the buffer pointed by destination

• strcoll is an alias of strcmp, since there is no notion of locale in the runtime environment

• strxfrm is an alias of strncpy, since there is no notion of locale in the runtime environment

• strlwr(string) : converts string to lowercase characters

• strupr(string) : converts string to uppercase characters

• strrev(string) : reverses the characters of string

• strerr(errnum) : gives a description of the error corresponding to error number errnum

• strdup(string) : creates a duplicate of string

• strndup(string, size) : creates a duplicate of at most size bytes of string

• strspn(string, accept) : computes the length of the longest prefix of string which consists entirely of bytes in accept

• strcspn(string, reject) : computes the length of the longest prefix of string which consists entirely of bytes not in reject

• strpbrk(string, accept) : locates the first occurrence in string of any of the bytes in accept

• strstr(haystack, needle) : finds the first occurrence of needle in haystack

• strtok_r(string, separator, save) : extract a token delimited by separator from string

• strsep(string, separator) : extract a token delimited by separator from string

stdio.h

It defines the following standard functions:

• printf

• puts

• putchar

For more information about logging see Section Logging.

Not-supported headers

The following headers are not implemented in the DPU standard library:

• complex.h

• locale.h

• math.h

• setjmp.h

• signal.h

• stdatomic.h

• tgmath.h

• threads.h

• time.h

Floating point support

The system library re-uses the LLVM floating-point emulation functions so that floating points can be used natively in C. However, this is pure software emulation, giving very poor performance results: floating points shall be used for very specific non-time-critical operations.