1 //*****************************************************************************
2 //
3 //! @file am_hal_debug.h
4 //!
5 //! @brief Useful Functions for Debugging.
6 //!
7 //! These functions and macros were created to assist with debugging. They are
8 //! intended to be as unintrusive as possible and designed to be removed from
9 //! the compilation of a project when they are no longer needed.
10 //!
11 //! @addtogroup haldebug3p Debug - HAL Debug/Assert Utilities
12 //! @ingroup apollo3p_hal
13 //! @{
14 //
15 //*****************************************************************************
16 
17 //*****************************************************************************
18 //
19 // Copyright (c) 2023, Ambiq Micro, Inc.
20 // All rights reserved.
21 //
22 // Redistribution and use in source and binary forms, with or without
23 // modification, are permitted provided that the following conditions are met:
24 //
25 // 1. Redistributions of source code must retain the above copyright notice,
26 // this list of conditions and the following disclaimer.
27 //
28 // 2. Redistributions in binary form must reproduce the above copyright
29 // notice, this list of conditions and the following disclaimer in the
30 // documentation and/or other materials provided with the distribution.
31 //
32 // 3. Neither the name of the copyright holder nor the names of its
33 // contributors may be used to endorse or promote products derived from this
34 // software without specific prior written permission.
35 //
36 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
37 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
38 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
39 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
40 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
41 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
42 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
43 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
44 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
45 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
46 // POSSIBILITY OF SUCH DAMAGE.
47 //
48 // This is part of revision release_sdk_3_1_1-10cda4b5e0 of the AmbiqSuite Development Package.
49 //
50 //*****************************************************************************
51 #ifndef AM_HAL_DEBUG_H
52 #define AM_HAL_DEBUG_H
53 
54 #ifdef __cplusplus
55 extern "C"
56 {
57 #endif
58 
59 
60 //*****************************************************************************
61 //
62 //! Determine DBG_FILENAME
63 //
64 //*****************************************************************************
65 //
66 // By spec and convention, the standard __FILE__ compiler macro includes a full
67 // path (absolute or relative) to the file being compiled. This makes recreating
68 // binaries virtually impossible unless rebuilt on the same or identically
69 // configured system.
70 //
71 // To be able to build consistent binaries on different systems, we want to make
72 // sure the full pathname is not included in the binary.  Only IAR EWARM provides
73 // an easy mechanism to provide only the filename without the path.  For other
74 // platforms, we will simply use a generic pathname.
75 //
76 #if defined (__IAR_SYSTEMS_ICC__)
77 //
78 // With EWARM the --no_path_in_file_macros option reduces __FILE__ to only the
79 //  module name.  Therefore this define assumes the option is being used.
80 //
81 #define DBG_FILENAME    __FILE__
82 #elif defined(__KEIL__)
83 //
84 // Keil provides __MODULE__ which is simply the module name portion of __FILE__.
85 //
86 #define DBG_FILENAME    __MODULE__
87 #elif defined(__ARMCC_VERSION)
88 #if (__ARMCC_VERSION >= 6000000)
89 #define DBG_FILENAME    __FILE_NAME__
90 #else
91 #define DBG_FILENAME    __MODULE__
92 #endif
93 #else
94 //
95 // With GCC, we're out of luck.
96 //
97 #define DBG_FILENAME    "debug_filename.ext"
98 //#define DBG_FILENAME    __FILE__
99 #endif
100 
101 //*****************************************************************************
102 //
103 //! Debug assert macros.
104 //
105 //*****************************************************************************
106 #ifndef AM_HAL_DEBUG_NO_ASSERT
107 
108 #define am_hal_debug_assert_msg(bCondition, pcMessage)                        \
109     if ( !(bCondition))  am_hal_debug_error(DBG_FILENAME, __LINE__, pcMessage)
110 
111 #define am_hal_debug_assert(bCondition)                                       \
112     if ( !(bCondition))  am_hal_debug_error(DBG_FILENAME, __LINE__, 0)
113 
114 #else
115 
116 #define am_hal_debug_assert_msg(bCondition, pcMessage)
117 #define am_hal_debug_assert(bCondition)
118 
119 #endif // AM_DEBUG_ASSERT
120 
121 //*****************************************************************************
122 //
123 //! @brief Default implementation of a failed ASSERT statement.
124 //!
125 //! @param pcFile is the name of the source file where the error occurred.
126 //! @param ui32Line is the line number where the error occurred.
127 //! @param pcMessage is an optional message describing the failure.
128 //!
129 //! This function is called by am_hal_debug_assert() macro when the supplied
130 //! condition is not true. The implementation here simply halts the application
131 //! for further analysis. Individual applications may define their own
132 //! implementations of am_hal_debug_error() to provide more detailed feedback
133 //! about the failed am_hal_debug_assert() statement.
134 //!
135 //! @note this function never returns
136 //
137 //*****************************************************************************
138 extern void am_hal_debug_error(const char *pcFile, uint32_t ui32Line,
139                                const char *pcMessage);
140 
141 #ifdef __cplusplus
142 }
143 #endif
144 
145 #endif // AM_HAL_DEBUG_H
146 
147 //*****************************************************************************
148 //
149 // End Doxygen group.
150 //! @}
151 //
152 //*****************************************************************************
153