1 /***************************************************************************//**
2  * @file
3  * @brief RAM code support.
4  *******************************************************************************
5  * # License
6  * <b>Copyright 2018 Silicon Laboratories Inc. www.silabs.com</b>
7  *******************************************************************************
8  *
9  * SPDX-License-Identifier: Zlib
10  *
11  * The licensor of this software is Silicon Laboratories Inc.
12  *
13  * This software is provided 'as-is', without any express or implied
14  * warranty. In no event will the authors be held liable for any damages
15  * arising from the use of this software.
16  *
17  * Permission is granted to anyone to use this software for any purpose,
18  * including commercial applications, and to alter it and redistribute it
19  * freely, subject to the following restrictions:
20  *
21  * 1. The origin of this software must not be misrepresented; you must not
22  *    claim that you wrote the original software. If you use this software
23  *    in a product, an acknowledgment in the product documentation would be
24  *    appreciated but is not required.
25  * 2. Altered source versions must be plainly marked as such, and must not be
26  *    misrepresented as being the original software.
27  * 3. This notice may not be removed or altered from any source distribution.
28  *
29  ******************************************************************************/
30 
31 #ifndef EM_RAMFUNC_H
32 #define EM_RAMFUNC_H
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /* *INDENT-OFF* */
39 /***************************************************************************//**
40  * @addtogroup ramfunc RAMFUNC - RAM Function Support
41  * @brief RAM code support
42  * @details
43  *  Provides support for executing code from RAM.
44  *  Provides a unified method to manage RAM code across all supported tools.
45  * @{
46 
47   @note
48    Other cross-compiler support macros are implemented in @ref common.
49 
50   @note
51     Functions executing from RAM should not be declared as static.
52 
53   @warning
54     Standard library facilities are available to the tool with GCC in hosted
55 	mode (default), regardless of the section attribute. Calls to standard
56     libraries placed in the default section may therefore occur. To disable
57     hosted mode, add '-ffreestanding' to the build command line. This is the
58     only way to guarantee no calls to standard libraries with GCC.
59     Read more at www.gcc.gnu.org/onlinedocs/gcc-5.3.0/gcc/Standards.html
60 
61   @warning
62     Keil/ARM uVision users must add a section named "ram_code" in their linker
63     scatter file. This section must be in RAM memory. Look in the MCU SDK for
64     example scatter files (ram_code.sct).
65 
66   @n @section ramfunc_usage Usage
67 
68   In your .h file:
69   @verbatim
70   #include "em_ramfunc.h"
71 
72   SL_RAMFUNC_DECLARATOR
73   void MyPrint(const char* string);
74   @endverbatim
75 
76   Issues have been observed with armgcc when there is no declarator. It is
77   recommended to have a declarator also for internal functions, but move the
78   declarator to the .c file.
79 
80   In your .c file:
81   @verbatim
82   #include "em_ramfunc.h"
83 
84   SL_RAMFUNC_DEFINITION_BEGIN
85   void MyPrint(const char* string)
86   {
87   ...
88   }
89   SL_RAMFUNC_DEFINITION_END
90   @endverbatim
91 
92  ******************************************************************************/
93 /* *INDENT-ON* */
94 
95 /*******************************************************************************
96  ******************************   DEFINES    ***********************************
97  ******************************************************************************/
98 
99 /**
100  * @brief
101  *    This define is not present by default. By compiling with define
102  *    @ref SL_RAMFUNC_DISABLE, code placed in RAM by SL_RAMFUNC macros
103  *    will be placed in default code space (Flash) instead.
104  *
105  * @note
106  *    This define is not present by default.
107  */
108 #if defined(DOXY_DOC_ONLY)
109 #define SL_RAMFUNC_DISABLE
110 #endif
111 
112 #if defined(SL_RAMFUNC_DISABLE)
113 /** @brief Compiler ported function declarator for RAM code. */
114 #define SL_RAMFUNC_DECLARATOR
115 
116 /** @brief Compiler ported function definition begin marker for RAM code. */
117 #define SL_RAMFUNC_DEFINITION_BEGIN
118 
119 /** @brief Compiler ported function definition end marker for RAM code. */
120 #define SL_RAMFUNC_DEFINITION_END
121 
122 #elif defined(__CC_ARM)
123 /* MDK-ARM compiler */
124 #define SL_RAMFUNC_DECLARATOR
125 #define SL_RAMFUNC_DEFINITION_BEGIN    _Pragma("arm section code=\"ram_code\"")
126 #define SL_RAMFUNC_DEFINITION_END      _Pragma("arm section code")
127 
128 #elif defined(__ICCARM__)
129 /* IAR Embedded Workbench */
130 #define SL_RAMFUNC_DECLARATOR          __ramfunc
131 #define SL_RAMFUNC_DEFINITION_BEGIN    SL_RAMFUNC_DECLARATOR
132 #define SL_RAMFUNC_DEFINITION_END
133 
134 #elif defined(__GNUC__) && (defined(__CROSSWORKS_ARM) || defined(__SES_ARM))
135 /* Rowley Crossworks and Segger Embedded Studio */
136 #define SL_RAMFUNC_DECLARATOR          __attribute__ ((section(".fast")))
137 #define SL_RAMFUNC_DEFINITION_BEGIN    SL_RAMFUNC_DECLARATOR
138 #define SL_RAMFUNC_DEFINITION_END
139 
140 #elif defined(__GNUC__)
141 /* Simplicity Studio, Atollic and Vanilla armgcc */
142 #define SL_RAMFUNC_DECLARATOR          __attribute__ ((section(".ramfunc")))
143 #define SL_RAMFUNC_DEFINITION_BEGIN    SL_RAMFUNC_DECLARATOR
144 #define SL_RAMFUNC_DEFINITION_END
145 
146 #endif
147 
148 /** @cond DO_NOT_INCLUDE_WITH_DOXYGEN */
149 /* Deprecated macro names */
150 #define RAMFUNC_DECLARATOR          SL_RAMFUNC_DECLARATOR
151 #define RAMFUNC_DEFINITION_BEGIN    SL_RAMFUNC_DEFINITION_BEGIN
152 #define RAMFUNC_DEFINITION_END      SL_RAMFUNC_DEFINITION_END
153 /** @endcond */
154 
155 /** @} (end addtogroup ramfunc) */
156 
157 #ifdef __cplusplus
158 }
159 #endif
160 
161 #endif /* EM_RAMFUNC_H */
162