firmware-base/docs-c/core/macros.md

title	description	keywords
Macros Utility Header	Documentation for the macros utility header which provides various helper macros for ESP32 C17 development	ESP32, C17, macros, utilities, embedded, industrial

Macros Utility

Path: src/modbus/macros.h

Revision History: Initial documentation

A comprehensive collection of utility macros for ESP-32 development. This header provides macro definitions for commonly used operations in embedded systems programming, avoiding the use of the standard library. It includes macros for type manipulation, bit operations, mathematical functions, array handling, compile-time optimizations, and more.

Requirements

• ESP-32 platform
• C17 compliant compiler
• No standard library dependencies

Provides

• Incrementation/Decrementation: INC_X, DEC_X, INCREMENT, DECREMENT
• Compiler Optimizations: FORCE_INLINE, _UNUSED, NOOP
• Argument Counting/Testing: NUM_ARGS, TWO_ARGS
• String Helpers: CAT, _CAT
• Conditional Compilation: ENABLED, DISABLED, ANY, ALL, NONE
• Bit Manipulation: __BV, TEST, SBI, CBI, SET_BIT_TO
• Math Operations: WITHIN, RADIANS, DEGREES, NEAR_ZERO
• Time Helpers: PENDING, ELAPSED, HOUR_MS, MIN_MS
• Array Initialization: ARRAY_N, ARRAY_1 through ARRAY_6
• C++11 Template Utilities: Min/Max templates, SFINAE helpers

Features

• Preprocessor macros for common calculations and operations
• Bit manipulation utilities
• Compile-time optimizations
• Safe type conversion helpers
• Template-based compile-time checks
• Time management utilities
• Array initialization helpers
• Conditional execution based on feature flags

Dependencies

• ./xtypes.h

graph TD
    Macros --> XTypes

Behavior

The macros in this header provide utility functions that are used throughout the codebase. They do not have state or flow by themselves but enable cleaner, more efficient code.

graph LR
    Application[Application Code] -->|Uses macros| Macros
    Macros -->|Expand at compile time| Optimized[Optimized Binary]

TODOs

Performance

• Consider separating into multiple headers for faster compilation
• Add pre-processor optimization for frequently used macro combinations

Security

• No direct security concerns as these are compile-time macros
• Ensure macros don't introduce unintended behaviors when used with user input

Compliance

• Compatible with C17 standard
• Designed for ESP-32 and industrial Modbus applications
• No use of standard library functions

Recommendations

• Group related macros when using in implementation files
• Use the ENABLED/DISABLED macros for feature toggling
• Prefer the template-based MIN/MAX over macro versions when in C++ code
• Consider the resource constraints of ESP-32 when using complex macro expansions