mikroSDK Reference Manual
tusb_verify.h
1/*
2 * The MIT License (MIT)
3 *
4 * Copyright (c) 2019 Ha Thach (tinyusb.org)
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 * THE SOFTWARE.
23 *
24 * This file is part of the TinyUSB stack.
25 */
26#ifndef TUSB_VERIFY_H_
27#define TUSB_VERIFY_H_
28
29#include <stdbool.h>
30#include <stdint.h>
31#include "tusb_option.h"
32#include "tusb_compiler.h"
33
34/*------------------------------------------------------------------*/
35/* This file use an advanced macro technique to mimic the default parameter
36 * as C++ for the sake of code simplicity. Beware of a headache macro
37 * manipulation that you are told to stay away.
38 *
39 * This contains macros for both VERIFY and ASSERT:
40 *
41 * VERIFY: Used when there is an error condition which is not the
42 * fault of the MCU. For example, bounds checking on data
43 * sent to the micro over USB should use this function.
44 * Another example is checking for buffer overflows, where
45 * returning from the active function causes a NAK.
46 *
47 * ASSERT: Used for error conditions that are caused by MCU firmware
48 * bugs. This is used to discover bugs in the code more
49 * quickly. One example would be adding assertions in library
50 * function calls to confirm a function's (untainted)
51 * parameters are valid.
52 *
53 * The difference in behavior is that ASSERT triggers a breakpoint while
54 * verify does not.
55 *
56 * #define TU_VERIFY(cond) if(cond) return false;
57 * #define TU_VERIFY(cond,ret) if(cond) return ret;
58 *
59 * #define TU_VERIFY_HDLR(cond,handler) if(cond) {handler; return false;}
60 * #define TU_VERIFY_HDLR(cond,ret,handler) if(cond) {handler; return ret;}
61 *
62 * #define TU_ASSERT(cond) if(cond) {_MESS_FAILED(); TU_BREAKPOINT(), return false;}
63 * #define TU_ASSERT(cond,ret) if(cond) {_MESS_FAILED(); TU_BREAKPOINT(), return ret;}
64 *
65 *------------------------------------------------------------------*/
66
67#ifdef __cplusplus
68 extern "C" {
69#endif
70
71//--------------------------------------------------------------------+
72// TU_VERIFY Helper
73//--------------------------------------------------------------------+
74
75#if CFG_TUSB_DEBUG
76 #include <stdio.h>
77 #define _MESS_FAILED() tu_printf("%s %d: ASSERT FAILED\r\n", __func__, __LINE__)
78#else
79 #define _MESS_FAILED() do {} while (0)
80#endif
81
82// Halt CPU (breakpoint) when hitting error, only apply for Cortex M3, M4, M7, M33
83#if defined(__ARM_ARCH_7M__) || defined (__ARM_ARCH_7EM__) || defined(__ARM_ARCH_8M_MAIN__)
84 #define TU_BREAKPOINT() do \
85 { \
86 volatile uint32_t* ARM_CM_DHCSR = ((volatile uint32_t*) 0xE000EDF0UL); /* Cortex M CoreDebug->DHCSR */ \
87 if ( (*ARM_CM_DHCSR) & 1UL ) __asm("BKPT #0\n"); /* Only halt mcu if debugger is attached */ \
88 } while(0)
89
90#elif defined(__riscv)
91 #define TU_BREAKPOINT() do { __asm("ebreak\n"); } while(0)
92
93#elif defined(_mips)
94 #define TU_BREAKPOINT() do { __asm("sdbbp 0"); } while (0)
95
96#else
97 #define TU_BREAKPOINT() do {} while (0)
98#endif
99
100/*------------------------------------------------------------------*/
101/* Macro Generator
102 *------------------------------------------------------------------*/
103
104// Helper to implement optional parameter for TU_VERIFY Macro family
105#define _GET_3RD_ARG(arg1, arg2, arg3, ...) arg3
106#define _GET_4TH_ARG(arg1, arg2, arg3, arg4, ...) arg4
107
108/*------------- Generator for TU_VERIFY and TU_VERIFY_HDLR -------------*/
109#define TU_VERIFY_DEFINE(_cond, _handler, _ret) do \
110{ \
111 if ( !(_cond) ) { _handler; return _ret; } \
112} while(0)
113
114/*------------------------------------------------------------------*/
115/* TU_VERIFY
116 * - TU_VERIFY_1ARGS : return false if failed
117 * - TU_VERIFY_2ARGS : return provided value if failed
118 *------------------------------------------------------------------*/
119#define TU_VERIFY_1ARGS(_cond) TU_VERIFY_DEFINE(_cond, , false)
120#define TU_VERIFY_2ARGS(_cond, _ret) TU_VERIFY_DEFINE(_cond, , _ret)
121
122#define TU_VERIFY(...) _GET_3RD_ARG(__VA_ARGS__, TU_VERIFY_2ARGS, TU_VERIFY_1ARGS, UNUSED)(__VA_ARGS__)
123
124
125/*------------------------------------------------------------------*/
126/* TU_VERIFY WITH HANDLER
127 * - TU_VERIFY_HDLR_2ARGS : execute handler, return false if failed
128 * - TU_VERIFY_HDLR_3ARGS : execute handler, return provided error if failed
129 *------------------------------------------------------------------*/
130#define TU_VERIFY_HDLR_2ARGS(_cond, _handler) TU_VERIFY_DEFINE(_cond, _handler, false)
131#define TU_VERIFY_HDLR_3ARGS(_cond, _handler, _ret) TU_VERIFY_DEFINE(_cond, _handler, _ret)
132
133#define TU_VERIFY_HDLR(...) _GET_4TH_ARG(__VA_ARGS__, TU_VERIFY_HDLR_3ARGS, TU_VERIFY_HDLR_2ARGS,UNUSED)(__VA_ARGS__)
134
135/*------------------------------------------------------------------*/
136/* ASSERT
137 * basically TU_VERIFY with TU_BREAKPOINT() as handler
138 * - 1 arg : return false if failed
139 * - 2 arg : return error if failed
140 *------------------------------------------------------------------*/
141#define ASSERT_1ARGS(_cond) TU_VERIFY_DEFINE(_cond, _MESS_FAILED(); TU_BREAKPOINT(), false)
142#define ASSERT_2ARGS(_cond, _ret) TU_VERIFY_DEFINE(_cond, _MESS_FAILED(); TU_BREAKPOINT(), _ret)
143
144#ifndef TU_ASSERT
145#define TU_ASSERT(...) _GET_3RD_ARG(__VA_ARGS__, ASSERT_2ARGS, ASSERT_1ARGS,UNUSED)(__VA_ARGS__)
146#endif
147
148/*------------------------------------------------------------------*/
149/* ASSERT HDLR
150 *------------------------------------------------------------------*/
151
152#ifdef __cplusplus
153 }
154#endif
155
156#endif /* TUSB_VERIFY_H_ */