Toolchain functions

Macros
#define	MBED_PACKED(struct)   struct __attribute__((packed))
	MBED_PACKED Pack a structure, preventing any padding from being added between fields.
#define	MBED_ALIGN(N)   alignas(N)
	MBED_ALIGN(N) Declare a variable to be aligned on an N-byte boundary.
#define	MBED_UNUSED
	MBED_UNUSED Declare a function argument to be unused, suppressing compiler warnings.
#define	MBED_USED
	MBED_USED Inform the compiler that a static variable is to be retained in the object file, even if it is unreferenced.
#define	MBED_WEAK   __attribute__((weak))
	MBED_WEAK Mark a function as being weak.
#define	MBED_PURE
	MBED_COMPILER_BARRIER Stop the compiler moving memory accesses.
#define	MBED_NOINLINE
	MBED_NOINLINE Declare a function that must not be inlined.
#define	MBED_FORCEINLINE   inline
	MBED_FORCEINLINE Declare a function that must always be inlined.
#define	MBED_NORETURN   [[noreturn]]
	MBED_NORETURN Declare a function that will never return.
#define	MBED_UNREACHABLE   while (1)
	MBED_UNREACHABLE An unreachable statement.
#define	MBED_FALLTHROUGH   [[fallthrough]]
	MBED_FALLTHROUGH Marks a point in a switch statement where fallthrough can occur.
#define	MBED_DEPRECATED_SINCE(D, M)   MBED_DEPRECATED(M " [since " D "]")
	MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warning will be issued by the compiler possibly including the provided message.
#define	MBED_CALLER_ADDR()   (NULL)
	MBED_CALLER_ADDR() Returns the caller of the current function.
#define	MBED_PRETTY_FUNCTION   __PRETTY_FUNCTION__
	Macro expanding to a string literal of the enclosing function name.
#define	MBED_NONCACHED_SECTION_NAME   ".noncached"
	Name of the section where non-cached data is stored.
#define	MBED_NONCACHED   MBED_SECTION(MBED_NONCACHED_SECTION_NAME)
	Attach to a global variable to put it in the noncached section.
#define	MBED_NONSECURE_ENTRY
	MBED_NONSECURE_ENTRY Declare a function that can be called from non-secure world or secure world.

Detailed Description

Macro Definition Documentation

MBED_PACKED

#define MBED_PACKED

(

struct

)

struct __attribute__((packed))

MBED_PACKED Pack a structure, preventing any padding from being added between fields.

#include "mbed_toolchain.h"
 
MBED_PACKED(struct) foo {
    char x;
    int y;
};

Definition at line 76 of file mbed_toolchain.h.

MBED_ALIGN

#define MBED_ALIGN

(

N

)

alignas(N)

MBED_ALIGN(N) Declare a variable to be aligned on an N-byte boundary.

Note

IAR does not support alignment greater than word size on the stack

#include "mbed_toolchain.h"
 
MBED_ALIGN(16) char a;

Definition at line 94 of file mbed_toolchain.h.

MBED_UNUSED

#define MBED_UNUSED

MBED_UNUSED Declare a function argument to be unused, suppressing compiler warnings.

#include "mbed_toolchain.h"
 
void foo(MBED_UNUSED int arg) {
 
}

Definition at line 119 of file mbed_toolchain.h.

MBED_USED

#define MBED_USED

MBED_USED Inform the compiler that a static variable is to be retained in the object file, even if it is unreferenced.

#include "mbed_toolchain.h"
 
MBED_USED int foo;

Definition at line 139 of file mbed_toolchain.h.

MBED_WEAK

#define MBED_WEAK   __attribute__((weak))

MBED_WEAK Mark a function as being weak.

Note

Functions should only be marked as weak in the source file. The header file should contain a regular function declaration to insure the function is emitted. A function marked weak will not be emitted if an alternative non-weak implementation is defined.

Weak functions are not friendly to making code re-usable, as they can only be overridden once (and if they are multiply overridden the linker will emit no warning). You should not normally use weak symbols as part of the API to re-usable modules.

#include "mbed_toolchain.h"
 
MBED_WEAK void foo() {
    // a weak implementation of foo that can be overriden by a definition
    // without  __weak
}

Definition at line 173 of file mbed_toolchain.h.

MBED_PURE

#define MBED_PURE

MBED_COMPILER_BARRIER Stop the compiler moving memory accesses.

The barrier stops memory accesses from being moved from one side of the barrier to the other for safety against other threads and interrupts.

This macro should only be used if we know only one CPU is accessing the data, or we are otherwise synchronising CPUs via acquire/release instructions. Otherwise, use MBED_BARRIER, which will act as a compiler barrier and also a CPU barrier if necessary.

