debug.h

// SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause
/*
 * Copyright (C) 2026 Espressif Systems (Shanghai) CO LTD
 *
 * Logging conventions (grep / AI-friendly):
 *
 * - Use espwl_info / espwl_warn / espwl_err when you have struct espwl *m (or sip->wpub).
 *   Format string must end with '\n' (enforced by CHECK_FOR_NEWLINE).
 *
 * - Use espwl_dbg / espwl_dbg_limit for verbose paths; gated by CONFIG_ESPWL_DEBUG and
 *   module parameter debug= (same variable as debugfs debug_level). Makefile only enables/disables
 *   CONFIG_ESPWL_DEBUG; it does not set the bitmask (default after load is 0 until you set debug=).
 *
 * - Prefix message text with a subsystem tag and key=value pairs, e.g.
 *   "mac: set_sta phy=HE bw=80\n", "sip: txq_wake tx_credits=%d fw_credits=%d\n".
 *
 * - Prefer espwl_print_hex_dump or espwl_show_buf() for binary blobs instead of hand-rolled printk loops.
 *
 * Debug mask bits (see enum espwl_debug_mask):
 *   0x00000001 BOOT      0x00000002 FW        0x00000004 PCI       0x00000008 MAC
 *   0x00000010 MGMT      0x00000020 DATA      0x00000040 TESTMODE  0x00000080 PCI_PS
 *   0x00000100 SDIO      0x00000200 STA       0x00000400 BEACON    0x00000800 TX
 *   0x00001000 TRANS     0x00002000 SIP       0x00004000 SIP_EVT   0x00008000 SIP_PKT
 *   0xffffffff ANY (enable all)
 */
#ifndef __debug_h__
#define __debug_h__

#include <linux/types.h>
#include <linux/net.h> /* net_ratelimit() */

#include "core.h"
#include "modparams.h"
#include "debugfs.h"

static inline bool espwl_have_debug_level(u32 level)
{
#ifdef CONFIG_ESPWL_DEBUG
	return espwl_modparams.debug_level & level;
#else
	return false;
#endif
}

/**
 * ESPWL Debug messages
 */
enum espwl_debug_mask {
	ESPWL_DBG_BOOT = 0x00000001,
	ESPWL_DBG_FW = 0x00000002,
	ESPWL_DBG_PCI = 0x00000004,
	ESPWL_DBG_MAC = 0x00000008,
	ESPWL_DBG_MGMT = 0x00000010,
	ESPWL_DBG_DATA = 0x00000020,
	ESPWL_DBG_TESTMODE = 0x00000040,
	ESPWL_DBG_PCI_PS = 0x00000080,
	ESPWL_DBG_SDIO = 0x00000100,
	ESPWL_DBG_STA = 0x00000200,
	ESPWL_DBG_BEACON = 0x00000400, /* Print out beacon debug info */
	ESPWL_DBG_TX = 0x00000800,
	ESPWL_DBG_TRANS = 0x00001000,
	ESPWL_DBG_SIP = 0x00002000, /* SIP */
	ESPWL_DBG_SIP_EVT = 0x00004000, /* SIP Event */
	ESPWL_DBG_SIP_PKT = 0x00008000, /* SIP Packet */
	ESPWL_DBG_ANY = 0xffffffff,
};

__printf(2, 3) void __espwl_info(struct device *dev, const char *fmt, ...);
__printf(2, 3) void __espwl_warn(struct device *dev, const char *fmt, ...);
__printf(2, 3) void __espwl_err(struct device *dev, const char *fmt, ...);

/* not all compilers can evaluate strlen() at compile time, so use sizeof() */
#define CHECK_FOR_NEWLINE(f) BUILD_BUG_ON(f[sizeof(f) - 2] != '\n')

/* No matter what is m (priv, bus, sif), this will work */
#define espwl_info(m, f, a...)                  \
	do {                                    \
		CHECK_FOR_NEWLINE(f);           \
		__espwl_info((m)->dev, f, ##a); \
	} while (0)

#define espwl_warn(m, f, a...)                  \
	do {                                    \
		CHECK_FOR_NEWLINE(f);           \
		__espwl_warn((m)->dev, f, ##a); \
	} while (0)

#define espwl_err(m, f, a...)                  \
	do {                                   \
		CHECK_FOR_NEWLINE(f);          \
		__espwl_err((m)->dev, f, ##a); \
	} while (0)

#if defined(CONFIG_ESPWL_DEBUG)
void __espwl_dbg(struct device *dev, u32 level, bool limit,
		 const char *function, const char *fmt, ...) __printf(5, 6);
#else
__printf(5, 6) static inline void __espwl_dbg(struct device *dev, u32 level,
					      bool limit, const char *function,
					      const char *fmt, ...)
{
}
#endif

#define __espwl_dbg_dev(dev, level, limit, fmt, args...)               \
	do {                                                           \
		CHECK_FOR_NEWLINE(fmt);                                \
		__espwl_dbg(dev, level, limit, __func__, fmt, ##args); \
	} while (0)

#define espwl_dbg(m, level, fmt, args...) \
	__espwl_dbg_dev((m)->dev, level, false, fmt, ##args)

#define espwl_dbg_dev(dev, level, fmt, args...) \
	__espwl_dbg_dev(dev, level, false, fmt, ##args)

#define espwl_dbg_limit(m, level, fmt, args...) \
	__espwl_dbg_dev((m)->dev, level, true, fmt, ##args)

#ifdef CONFIG_ESPWL_DEBUG
#define espwl_print_hex_dump(level, p, len)                                    \
	do {                                                                   \
		if (espwl_have_debug_level(level))                             \
			print_hex_dump(KERN_DEBUG,                             \
				       "espwl data: ", DUMP_PREFIX_OFFSET, 16, \
				       1, p, len, 1);                          \
	} while (0)

int espwl_debug_create(struct espwl *wpub);

#else

#define espwl_print_hex_dump(level, p, len)

static inline int espwl_debug_create(struct espwl *wpub)
{
	return 0;
}

#endif /* CONFIG_ESPWL_DEBUG */

void espwl_show_buf(struct espwl *wpub, u32 level, const char *tag,
		    const void *buf, size_t len);

#endif /* #__debug_h__ */