1 //***************************************************************************** 2 // 3 //! @file am_util_stdio.h 4 //! 5 //! @brief A few printf-style functions for use with Ambiq products 6 //! 7 //! Functions for performing printf-style operations without dynamic memory 8 //! allocation. 9 //! 10 //! For further information about this module concerning its history, uses, 11 //! and limitations, please see the Ambiq Micro KB article "Q&A: What does 12 //! the AmbiqSuite SDK am_util_stdio_printf() function do?" at: 13 //! 14 //! https://support.ambiqmicro.com/hc/en-us/articles/360040441631 15 //! 16 //! @addtogroup stdio STDIO - Ambiq's Implementation 17 //! @ingroup utils 18 //! @{ 19 // 20 //***************************************************************************** 21 22 //***************************************************************************** 23 // 24 // Copyright (c) 2023, Ambiq Micro, Inc. 25 // All rights reserved. 26 // 27 // Redistribution and use in source and binary forms, with or without 28 // modification, are permitted provided that the following conditions are met: 29 // 30 // 1. Redistributions of source code must retain the above copyright notice, 31 // this list of conditions and the following disclaimer. 32 // 33 // 2. Redistributions in binary form must reproduce the above copyright 34 // notice, this list of conditions and the following disclaimer in the 35 // documentation and/or other materials provided with the distribution. 36 // 37 // 3. Neither the name of the copyright holder nor the names of its 38 // contributors may be used to endorse or promote products derived from this 39 // software without specific prior written permission. 40 // 41 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 42 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 43 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 44 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 45 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 46 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 47 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 48 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 49 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 51 // POSSIBILITY OF SUCH DAMAGE. 52 // 53 // This is part of revision release_sdk_4_4_0-3c5977e664 of the AmbiqSuite Development Package. 54 // 55 //***************************************************************************** 56 #ifndef AM_UTIL_STDIO_H 57 #define AM_UTIL_STDIO_H 58 59 /* get va_list from compiler. */ 60 #include <stdarg.h> 61 #include <stdbool.h> 62 63 #ifdef __cplusplus 64 extern "C" 65 { 66 #endif 67 //***************************************************************************** 68 // 69 // Macro definitions 70 // 71 //***************************************************************************** 72 73 // buffer size for printf 74 #ifndef AM_PRINTF_BUFSIZE 75 #define AM_PRINTF_BUFSIZE 1024 // Global printf buffer size 76 #endif 77 78 typedef void (*am_util_stdio_print_char_t)(char *pcStr); 79 80 //***************************************************************************** 81 // 82 // External function definitions 83 // 84 //***************************************************************************** 85 //***************************************************************************** 86 // 87 //! @brief Sets the interface for printf calls. 88 //! 89 //! @param pfnCharPrint - Function pointer to be used to print to interface 90 //! 91 //! This function initializes the global print function which is used for 92 //! printf. This allows users to define their own printf interface and pass it 93 //! in as a am_util_stdio_print_char_t type. 94 // 95 //***************************************************************************** 96 extern void am_util_stdio_printf_init(am_util_stdio_print_char_t pfnCharPrint); 97 98 //***************************************************************************** 99 // 100 //! @brief Converts strings to 32-bit unsigned integers. 101 //! 102 //! @param *str - Pointer to the string to convert 103 //! @param **endptr - strtoul will set this to the char after the converted num 104 //! @param base - Base of the number as written in the input string. 105 //! 106 //! This function was implemented in a way similar to the strtoul function 107 //! found in the C standard library. It will attempt to extract a numerical 108 //! value from the input string, and return it to the caller. Invalid input 109 //! strings will return a value of zero. 110 //! 111 //! @return uint32_t representing the numerical value from the string. 112 // 113 //***************************************************************************** 114 extern uint32_t am_util_stdio_strtoul(const char *str, char **endptr, int base); 115 116 //***************************************************************************** 117 // 118 //! @brief Text mode translates linefeed (\n) characters to carriage return/ 119 //! linefeed (CR/LF) combinations in printf() and sprintf() functions. 120 //! 121 //! @param bSetTextTranslationMode - true: Do LF to CR/LF translation. 122 //! false: Don't do the text mode translation. 123 //! 124 //! This function causes the printf() and sprintf() functions to translate 125 //! newline characters (\\n) into CR/LF (\\r\\n) combinations. 126 //! 127 //! @return Previous mode. 128 // 129 //***************************************************************************** 130 extern bool am_util_stdio_textmode_set(bool bSetTextTranslationMode); 131 132 //****************************************************************************** 133 // 134 //! @brief Format data into string. (va_list implementation) 135 //! 136 //! @param *pcBuf - Pointer to the buffer to store the string 137 //! @param *pcFmt - Pointer to formatter string 138 //! @param *pArgs - Pointer to extended arguments 139 //! 140 //! A lite version of vsprintf(). 141 //! Currently handles the following specifiers: 142 //! %c 143 //! %s 144 //! %[0][width]d (also %i) 145 //! %[0][width]u 146 //! %[0][width]x 147 //! %[.precision]f 148 //! 149 //! Note than any unrecognized or unhandled format specifier character is 150 //! simply printed. For example, "%%" will print a '%' character. 151 //! 152 //! @return uint32_t representing the number of characters printed. 153 // 154 //****************************************************************************** 155 extern uint32_t am_util_stdio_vsprintf(char *pcBuf, const char *pcFmt, va_list pArgs); 156 157 //****************************************************************************** 158 // 159 //! @brief Format data into string. 160 //! 161 //! @param *pcBuf - Pointer to the buffer to store the string 162 //! @param *pcFmt - Pointer to formater string 163 //! 164 //! A lite version of vsprintf(). 165 //! Currently handles the following specifiers: 166 //! %c 167 //! %s 168 //! %[0][width]d (also %i) 169 //! %[0][width]u 170 //! %[0][width]x 171 //! 172 //! Note than any unrecognized or unhandled format specifier character is 173 //! simply printed. For example, "%%" will print a '%' character. 174 //! 175 //! @return uint32_t representing the number of characters printed. 176 // 177 //****************************************************************************** 178 extern uint32_t am_util_stdio_sprintf(char *pcBuf, const char *pcFmt, ...); 179 180 //***************************************************************************** 181 // 182 //! @brief A lite version of printf() 183 //! 184 //! @param *pcFmt - Pointer to formatter string 185 //! 186 //! See am_util_stdio_sprintf() for more details. 187 //! 188 //! @return uint32_t representing the number of characters printed. 189 // 190 // ***************************************************************************** 191 extern uint32_t am_util_stdio_printf(const char *pcFmt, ...); 192 193 //****************************************************************************** 194 // 195 //! @brief Format data into string. (va_list implementation) 196 //! 197 //! @param *pcBuf - Pointer to the buffer to store the string 198 //! @param n - number of arguments 199 //! @param *pcFmt - Pointer to formatter string 200 //! @param *pArgs - Pointer to extended arguments 201 //! 202 //! A lite version of vsprintf(). 203 //! Currently handles the following specifiers: 204 //! %c 205 //! %s 206 //! %[0][width]d (also %i) 207 //! %[0][width]u 208 //! %[0][width]x 209 //! %[.precision]f 210 //! 211 //! Note than any unrecognized or unhandled format specifier character is 212 //! simply printed. For example, "%%" will print a '%' character. 213 //! 214 //! @return uint32_t representing the number of characters printed. 215 // 216 //****************************************************************************** 217 extern uint32_t am_util_stdio_vsnprintf(char *pcBuf, uint32_t n, const char *pcFmt, 218 va_list pArgs); 219 220 //****************************************************************************** 221 // 222 //! @brief Format data into string. 223 //! 224 //! @param *pcBuf - Pointer to the buffer to store the string 225 //! @param n - number of arguments 226 //! @param *pcFmt - Pointer to formater string 227 //! 228 //! A lite version of vsprintf(). 229 //! Currently handles the following specifiers: 230 //! %c 231 //! %s 232 //! %[0][width]d (also %i) 233 //! %[0][width]u 234 //! %[0][width]x 235 //! 236 //! Note than any unrecognized or unhandled format specifier character is 237 //! simply printed. For example, "%%" will print a '%' character. 238 //! 239 //! @return uint32_t representing the number of characters printed. 240 // 241 //****************************************************************************** 242 extern uint32_t am_util_stdio_snprintf(char *pcBuf, uint32_t n, const char *pcFmt, ...); 243 244 //****************************************************************************** 245 // 246 //! @brief Format data into string. (va_list implementation) 247 //! 248 //! @param *pcFmt - Pointer to formatter string 249 //! @param *pArgs - Pointer to extended arguments 250 //! 251 //! A lite version of vsprintf(). 252 //! Currently handles the following specifiers: 253 //! %c 254 //! %s 255 //! %[0][width]d (also %i) 256 //! %[0][width]u 257 //! %[0][width]x 258 //! %[.precision]f 259 //! 260 //! Note than any unrecognized or unhandled format specifier character is 261 //! simply printed. For example, "%%" will print a '%' character. 262 //! 263 //! @return uint32_t representing the number of characters printed. 264 // 265 //****************************************************************************** 266 extern uint32_t am_util_stdio_vprintf(const char *pcFmt, va_list pArgs); 267 268 //***************************************************************************** 269 // 270 //! @brief Clear the terminal screen 271 //! 272 //! This function clears a standard terminal screen. 273 // 274 //***************************************************************************** 275 extern void am_util_stdio_terminal_clear(void); 276 277 #ifdef __cplusplus 278 } 279 #endif 280 281 #endif // AM_UTIL_STDIO_H 282 283 //***************************************************************************** 284 // 285 // End Doxygen group. 286 //! @} 287 // 288 //***************************************************************************** 289 290
