core/lib: Add macros/utils.h header

The macros CONCAT(), MIN(), and MAX() are defined over and over again in
RIOT's code base. This de-duplicates the code by moving the macros to a
common place.

core/lib/include/macros/utils.h

@@ -0,0 +1,71 @@
+/*
+ * Copyright (C) 2023 Otto-von-Guericke-Universität Magdeburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     core_macros
+ * @{
+ *
+ * @file
+ * @brief       Various helper macros
+ *
+ * @author      Marian Buschsieweke <marian.buschsieweke@ovgu.de>
+ */
+
+#ifndef MACROS_UTILS_H
+#define MACROS_UTILS_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   Concatenate the tokens @p a and @p b
+ */
+#define CONCAT(a, b) a ## b
+
+/**
+ * @brief   Concatenate the tokens @p a , @p b , and @p c
+ */
+#define CONCAT3(a, b, c) a ## b ## c
+
+/**
+ * @brief   Concatenate the tokens @p a , @p b , @p c , and @p d
+ */
+#define CONCAT4(a, b, c, d) a ## b ## c ## d
+
+/* For compatibility with vendor headers, only provide MAX() and MIN() if not
+ * provided. (The alternative approach of using #undef has the downside that
+ * vendor header files may provide a smarter version of MAX() / MIN() that does
+ * not evaluate the argument twice and rely on this).
+ */
+#ifndef MAX
+/**
+ * @brief   Get the maximum of the two parameters
+ *
+ * @note    This is the trivial implementation that does evaluate the arguments
+ *          more than once
+ */
+#define MAX(a, b) ((a) > (b) ? (a) : (b))
+#endif
+
+#ifndef MIN
+/**
+ * @brief   Get the minimum of the two parameters
+ *
+ * @note    This is the trivial implementation that does evaluate the arguments
+ *          more than once
+ */
+#define MIN(a, b) ((a) < (b) ? (a) : (b))
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* MACROS_UTILS_H */
+/** @} */

cpu/atmega_common/periph/rtt.c

@@ -48,6 +48,7 @@
 #include "byteorder.h"
 #include "cpu.h"
 #include "irq.h"
+#include "macros/utils.h"
 #include "periph/rtt.h"
 #include "periph_conf.h"
 
@@ -91,11 +92,6 @@ static inline void reg32_write(volatile uint8_t *reg_ll, uint32_t _val)
     irq_restore(state);
 }
 
-/* To build proper register names */
-#ifndef CONCAT
-#define CONCAT(a, b) (a##b)
-#endif
-
 /* To read the whole 32-bit register */
 #define RG_READ32(reg)  (reg32_read(&CONCAT(reg, LL)))
 

cpu/esp_common/include/esp_common.h