Definition at line 261 of file mbed_toolchain.h.

MBED_NOINLINE

#define MBED_NOINLINE

MBED_NOINLINE Declare a function that must not be inlined.

#include "mbed_toolchain.h"
 
MBED_NOINLINE void foo() {
 
}

Definition at line 282 of file mbed_toolchain.h.

MBED_FORCEINLINE

#define MBED_FORCEINLINE   inline

MBED_FORCEINLINE Declare a function that must always be inlined.

Failure to inline such a function will result in an error.

#include "mbed_toolchain.h"
 
MBED_FORCEINLINE void foo() {
 
}

Definition at line 304 of file mbed_toolchain.h.

MBED_NORETURN

#define MBED_NORETURN   [[noreturn]]

MBED_NORETURN Declare a function that will never return.

#include "mbed_toolchain.h"
 
MBED_NORETURN void foo() {
    // must never return
    while (1) {}
}

Definition at line 322 of file mbed_toolchain.h.

MBED_UNREACHABLE

#define MBED_UNREACHABLE   while (1)

MBED_UNREACHABLE An unreachable statement.

If the statement is reached, behavior is undefined. Useful in situations where the compiler cannot deduce if the code is unreachable.

#include "mbed_toolchain.h"
 
void foo(int arg) {
    switch (arg) {
        case 1: return 1;
        case 2: return 2;
        ...
    }
    MBED_UNREACHABLE;
}

Definition at line 356 of file mbed_toolchain.h.

MBED_FALLTHROUGH

#define MBED_FALLTHROUGH   [[fallthrough]]

MBED_FALLTHROUGH Marks a point in a switch statement where fallthrough can occur.

Should be placed as the last statement before a label.

#include "mbed_toolchain.h"
 
int foo(int arg) {
    switch (arg) {
        case 1:
        case 2:
        case 3:
            arg *= 2;
            MBED_FALLTHROUGH;
        default:
            return arg;
    }
}

Definition at line 382 of file mbed_toolchain.h.

MBED_DEPRECATED_SINCE

#define MBED_DEPRECATED_SINCE	(		D,
			M
	)		MBED_DEPRECATED(M " [since " D "]")

MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warning will be issued by the compiler possibly including the provided message.

Note that not all compilers are able to display the message.

#include "mbed_toolchain.h"
 
MBED_DEPRECATED("don't foo any more, bar instead")
void foo(int arg);

MBED_DEPRECATED_SINCE("version", "message string") Mark a function declaration as deprecated, noting that the declaration was deprecated on the specified version. If the function is used then a warning will be issued by the compiler possibly including the provided message. Note that not all compilers are able to display this message.

#include "mbed_toolchain.h"
 
MBED_DEPRECATED_SINCE("mbed-os-5.1", "don't foo any more, bar instead")
void foo(int arg);

Definition at line 434 of file mbed_toolchain.h.

MBED_CALLER_ADDR

#define MBED_CALLER_ADDR

(

)

(NULL)

MBED_CALLER_ADDR() Returns the caller of the current function.

Note

This macro is only implemented for GCC and ARMCC.

#include "mbed_toolchain.h"
 
printf("This function was called from %p", MBED_CALLER_ADDR());

Returns

Address of the calling function

Definition at line 454 of file mbed_toolchain.h.

MBED_PRETTY_FUNCTION

#define MBED_PRETTY_FUNCTION   __PRETTY_FUNCTION__

Macro expanding to a string literal of the enclosing function name.

The string returned takes into account language specificity and yield human readable content.

As an example, if the macro is used within a C++ function then the string literal containing the function name will contain the complete signature of the function - including template parameters - and namespace qualifications.

Definition at line 479 of file mbed_toolchain.h.

MBED_NONCACHED_SECTION_NAME

#define MBED_NONCACHED_SECTION_NAME   ".noncached"

Name of the section where non-cached data is stored.

Definition at line 484 of file mbed_toolchain.h.

MBED_NONCACHED

#define MBED_NONCACHED   MBED_SECTION(MBED_NONCACHED_SECTION_NAME)

Attach to a global variable to put it in the noncached section.

Note that this section is always zero-initialized at boot, and any initial value assigned to noncached values is ignored.

Definition at line 489 of file mbed_toolchain.h.

MBED_NONSECURE_ENTRY

#define MBED_NONSECURE_ENTRY

MBED_NONSECURE_ENTRY Declare a function that can be called from non-secure world or secure world.

#include "mbed_toolchain.h"
 
MBED_NONSECURE_ENTRY void foo() {
 
}

Definition at line 579 of file mbed_toolchain.h.