general.h - definitions of general use to (standard) C programs More...

Macros
#define	CONCAT(a, b) a ## b

#define	EXPCONCAT(a, b) CONCAT(a, b)

#define	static_assert(e, msg) enum { EXPCONCAT(static_assert_, __LINE__) = 1/!!(e) }

#define	LOCAL static
	C has some very silly default behaviours. More...

#define	GLOBAL
	See above.

#define	NOBREAK
	Show reader that 'break' was not omitted by accident.

#define	FALLTHROUGH
	or if you prefer, use this word instead.

#define	PI 3.1415926535897932384626433832795028841971
	,

#define	HALFPI (PI / 2.0)
	,

#define	TWOPI (2.0 * PI)
	,

#define	SQRT2 1.4142135623730950488016887242096980785697
	,

#define	SQRT3 1.7320508075688772935274463415058723669428
	,

#define	DEG2RAD (PI / 180.0)
	degrees to radians

#define	RAD2DEG (180.0 / PI)
	radians to degrees

#define	SFA 1E-10
	A very small number, used to avoid divide by 0 errors.

#define	ARRAY_SIZE(x__) (int)(sizeof(x__)/sizeof(x__[0]))
	Because C passes arrays to functions by passing only a pointer to the zero'th element of the array, we often need to pass the array size in a separate argument to the function. More...

#define	ISPOWER2(x__) (!((x__)&((x__)-1)))
	There are times when we want to declare arrays or buffers whose dimension is a power of 2, so that the index value can be bit-masked to enforce wrap- around. More...

#define	ASSERTION_LEVEL 2 /* Pre & post-conditions checked */
	Useful macros for supporting a "Design by Contract" approach to programming embedded systems. More...

#define	USE_STANDARD_ASSERT

#define	DEFINE_THIS_FILE typedef int dummy_t
	Leave DEFINE_THIS_FILE undefined. More...

#define	ASSERT(test_) assert(test_)
	Uses standard assert.

#define	REQUIRE(test_) ASSERT(test_)
	Check preconditions.

#define	ENSURE(test_) ASSERT(test_)
	Check post-conditions.

#define	INVARIANT(test_) ((void)0)
	Invariant checks disabled.

#define	ENABLE_NULL_CHECKING

#define	REQUIRE_NOT_NULL(pointer_) ASSERT((pointer_) != NULL)
	,

Functions
static double	degToRad (double angle_deg)
	Returns angle_deg converted from degrees to radians.

static double	radToDeg (double angle_rad)
	Returns angle_rad converted from radians to degrees.

Detailed Description

general.h - definitions of general use to (standard) C programs

Author: David Hoadley vcrum.nosp@m.ble@.nosp@m.westn.nosp@m.et.c.nosp@m.om.au

Definitions that almost all of our C programs can find useful. Defines bool and fixed size int data types, if the compiler standard does not (i.e. if this is a pre-C99 compiler). Defines a static_assert() macro if this is a pre-C11 compiler. Some other useful constants and macros are defined, including macros for assertions in an embedded context.

Definition in file general.h.

Macro Definition Documentation

◆ LOCAL

#define LOCAL static

C has some very silly default behaviours.

One of these is to define all symbols declared at file level as global in scope (i.e. visible to the linker). This is a recipe for trouble. Secondly, C overloads the 'static' storage class (which defines how data is allocated to memory) with a second completely independent meaning - that the scope of the symbol name will be restricted to the current C source file only. While this is behaviour that we want, the use of the word 'static' is odd, to say the least. So, use the following definitions to discipline yourself to sensible behaviour - define truly global variables and functions as 'GLOBAL', and those which are to be visible only in the current C source file as 'LOCAL'. [Each global function definition should be matched with a corresponding function prototype in the corresponding header file, and each global variable definition should be matched with a corresponding 'extern' declaration in that same header file. There should be no 'extern' declarations outside of header files.]

Definition at line 133 of file general.h.

◆ ARRAY_SIZE

#define ARRAY_SIZE ( x__ ) (int)(sizeof(x__)/sizeof(x__[0]))

Because C passes arrays to functions by passing only a pointer to the zero'th element of the array, we often need to pass the array size in a separate argument to the function.

Make that easier.

Definition at line 194 of file general.h.

◆ ISPOWER2

#define ISPOWER2 ( x__ ) (!((x__)&((x__)-1)))

There are times when we want to declare arrays or buffers whose dimension is a power of 2, so that the index value can be bit-masked to enforce wrap- around.

Code based on this assumption will fail if the array size is changed by someone who doesn't notice this requirement. Here is a check you can use to help prevent that happening

Definition at line 201 of file general.h.

◆ ASSERTION_LEVEL

#define ASSERTION_LEVEL 2 /* Pre & post-conditions checked */

Useful macros for supporting a "Design by Contract" approach to programming embedded systems.

These are heavily influenced by the article "Design by Contract (DbC) for Embedded Software" by Miro Samek, to be found on the Barr Group website, at https://barrgroup.com/Embedded-Systems/How-To/Design-by-Contract-for-Embedded-Software

To use,

define an implementation of onAssert__() function as specified below. For example, it could write the first n chars of the filename and the line number to a bit of memory that won't be erased on a reboot, and then force a reboot.
spread REQUIRE(), ENSURE(), and INVARIANT() macros throughout your code. (In brief, REQUIRE() macros are generally put at the beginning of functions to check the validity of passed parameters. ENSURE() macros are generally placed at the end of functions to check that the functions have not calculated invalid results.)
put the DEFINE_THIS_FILE statement near the top of each C file that contains any REQUIRE(), ENSURE(), or INVARIANT() macros.
choose the ASSERTION_LEVEL that you want.

(If you define USE_STANDARD_ASSERT as described below, you don't really need to do steps 1 and 3. They are really for embedded systems.)

Definition at line 229 of file general.h.

◆ DEFINE_THIS_FILE

#define DEFINE_THIS_FILE typedef int dummy_t

Leave DEFINE_THIS_FILE undefined.

But we get a -Wextra-semi warning message if it is defined as nothing at all, so use this dummy declaration instead.

Definition at line 252 of file general.h.

Macros