@@ -28,6 +28,7 @@ extern "C" {
 
 #include "log.h"
 #include "esp_common_log.h"
+#include "macros/utils.h"
 #include "macros/xtstr.h"
 
 #if !defined(ICACHE_FLASH)
@@ -93,16 +94,6 @@ extern "C" {
 
 #endif /* ENABLE_DEBUG */
 
-/** gives the minimum of a and b */
-#ifndef MIN
-#define MIN(a, b) ((a) < (b) ? (a) : (b))
-#endif
-
-/** gives the maximum of a and b */
-#ifndef MAX
-#define MAX(a, b) ((a) > (b) ? (a) : (b))
-#endif
-
 /**
   * @brief  function name mappings for source code compatibility with ESP8266 port
   * @{

cpu/native/mtd/mtd_native.c

@@ -15,20 +15,18 @@
  * @author      Vincent Dupont <vincent@otakeys.com>
  */
 
-#include <stdio.h>
-#include <inttypes.h>
 #include <errno.h>
+#include <inttypes.h>
+#include <stdio.h>
 
+#include "macros/utils.h"
 #include "mtd.h"
 #include "mtd_native.h"
-
 #include "native_internal.h"
 
 #define ENABLE_DEBUG 0
 #include "debug.h"
 
-#define MIN(a, b) ((a) > (b) ? (b) : (a))
-
 static int _init(mtd_dev_t *dev)
 {
     mtd_native_dev_t *_dev = (mtd_native_dev_t*) dev;

cpu/sam0_common/periph/flashpage.c

@@ -30,14 +30,13 @@
 #include <string.h>
 
 #include "cpu.h"
+#include "macros/utils.h"
 #include "periph/flashpage.h"
 #include "unaligned.h"
 
 #define ENABLE_DEBUG 0
 #include "debug.h"
 
-#define MIN(x, y) (((x) < (y)) ? (x) : (y))
-
 /* Write Quad Word is the only allowed operation on AUX pages */
 #if defined(NVMCTRL_CTRLB_CMD_WQW)
 #define AUX_CHUNK_SIZE  (4 * sizeof(uint32_t))

cpu/stm32/periph/eth.c

@@ -27,6 +27,7 @@
 #include "bitarithm.h"
 #include "board.h"
 #include "iolist.h"
+#include "macros/utils.h"
 #include "mii.h"
 #include "mutex.h"
 #include "net/ethernet.h"
@@ -34,7 +35,7 @@
 #include "net/netdev/eth.h"
 #include "periph/gpio.h"
 #include "periph/gpio_ll.h"
-#include "timex.h"
+#include "time_units.h"
 
 #define ENABLE_DEBUG            0
 #define ENABLE_DEBUG_VERBOSE    0
@@ -91,8 +92,6 @@ static ztimer_t _link_status_timer;
 #warning "Total RX buffers lower than MTU, you won't receive huge frames!"
 #endif
 
-#define MIN(a, b) (((a) <= (b)) ? (a) : (b))
-
 /**
  * @name    GPIOs to use for tracing STM32 Ethernet state via module
  *          `stm32_eth_tracing`

drivers/at24cxxx/at24cxxx.c

@@ -22,6 +22,7 @@
 #include <string.h>
 
 #include "assert.h"
+#include "macros/utils.h"
 #include "xtimer.h"
 
 #include "at24cxxx_defines.h"
@@ -30,10 +31,6 @@
 #define ENABLE_DEBUG 0
 #include "debug.h"
 
-#ifndef MIN
-#define MIN(a, b) ((a) > (b) ? (b) : (a))
-#endif
-
 /**
  * @brief Calculate x mod y, if y is a power of 2
  */

drivers/lsm6dsl/lsm6dsl.c

@@ -23,6 +23,7 @@
 #include <assert.h>
 
 #include "ztimer.h"
+#include "macros/utils.h"
 
 #include "lsm6dsl.h"
 #include "lsm6dsl_internal.h"
@@ -30,8 +31,6 @@
 #define ENABLE_DEBUG 0
 #include "debug.h"
 
-#define MAX(a, b) ((a) > (b) ? (a) : (b))
-
 #define BUS         (dev->params.i2c)
 #define ADDR        (dev->params.addr)
 

drivers/mtd_sdcard/mtd_sdcard.c

@@ -20,18 +20,17 @@
  */
 #define ENABLE_DEBUG 0
 #include "debug.h"
+#include "kernel_defines.h"
+#include "macros/utils.h"
 #include "mtd.h"
 #include "mtd_sdcard.h"
 #include "sdcard_spi.h"
 #include "sdcard_spi_internal.h"
-#include "kernel_defines.h"
 
 #include <inttypes.h>
 #include <errno.h>
 #include <string.h>
 
-#define MIN(a, b) ((a) > (b) ? (b) : (a))
-
 static int mtd_sdcard_init(mtd_dev_t *dev)
 {
     DEBUG("mtd_sdcard_init\n");

drivers/mtd_spi_nor/mtd_spi_nor.c

@@ -25,16 +25,18 @@
 #include <string.h>
 #include <errno.h>
 
+#include "byteorder.h"
 #include "kernel_defines.h"
+#include "macros/utils.h"
 #include "mtd.h"
+#include "mtd_spi_nor.h"
+#include "thread.h"
+
 #if IS_USED(MODULE_ZTIMER_USEC)
 #include "ztimer.h"
 #elif IS_USED(MODULE_XTIMER)
 #include "xtimer.h"
 #endif
-#include "thread.h"
-#include "byteorder.h"
-#include "mtd_spi_nor.h"
 
 #define ENABLE_DEBUG    0
 #include "debug.h"
@@ -61,8 +63,6 @@
 
 #define MBIT_AS_BYTES       ((1024 * 1024) / 8)
 
-#define MIN(a, b) ((a) > (b) ? (b) : (a))
-
 /**
  * @brief   JEDEC memory manufacturer ID codes.
  *

pkg/lua/contrib/lua_run.c

@@ -23,6 +23,7 @@
 #include <setjmp.h>
 
 #include "kernel_defines.h"
+#include "macros/utils.h"
 #include "tlsf.h"
 
 #include "lua.h"
@@ -272,7 +273,6 @@ LUALIB_API int lua_riot_do_buffer(const uint8_t *buf, size_t buflen, void *memor
 }
 
 #define MAX_ERR_STRING (ARRAY_SIZE(lua_riot_str_errors) - 1)
-#define MIN(x, y) (((x) < (y)) ? (x) : (y))
 
 LUALIB_API const char *lua_riot_strerror(int errn)
 {

sys/can/isotp/isotp.c

@@ -20,17 +20,17 @@
 #include <errno.h>
 #include <string.h>
 
-#include "net/gnrc/pktbuf.h"
-
-#include "can/isotp.h"
 #include "can/common.h"
+#include "can/isotp.h"
 #include "can/raw.h"
 #include "can/router.h"
-#include "thread.h"
+#include "macros/utils.h"
 #include "mutex.h"
+#include "net/gnrc/pktbuf.h"
+#include "thread.h"
 #include "timex.h"
-#include "ztimer.h"
 #include "utlist.h"
+#include "ztimer.h"
 
 #define ENABLE_DEBUG 0
 #include "debug.h"
@@ -88,8 +88,6 @@ static kernel_pid_t isotp_pid = KERNEL_PID_UNDEF;
 static struct isotp *isotp_list = NULL;
 static mutex_t lock = MUTEX_INIT;
 
-#define MIN(a, b)   (((a) < (b)) ? (a) : (b))
-
 static void _rx_timeout(void *arg);
 static int _isotp_send_fc(struct isotp *isotp, int ae, uint8_t status);
 static int _isotp_tx_send(struct isotp *isotp, struct can_frame *frame);

sys/hashes/aes128_cmac.c

@@ -24,8 +24,7 @@
 
 #include "crypto/ciphers.h"
 #include "hashes/aes128_cmac.h"
-
-#define MIN(a, b) a < b ? a : b
+#include "macros/utils.h"
 
 static void _xor128(uint8_t *x, uint8_t *y)
 {

sys/hashes/sha3.c

@@ -56,8 +56,11 @@
    ================================================================
  */
 
-#include <hashes/sha3.h>
 #include <stdint.h>
+#include <string.h>
+
+#include "hashes/sha3.h"
+#include "macros/utils.h"
 
 /**
  * Function to compute the Keccak[r, c] sponge function over a given input.
@@ -330,9 +333,6 @@ static void KeccakF1600_StatePermute(void *state)
    ================================================================
  */
 
-#include <string.h>
-#define MIN(a, b) ((a) < (b) ? (a) : (b))
-
 static void Keccak(unsigned int rate, unsigned int capacity, const unsigned char *input,
                    unsigned long long int inputByteLen, unsigned char delimitedSuffix,
                    unsigned char *output, unsigned long long int outputByteLen)

sys/include/atomic_utils.h

@@ -139,6 +139,7 @@
 #include <stdint.h>
 
 #include "irq.h"
+#include "macros/utils.h"
 #include "sched.h"
 
 #include "atomic_utils_arch.h"
@@ -849,16 +850,6 @@ static inline uint64_t semi_atomic_fetch_and_u64(volatile uint64_t *dest,
 
 /* Fallback implementations of atomic utility functions: */
 
-/**
- * @brief   Concatenate two tokens
- */
-#define CONCAT(a, b) a ## b
-
-/**
- * @brief   Concatenate four tokens
- */
-#define CONCAT4(a, b, c, d) a ## b ## c ## d
-
 /**
  * @brief   Generates a static inline function implementing
  *          `atomic_load_u<width>()`

sys/net/gnrc/link_layer/lorawan/gnrc_lorawan_region.c

@@ -12,19 +12,17 @@
  * @file
  * @author  José Ignacio Alamos <jose.alamos@haw-hamburg.de>
  */
-#include "kernel_defines.h"
 #include "bitarithm.h"
-#include "random.h"
+#include "kernel_defines.h"
+#include "macros/utils.h"
 #include "net/gnrc/lorawan/region.h"
+#include "random.h"
 
 #define ENABLE_DEBUG 0
 #include "debug.h"
 
 #define GNRC_LORAWAN_DATARATES_NUMOF (6U)
 
-#define MIN(a, b) ((a) < (b) ? (a) : (b))
-#define MAX(a, b) ((a) > (b) ? (a) : (b))
-
 static uint8_t dr_sf[GNRC_LORAWAN_DATARATES_NUMOF] =
 { LORA_SF12, LORA_SF11, LORA_SF10, LORA_SF9, LORA_SF8, LORA_SF7 };
 static uint8_t dr_bw[GNRC_LORAWAN_DATARATES_NUMOF] =

sys/net/gnrc/netif/gnrc_netif_device_type.c

@@ -19,21 +19,21 @@
 #include <kernel_defines.h>
 
 #include "log.h"
+#include "macros/utils.h"
+#include "net/ethernet.h"
+#include "net/eui48.h"
+#include "net/gnrc/netif.h"
+#include "net/ieee802154.h"
+#include "net/l2util.h"
+
 #if IS_USED(MODULE_GNRC_NETIF_IPV6)
 #include "net/ipv6.h"
 #endif
-#include "net/gnrc/netif.h"
-#include "net/eui48.h"
-#include "net/ethernet.h"
-#include "net/ieee802154.h"
-#include "net/l2util.h"
+
 #if IS_USED(MODULE_GNRC_NETIF_6LO)
 #include "net/sixlowpan.h"
 #endif
 
-#define MAX(a, b) ((a) > (b) ? (a) : (b))
-#define MIN(a, b) ((a) < (b) ? (a) : (b))
-
 netopt_t gnrc_netif_get_l2addr_opt(const gnrc_netif_t *netif)
 {
     netopt_t res = NETOPT_ADDRESS;

sys/net/gnrc/network_layer/icmpv6/error/gnrc_icmpv6_error.c

@@ -14,13 +14,13 @@
 
 #include <assert.h>
 
-#include "net/ipv6.h"
-#include "net/gnrc/netreg.h"
+#include "macros/utils.h"
 #include "net/gnrc/icmpv6.h"
-#include "net/gnrc/netif.h"
-#include "net/gnrc/pktbuf.h"
-
 #include "net/gnrc/icmpv6/error.h"
+#include "net/gnrc/netif.h"
+#include "net/gnrc/netreg.h"
+#include "net/gnrc/pktbuf.h"
+#include "net/ipv6.h"
 
 #define ENABLE_DEBUG 0
 #include "debug.h"
@@ -30,9 +30,6 @@
 #define ICMPV6_ERROR_SET_VALUE(data, value) \
     ((icmpv6_error_pkt_too_big_t *)(data))->mtu = byteorder_htonl(value)
 
-#undef MIN
-#define MIN(a, b)   ((a) < (b)) ? (a) : (b)
-
 /**
  * @brief   Get packet fit.
  *

sys/stdio_rtt/stdio_rtt.c

@@ -76,9 +76,10 @@
 
 #include <string.h>
 
+#include "macros/utils.h"
+#include "mutex.h"
 #include "stdio_rtt.h"
 #include "thread.h"
-#include "mutex.h"
 #include "ztimer.h"
 
 #if MODULE_VFS
@@ -91,9 +92,6 @@
 #define STDIO_POLL_INTERVAL_MS 50U
 #endif
 
-#define MIN(a, b)        (((a) < (b)) ? (a) : (b))
-#define MAX(a, b)        (((a) > (b)) ? (a) : (b))
-
 #ifndef STDIO_TX_BUFSIZE
 #define STDIO_TX_BUFSIZE    (512)
 #endif

sys/test_utils/benchmark_udp/benchmark_udp.c

@@ -16,18 +16,17 @@
  */
 
 #include <stdio.h>
+
+#include "macros/utils.h"
 #include "net/sock/udp.h"
 #include "net/utils.h"
 #include "sema_inv.h"
-#include "xtimer.h"
-
 #include "test_utils/benchmark_udp.h"
+#include "xtimer.h"
 
 #define ENABLE_DEBUG 0
 #include "debug.h"
 
-#define MIN(a, b) ((a) > (b) ? (b) : (a))
-
 static sock_udp_t sock;
 static uint32_t delay_us = US_PER_SEC;
 static uint16_t payload_size = 32;

tests/bench_sys_atomic_utils/main.c

@@ -23,6 +23,7 @@
 #include <stdio.h>
 
 #include "atomic_utils.h"
+#include "macros/utils.h"
 #include "xtimer.h"
 
 /* On fast CPUs: 1.000.000 loops */
@@ -33,10 +34,6 @@
 #define LOOPS 100000
 #endif
 
-#define CONCAT(a, b) a ## b
-#define CONCAT3(a, b, c) a ## b ## c
-#define CONCAT4(a, b, c, d) a ## b ## c ## d
-
 enum {
     IMPL_VOLATILE,
     IMPL_ATOMIC_UTIL,

tests/bench_sys_base64/main.c

@@ -23,10 +23,9 @@
 
 #include "base64.h"
 #include "fmt.h"
+#include "macros/utils.h"
 #include "xtimer.h"
 
-#define MIN(a, b) (a < b) ? a : b
-
 static char buf[128];
 
 static const char input[96] = "This is an extremely, enormously, greatly, "

tests/driver_pn532/main.c

@@ -19,7 +19,7 @@
  */
 
 #include "board.h"
-
+#include "macros/utils.h"
 #include "pn532.h"
 #include "pn532_params.h"
 #include "ztimer.h"
@@ -27,8 +27,6 @@
 #define LOG_LEVEL LOG_INFO
 #include "log.h"
 
-#define MIN(a, b) ((a) < (b) ? (a) : (b))
-
 static void printbuff(char *buff, unsigned len)
 {
     while (len) {

tests/mtd_mapper/main.c

@@ -23,7 +23,7 @@
 #include <string.h>
 
 #include "embUnit.h"
-
+#include "macros/utils.h"
 #include "mtd.h"
 #include "mtd_mapper.h"
 
@@ -49,8 +49,6 @@
 
 #define REGION_PAGE_COUNT    MEMORY_PAGE_COUNT / 2
 
-#define MIN(x, y) (((x) < (y)) ? (x) : (y))
-
 static uint8_t _dummy_memory[MEMORY_SIZE];
 
 static uint8_t _buffer[PAGE_SIZE];