This is the documentation for the latest (master) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Utilities

This page contains reference documentation for <sys/util.h>, which provides miscellaneous utility functions and macros.

group sys-util

Defines

POINTER_TO_UINT(x)

Cast x, a pointer, to an unsigned integer.

UINT_TO_POINTER(x)

Cast x, an unsigned integer, to a void*.

POINTER_TO_INT(x)

Cast x, a pointer, to a signed integer.

INT_TO_POINTER(x)

Cast x, a signed integer, to a void*.

BITS_PER_LONG

Number of bits in a long int.

GENMASK(h, l)

Create a contiguous bitmask starting at bit position l and ending at position h.

ZERO_OR_COMPILE_ERROR(cond)

0 if cond is true-ish; causes a compile error otherwise.

IS_ARRAY(array)

Zero if array has an array type, a compile error otherwise.

This macro is available only from C, not C++.

ARRAY_SIZE(array)

Number of elements in the given array.

In C++, due to language limitations, this will accept as array any type that implements operator[]. The results may not be particulary meaningful in this case.

In C, passing a pointer as array causes a compile error.

PART_OF_ARRAY(array, ptr)

Check if a pointer ptr lies within array.

In C but not C++, this causes a compile error if array is not an array (e.g. if ptr and array are mixed up).

Return

1 if ptr is part of array, 0 otherwise

Parameters
  • ptr: a pointer

  • array: an array

CONTAINER_OF(ptr, type, field)

Get a pointer to a container structure from an element.

Example:

 struct foo {
    int bar;
 };

 struct foo my_foo;
 int *ptr = &my_foo.bar;

 struct foo *container = CONTAINER_OF(ptr, struct foo, bar);

Above, container points at my_foo.

Return

a pointer to the structure that contains ptr

Parameters
  • ptr: pointer to a structure element

  • type: name of the type that ptr is an element of

  • field: the name of the field within the struct ptr points to

ROUND_UP(x, align)

Value of x rounded up to the next multiple of align, which must be a power of 2.

ROUND_DOWN(x, align)

Value of x rounded down to the previous multiple of align, which must be a power of 2.

WB_UP(x)

Value of x rounded up to the next word boundary.

WB_DN(x)

Value of x rounded down to the previous word boundary.

ceiling_fraction(numerator, divider)

Ceiling function applied to numerator / divider as a fraction.

MAX(a, b)

The larger value between a and b.

Note

Arguments are evaluated twice.

MIN(a, b)

The smaller value between a and b.

Note

Arguments are evaluated twice.

KB(x)

Number of bytes in x kibibytes.

MB(x)

Number of bytes in x mebibytes.

GB(x)

Number of bytes in x gibibytes.

KHZ(x)

Number of Hz in x kHz.

MHZ(x)

Number of Hz in x MHz.

BIT(n)

Unsigned integer with bit position n set (signed in assembly language).

BIT64(_n)

64-bit unsigned integer with bit position _n set.

WRITE_BIT(var, bit, set)

Set or clear a bit depending on a boolean value.

The argument var is a variable whose value is written to as a side effect.

Parameters
  • var: Variable to be altered

  • bit: Bit number

  • set: if 0, clears bit in var; any other value sets bit

BIT_MASK(n)

Bit mask with bits 0 through n-1 (inclusive) set, or 0 if n is 0.

Functions

bool is_power_of_two(unsigned int x)

Is x a power of two?

Return

true if x is a power of two, false otherwise

Parameters
  • x: value to check

int64_t arithmetic_shift_right(int64_t value, uint8_t shift)

Arithmetic shift right.

Return

value shifted right by shift; opened bit positions are filled with the sign bit

Parameters
  • value: value to shift

  • shift: number of bits to shift

int char2hex(char c, uint8_t *x)

Convert a single character into a hexadecimal nibble.

Return

Zero on success or (negative) error code otherwise.

Parameters
  • c: The character to convert

  • x: The address of storage for the converted number.

int hex2char(uint8_t x, char *c)

Convert a single hexadecimal nibble into a character.

Return

Zero on success or (negative) error code otherwise.

Parameters
  • c: The number to convert

  • x: The address of storage for the converted character.

size_t bin2hex(const uint8_t *buf, size_t buflen, char *hex, size_t hexlen)

Convert a binary array into string representation.

Return

The length of the converted string, or 0 if an error occurred.

Parameters
  • buf: The binary array to convert

  • buflen: The length of the binary array to convert

  • hex: Address of where to store the string representation.

  • hexlen: Size of the storage area for string representation.

size_t hex2bin(const char *hex, size_t hexlen, uint8_t *buf, size_t buflen)

Convert a hexadecimal string into a binary array.

Return

The length of the binary array, or 0 if an error occurred.

Parameters
  • hex: The hexadecimal string to convert

  • hexlen: The length of the hexadecimal string to convert.

  • buf: Address of where to store the binary data

  • buflen: Size of the storage area for binary data

uint8_t u8_to_dec(char *buf, uint8_t buflen, uint8_t value)

Convert a uint8_t into a decimal string representation.

Convert a uint8_t value into its ASCII decimal string representation. The string is terminated if there is enough space in buf.

Return

The length of the converted string (excluding terminator if any), or 0 if an error occurred.

Parameters
  • buf: Address of where to store the string representation.

  • buflen: Size of the storage area for string representation.

  • value: The value to convert to decimal string