Embed:
(wiki syntax)
Show/hide line numbers
fnet_serial.h
00001 /************************************************************************** 00002 * 00003 * Copyright (c) 2017, Arm Limited and affiliates. 00004 * Copyright 2011-2016 by Andrey Butok. FNET Community. 00005 * Copyright 2008-2010 by Andrey Butok. Freescale Semiconductor, Inc. 00006 * 00007 *************************************************************************** 00008 * 00009 * Licensed under the Apache License, Version 2.0 (the "License"); you may 00010 * not use this file except in compliance with the License. 00011 * You may obtain a copy of the License at 00012 * 00013 * http://www.apache.org/licenses/LICENSE-2.0 00014 * 00015 * Unless required by applicable law or agreed to in writing, software 00016 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 00017 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00018 * See the License for the specific language governing permissions and 00019 * limitations under the License. 00020 * 00021 **********************************************************************/ 00022 /*! 00023 * @brief FNET Serial Input and Output Library API. 00024 * 00025 ***************************************************************************/ 00026 #ifndef _FNET_SERIAL_H_ 00027 00028 #define _FNET_SERIAL_H_ 00029 00030 /*! @addtogroup fnet_serial 00031 * The Serial Input/Output (I/O) library provides commonly used I/O functions 00032 * like printf(), putchar() and getchar().@n 00033 * It uses stream abstraction to allow reading and writing data in an uniform way. 00034 * There are three standard streams allocated automatically that are 00035 * associated with physical serial ports (one per UART module). @n 00036 * For the serial library usage example, refer to FNET demo application source code. @n 00037 * @n 00038 * NOTE: The HW serial ports associated with I/O streams are not initialized by the serial 00039 * library and should be initialized by the application. It can be inialized by 00040 * the @ref fnet_cpu_serial_init() function. @n 00041 * @n 00042 * Configuration parameters: 00043 * - @ref FNET_CFG_SERIAL_PRINTF_N_TO_RN 00044 * 00045 */ 00046 /*! @{ */ 00047 00048 /****************************************************************************** 00049 * Escape sequences for termianl that suports vt100. 00050 *******************************************************************************/ 00051 #define FNET_ATTR_RESET 0 00052 #define FNET_ATTR_BOLD 1 00053 #define FNET_ATTR_BLINK 5 00054 #define FNET_ATTR_UNDERLINE 4 00055 #define FNET_ATTR_REVERSE 7 00056 00057 #define FNET_COLOR_BLACK 0 00058 #define FNET_COLOR_RED 1 00059 #define FNET_COLOR_GREEN 2 00060 #define FNET_COLOR_YELLOW 3 00061 #define FNET_COLOR_BLUE 4 00062 #define FNET_COLOR_MAGENTA 5 00063 #define FNET_COLOR_CYAN 6 00064 #define FNET_COLOR_WHITE 7 00065 00066 /* Foreground color.*/ 00067 #define FNET_SERIAL_ESC_FG_BLACK "\33[30m" 00068 #define FNET_SERIAL_ESC_FG_RED "\33[31m" 00069 #define FNET_SERIAL_ESC_FG_GREEN "\33[32m" 00070 #define FNET_SERIAL_ESC_FG_YELLOW "\33[33m" 00071 #define FNET_SERIAL_ESC_FG_BLUE "\33[34m" 00072 #define FNET_SERIAL_ESC_FG_MAGENTA "\33[35m" 00073 #define FNET_SERIAL_ESC_FG_CYAN "\33[36m" 00074 #define FNET_SERIAL_ESC_FG_WHITE "\33[37m" 00075 00076 /* Background color.*/ 00077 #define FNET_SERIAL_ESC_BG_BLACK "\33[40m" 00078 #define FNET_SERIAL_ESC_BG_RED "\33[41m" 00079 #define FNET_SERIAL_ESC_BG_GREEN "\33[42m" 00080 #define FNET_SERIAL_ESC_BG_YELLOW "\33[43m" 00081 #define FNET_SERIAL_ESC_BG_BLUE "\33[44m" 00082 #define FNET_SERIAL_ESC_BG_MAGENTA "\33[45m" 00083 #define FNET_SERIAL_ESC_BG_CYAN "\33[46m" 00084 #define FNET_SERIAL_ESC_BG_WHITE "\33[47m" 00085 00086 /* SGR -- Select Graphic Rendition.*/ 00087 #define FNET_SERIAL_ESC_ATTR_RESET "\33[0m" 00088 #define FNET_SERIAL_ESC_ATTR_BOLD "\33[1m" 00089 #define FNET_SERIAL_ESC_ATTR_UNDERLINE "\33[4m" 00090 #define FNET_SERIAL_ESC_ATTR_BLINK "\33[5m" 00091 #define FNET_SERIAL_ESC_ATTR_REVERSE "\33[7m" 00092 00093 /**************************************************************************/ /*! 00094 * @brief Stream control structure. 00095 * 00096 * This structure defines stream-specific parameters. All streams have similar 00097 * properties independently of the individual characteristics of 00098 * the media they are associated with. 00099 * 00100 * @see fnet_serial_stream_t 00101 ******************************************************************************/ 00102 struct fnet_serial_stream 00103 { 00104 fnet_index_t id; /**< @brief The @c id parameter provides a way for a stream 00105 * driver to identify a particular device. @n 00106 * For example it can be used as serial port number 00107 * or pointer to a stream private structure.@n 00108 * This parameter is passed to 00109 * @c fnet_serial_stream.putchar() and to 00110 * @c fnet_serial_stream.getchar() as the first parameter. 00111 */ 00112 void (*putchar)(fnet_index_t stream_id, fnet_char_t character);/**< @brief Callback function used 00113 * for writing the @c character to the stream. 00114 */ 00115 fnet_int32_t (*getchar)(fnet_index_t stream_id); /**< @brief Callback function used for reading 00116 * a character from the stream. 00117 */ 00118 void (*flush)(fnet_index_t stream_id); /**< @brief Callback function used for 00119 * immediate data sending from internal stream buffer 00120 * to the steam client.@n 00121 * This function is optional and can be set to zero.@n 00122 * The function only has meaning for buffered streams. 00123 * UART stream does not have internal buffer and does 00124 * not use this flush function. 00125 */ 00126 }; 00127 00128 /**************************************************************************/ /*! 00129 * @brief Serial stream descriptor. 00130 ******************************************************************************/ 00131 typedef const struct fnet_serial_stream *fnet_serial_stream_t; 00132 00133 00134 extern const struct fnet_serial_stream fnet_serial_stream_port0; 00135 extern const struct fnet_serial_stream fnet_serial_stream_port1; 00136 extern const struct fnet_serial_stream fnet_serial_stream_port2; 00137 extern const struct fnet_serial_stream fnet_serial_stream_port3; 00138 extern const struct fnet_serial_stream fnet_serial_stream_port4; 00139 extern const struct fnet_serial_stream fnet_serial_stream_port5; 00140 00141 /**************************************************************************/ /*! 00142 * @brief Stream descriptor associated with the serial port 0. 00143 * @see FNET_SERIAL_STREAM_DEFAULT 00144 ******************************************************************************/ 00145 #define FNET_SERIAL_STREAM_PORT0 ((fnet_serial_stream_t)(&fnet_serial_stream_port0)) 00146 00147 /**************************************************************************/ /*! 00148 * @brief Stream descriptor associated with the serial port 1. 00149 * @see FNET_SERIAL_STREAM_DEFAULT 00150 ******************************************************************************/ 00151 #define FNET_SERIAL_STREAM_PORT1 ((fnet_serial_stream_t)(&fnet_serial_stream_port1)) 00152 00153 /**************************************************************************/ /*! 00154 * @brief Stream descriptor associated with the serial port 2. 00155 * @see FNET_SERIAL_STREAM_DEFAULT 00156 ******************************************************************************/ 00157 #define FNET_SERIAL_STREAM_PORT2 ((fnet_serial_stream_t)(&fnet_serial_stream_port2)) 00158 00159 /**************************************************************************/ /*! 00160 * @brief Stream descriptor associated with the serial port 3. 00161 * @see FNET_SERIAL_STREAM_DEFAULT 00162 ******************************************************************************/ 00163 #define FNET_SERIAL_STREAM_PORT3 ((fnet_serial_stream_t)(&fnet_serial_stream_port3)) 00164 00165 /**************************************************************************/ /*! 00166 * @brief Stream descriptor associated with the serial port 4. 00167 * @see FNET_SERIAL_STREAM_DEFAULT 00168 ******************************************************************************/ 00169 #define FNET_SERIAL_STREAM_PORT4 ((fnet_serial_stream_t)(&fnet_serial_stream_port4)) 00170 00171 /**************************************************************************/ /*! 00172 * @brief Stream descriptor associated with the serial port 5. 00173 * @see FNET_SERIAL_STREAM_DEFAULT 00174 ******************************************************************************/ 00175 #define FNET_SERIAL_STREAM_PORT5 ((fnet_serial_stream_t)(&fnet_serial_stream_port5)) 00176 00177 00178 /**************************************************************************/ /*! 00179 * @def FNET_SERIAL_STREAM_DEFAULT 00180 * @brief Descriptor of the default stream. It's assigned to the default 00181 * serial port defined by @ref FNET_CFG_CPU_SERIAL_PORT_DEFAULT 00182 * (usually the serial port 0). 00183 ******************************************************************************/ 00184 #if (FNET_CFG_CPU_SERIAL_PORT_DEFAULT == 0u) 00185 #define FNET_SERIAL_STREAM_DEFAULT FNET_SERIAL_STREAM_PORT0 00186 #elif (FNET_CFG_CPU_SERIAL_PORT_DEFAULT == 1u) 00187 #define FNET_SERIAL_STREAM_DEFAULT FNET_SERIAL_STREAM_PORT1 00188 #elif (FNET_CFG_CPU_SERIAL_PORT_DEFAULT == 2u) 00189 #define FNET_SERIAL_STREAM_DEFAULT FNET_SERIAL_STREAM_PORT2 00190 #elif (FNET_CFG_CPU_SERIAL_PORT_DEFAULT == 3u) 00191 #define FNET_SERIAL_STREAM_DEFAULT FNET_SERIAL_STREAM_PORT3 00192 #elif (FNET_CFG_CPU_SERIAL_PORT_DEFAULT == 4u) 00193 #define FNET_SERIAL_STREAM_DEFAULT FNET_SERIAL_STREAM_PORT4 00194 #elif (FNET_CFG_CPU_SERIAL_PORT_DEFAULT == 5u) 00195 #define FNET_SERIAL_STREAM_DEFAULT FNET_SERIAL_STREAM_PORT5 00196 #else 00197 /* Serial port is not used, skip error message to keep cppcheck happy 00198 * #error "The serial library defines only 6 ports." 00199 */ 00200 #endif 00201 00202 #if defined(__cplusplus) 00203 extern "C" { 00204 #endif 00205 00206 00207 /***************************************************************************/ /*! 00208 * 00209 * @brief Writes character to the stream. 00210 * 00211 * @param stream Stream descriptor. 00212 * 00213 * @param character Character to be written. 00214 * 00215 * @see fnet_serial_getchar() 00216 * 00217 ****************************************************************************** 00218 * 00219 * This function writes a single @c character to the stream. 00220 * 00221 ******************************************************************************/ 00222 void fnet_serial_putchar(fnet_serial_stream_t stream, fnet_char_t character); 00223 00224 /***************************************************************************/ /*! 00225 * 00226 * @brief Reads character from the stream. 00227 * 00228 * @param stream Stream descriptor. 00229 * 00230 * @return This function returns: 00231 * - character from the stream. 00232 * - FNET_ERR if no character is available in the stream. 00233 * 00234 * @see fnet_serial_putchar() 00235 * 00236 ****************************************************************************** 00237 * 00238 * This function reads a single character from the stream. @n 00239 * If no character is available in the stream the FNET_ERR is returned. 00240 * 00241 ******************************************************************************/ 00242 fnet_int32_t fnet_serial_getchar(fnet_serial_stream_t stream); 00243 00244 /***************************************************************************/ /*! 00245 * 00246 * @brief Sends data from the internal stream buffer to the stream client. 00247 * 00248 * @param stream Stream descriptor. 00249 * 00250 ****************************************************************************** 00251 * 00252 * This function immediately sends data from the internal stream 00253 * buffer to the stream client. @n 00254 * If you do not explicitly call the flush function, stream sends data to 00255 * the client after the internal buffer is full.@n 00256 * The function only has meaning for buffered streams.@n 00257 * UART stream does not have internal buffer and does not use 00258 * this flush function. 00259 * 00260 ******************************************************************************/ 00261 void fnet_serial_flush(fnet_serial_stream_t stream); 00262 00263 /***************************************************************************/ /*! 00264 * 00265 * @brief Writes character to the default stream. 00266 * 00267 * @param character Character to be written. 00268 * 00269 * @see fnet_getchar() 00270 * 00271 ****************************************************************************** 00272 * 00273 * This function writes a single @c character to the default stream. 00274 * 00275 ******************************************************************************/ 00276 void fnet_putchar(fnet_char_t character); 00277 00278 /***************************************************************************/ /*! 00279 * 00280 * @brief Reads character from the default stream. 00281 * 00282 * @return This function returns: 00283 * - character from the default stream. 00284 * - FNET_ERR if no character is available in the default stream. 00285 * 00286 * @see fnet_putchar() 00287 * 00288 ****************************************************************************** 00289 * 00290 * This function reads a single character from the default stream. @n 00291 * If no character is available in the stream the FNET_ERR is returned. 00292 * 00293 ******************************************************************************/ 00294 fnet_int32_t fnet_getchar(void); 00295 00296 /***************************************************************************/ /*! 00297 * 00298 * @brief Prints formatted text to the stream. 00299 * 00300 * @param stream Stream descriptor. 00301 * 00302 * @param format Format string. 00303 * 00304 * @return This function returns the number of characters that were 00305 * successfully written, excluding the trailing null. 00306 * 00307 * @see fnet_serial_putchar(), fnet_serial_vprintf() 00308 * 00309 ****************************************************************************** 00310 * 00311 * This function outputs formatted text to the @c stream. @n 00312 * The function takes one or more arguments. The first argument is a string parameter 00313 * called the "format string". 00314 * The optional arguments following @c format are items 00315 * (integers, characters or strings) that are to be converted to character strings 00316 * and inserted into the output of @c format at specified placeholders. 00317 * The number of arguments following the @c format parameters should at 00318 * least be as much as the number of format placeholders. @n 00319 * The syntax for a format placeholder is @a "%[Flags][Width][Length]Type". 00320 * - @a Flags can be omitted or be any of: 00321 * - @c - : Left justify. 00322 * - @c + : Right justify. 00323 * - @c 0 : Pad with leading zeros. 00324 * - @a space : Print space if no sign. 00325 * - @a Width is minimum field width. It can be omitted. 00326 * - @a Length is conversion character. It can be omitted or by any of: 00327 * - @c h : Short integer. 00328 * - @c l : Long integer. 00329 * - @a Type can by any of: 00330 * - @c d, @c i : Integer. 00331 * - @c u : Unsigned. 00332 * - @c x, @c X : Hexadecimal. 00333 * - @c o : Octal. 00334 * - @c b : Binary. 00335 * - @c p : Pointer. 00336 * - @c c : Single char. 00337 * - @c s : Char string. 00338 * - @c n : Nothing. 00339 * 00340 * @note 00341 * To save some bytes from all the hard coded strings the fnet_(s)printf() functions will 00342 * expand all line feeds ("\n") inside the format string to CR LF ("\r\n"). 00343 * So do not use "\r\n" in the format string - it will be expanded to 00344 * "\r\r\n". It is save to add it via a parameter though, e.g. 00345 * fnet_printf("%s", "\r\n");@n 00346 * This feature can be disable/enabled by the @ref FNET_CFG_SERIAL_PRINTF_N_TO_RN 00347 * configuration parameter. 00348 ******************************************************************************/ 00349 fnet_size_t fnet_serial_printf(fnet_serial_stream_t stream, const fnet_char_t *format, ... ); 00350 00351 /***************************************************************************/ /*! 00352 * 00353 * @brief Prints formatted variable argument list to the stream. 00354 * 00355 * @param stream Stream descriptor. 00356 * 00357 * @param format Format string. 00358 * 00359 * @param arg Variable arguments list. It shall have been initialized by @c va_start() macro 00360 * 00361 * @return This function returns the number of characters that were 00362 * successfully written, excluding the trailing null. 00363 * 00364 * @see fnet_serial_printf() 00365 * 00366 ****************************************************************************** 00367 * 00368 * This function outputs formatted text to the @c stream, expanding the format 00369 * placeholders with the value of the argument list @c arg. @n 00370 * This function behaves exactly as @c printf except that the variable argument 00371 * list is passed as a @c va_list instead of a succession of arguments, 00372 * which becomes specially useful when the argument list to be passed comes 00373 * itself from a variable argument list in the calling function. @n 00374 * @n 00375 * The syntax for a format placeholder is @a "%[Flags][Width][Length]Type". 00376 * - @a Flags can be omitted or be any of: 00377 * - @c - : Left justify. 00378 * - @c + : Right justify. 00379 * - @c 0 : Pad with leading zeros. 00380 * - @a space : Print space if no sign. 00381 * - @a Width is minimum field width. It can be omitted. 00382 * - @a Length is conversion character. It can be omitted or by any of: 00383 * - @c h : Short integer. 00384 * - @c l : Long integer. 00385 * - @a Type can by any of: 00386 * - @c d, @c i : Integer. 00387 * - @c u : Unsigned. 00388 * - @c x, @c X : Hexadecimal. 00389 * - @c o : Octal. 00390 * - @c b : Binary. 00391 * - @c p : Pointer. 00392 * - @c c : Single char. 00393 * - @c s : Char string. 00394 * - @c n : Nothing. 00395 * 00396 * @note 00397 * To save some bytes from all the hard coded strings the fnet_(s)printf() functions will 00398 * expand all line feeds ("\n") inside the format string to CR LF ("\r\n"). 00399 * So do not use "\r\n" in the format string - it will be expanded to 00400 * "\r\r\n". It is save to add it via a parameter though, e.g. 00401 * fnet_printf("%s", "\r\n");@n 00402 * This feature can be disable/enabled by the @ref FNET_CFG_SERIAL_PRINTF_N_TO_RN 00403 * configuration parameter. 00404 ******************************************************************************/ 00405 fnet_size_t fnet_serial_vprintf(fnet_serial_stream_t stream, const fnet_char_t *format, va_list arg ); 00406 00407 /***************************************************************************/ /*! 00408 * 00409 * @brief Prints formatted text to the default stream. 00410 * 00411 * @param format Format string. 00412 * 00413 * @return This function returns the number of characters that were 00414 * successfully written, excluding the trailing null. 00415 * 00416 * @see fnet_sprintf() 00417 * 00418 ****************************************************************************** 00419 * 00420 * This function outputs formatted text to the default stream, its descriptor is 00421 * defined by @ref FNET_SERIAL_STREAM_DEFAULT. @n 00422 * The function takes one or more arguments. The first argument is a string parameter 00423 * called the "format string". 00424 * The optional arguments following @c format are items 00425 * (integers, characters or strings) that are to be converted to character strings 00426 * and inserted into the output of @c format at specified placeholders. 00427 * The number of arguments following the @c format parameters should at 00428 * least be as much as the number of format placeholders. @n 00429 * The syntax for a format placeholder is @a "%[Flags][Width][Length]Type". 00430 * - @a Flags can be omitted or be any of: 00431 * - @c - : Left justify. 00432 * - @c + : Right justify. 00433 * - @c 0 : Pad with leading zeros. 00434 * - @a space : Print space if no sign. 00435 * - @a Width is minimum field width. It can be omitted. 00436 * - @a Length is conversion character. It can be omitted or by any of: 00437 * - @c h : Short integer. 00438 * - @c l : Long integer. 00439 * - @a Type can by any of: 00440 * - @c d, @c i : Integer. 00441 * - @c u : Unsigned. 00442 * - @c x, @c X : Hexadecimal. 00443 * - @c o : Octal. 00444 * - @c b : Binary. 00445 * - @c p : Pointer. 00446 * - @c c : Single char. 00447 * - @c s : Char string. 00448 * - @c n : Nothing. 00449 * 00450 * @note 00451 * To save some bytes from all the hard coded strings the fnet_(s)printf() functions will 00452 * expand all line feeds ("\n") inside the format string to CR LF ("\r\n"). 00453 * So do not use "\r\n" in the format string - it will be expanded to 00454 * "\r\r\n". It is save to add it via a parameter though, e.g. 00455 * fnet_printf("%s", "\r\n"); @n 00456 * This feature can be disable/enabled by the @ref FNET_CFG_SERIAL_PRINTF_N_TO_RN 00457 * configuration parameter. 00458 ******************************************************************************/ 00459 fnet_size_t fnet_printf( const fnet_char_t *format, ... ); 00460 00461 00462 /***************************************************************************/ /*! 00463 * @brief Prints formatted text to the default stream and terminates the 00464 * printed text by the line separator string. 00465 00466 * @param format Format string. 00467 * 00468 * @return This function returns the number of characters that were 00469 * successfully written, excluding the trailing null. 00470 * 00471 * @see fnet_sprintf() 00472 * 00473 ****************************************************************************** 00474 * 00475 * This function outputs formatted text to the default stream and terminates the 00476 * printed text by the line separator string. Its descriptor is 00477 * defined by @ref FNET_SERIAL_STREAM_DEFAULT. @n 00478 * The function takes one or more arguments. The first argument is a string parameter 00479 * called the "format string". 00480 * The optional arguments following @c format are items 00481 * (integers, characters or strings) that are to be converted to character strings 00482 * and inserted into the output of @c format at specified placeholders. 00483 * The number of arguments following the @c format parameters should at 00484 * least be as much as the number of format placeholders. @n 00485 * The syntax for a format placeholder is @a "%[Flags][Width][Length]Type". 00486 * - @a Flags can be omitted or be any of: 00487 * - @c - : Left justify. 00488 * - @c + : Right justify. 00489 * - @c 0 : Pad with leading zeros. 00490 * - @a space : Print space if no sign. 00491 * - @a Width is minimum field width. It can be omitted. 00492 * - @a Length is conversion character. It can be omitted or by any of: 00493 * - @c h : Short integer. 00494 * - @c l : Long integer. 00495 * - @a Type can by any of: 00496 * - @c d, @c i : Integer. 00497 * - @c u : Unsigned. 00498 * - @c x, @c X : Hexadecimal. 00499 * - @c o : Octal. 00500 * - @c b : Binary. 00501 * - @c p : Pointer. 00502 * - @c c : Single char. 00503 * - @c s : Char string. 00504 * - @c n : Nothing. 00505 * 00506 * @note 00507 * To save some bytes from all the hard coded strings the fnet_(s)printf() functions will 00508 * expand all line feeds ("\n") inside the format string to CR LF ("\r\n"). 00509 * So do not use "\r\n" in the format string - it will be expanded to 00510 * "\r\r\n". It is save to add it via a parameter though, e.g. 00511 * fnet_printf("%s", "\r\n"); @n 00512 * This feature can be disable/enabled by the @ref FNET_CFG_SERIAL_PRINTF_N_TO_RN 00513 * configuration parameter. 00514 ******************************************************************************/ 00515 fnet_size_t fnet_println(const fnet_char_t *format, ... ); 00516 00517 /***************************************************************************/ /*! 00518 * @brief Prints formatted text to the buffer. 00519 * 00520 * @param str Pointer to buffer where the resulting string is stored. 00521 * 00522 * @param format Format string. 00523 * 00524 * @return This function returns the number of characters that were 00525 * successfully written, excluding the trailing null. 00526 * 00527 * @see fnet_snprintf() 00528 * 00529 ****************************************************************************** 00530 * 00531 * The @c format string contains the text to be written to the @c str buffer. 00532 * The optional arguments following @c format are items 00533 * (integers, characters or strings) that are to be converted to character strings 00534 * and inserted into the output of @c format at specified placeholders. 00535 * The number of arguments following the @c format parameters should at 00536 * least be as much as the number of format placeholders. @n 00537 * The syntax for a format placeholder is @a "%[Flags][Width][Length]Type". 00538 * - @a Flags can be omitted or be any of: 00539 * - @c - : Left justify. 00540 * - @c + : Right justify. 00541 * - @c 0 : Pad with leading zeros. 00542 * - @a space : Print space if no sign. 00543 * - @a Width is minimum field width. It can be omitted. 00544 * - @a Length is conversion character. It can be omitted or by any of: 00545 * - @c h : Short integer. 00546 * - @c l : Long integer. 00547 * - @a Type can by any of: 00548 * - @c d, @c i : Integer. 00549 * - @c u : Unsigned. 00550 * - @c x, @c X : Hexadecimal. 00551 * - @c o : Octal. 00552 * - @c b : Binary. 00553 * - @c p : Pointer. 00554 * - @c c : Single char. 00555 * - @c s : Char string. 00556 * - @c n : Nothing. 00557 * 00558 * The @ref fnet_sprintf() function is just like @ref fnet_printf(), except 00559 * that the output is sent to buffer.@n 00560 * @n 00561 * This function does not check the bounds of the buffer and therefore 00562 * creates the risk of a buffer overflow. It is recommended to use @ref fnet_snprintf() 00563 * that doesn't suffer from buffer overruns. 00564 * @note 00565 * To save some bytes from all the hard coded strings the fnet_(s)printf() functions will 00566 * expand all line feeds ("\n") inside the format string to CR LF ("\r\n"). 00567 * So do not use "\r\n" in the format string - it will be expanded to 00568 * "\r\r\n". It is save to add it via a parameter though, e.g. 00569 * fnet_printf("%s", "\r\n");@n 00570 * This feature can be disable/enabled by the @ref FNET_CFG_SERIAL_PRINTF_N_TO_RN 00571 * configuration parameter. 00572 ******************************************************************************/ 00573 fnet_size_t fnet_sprintf( fnet_char_t *str, const fnet_char_t *format, ... ); 00574 00575 /***************************************************************************/ /*! 00576 * 00577 * @brief Prints formatted text to the buffer. 00578 * The length of the buffer is given, that prevents the buffer overflows. 00579 * 00580 * @param str Pointer to buffer where the resulting string is stored. 00581 * 00582 * @param size Maximum number of characters to produce. 00583 * The trailing null character is counted towards this limit 00584 * 00585 * @param format Format string. 00586 * 00587 * @return This function returns the number of characters that were 00588 * successfully written, excluding the trailing null. 00589 * 00590 * @see fnet_sprintf() 00591 * 00592 ****************************************************************************** 00593 * 00594 * This function is just like fnet_sprintf(), except that 00595 * the length of the buffer is given. This prevents buffer overflows.@n 00596 * @n 00597 * The @c format string contains the text to be written to the @c str buffer. 00598 * The optional arguments following @c format are items 00599 * (integers, characters or strings) that are to be converted to character strings 00600 * and inserted into the output of @c format at specified placeholders. 00601 * The number of arguments following the @c format parameters should at 00602 * least be as much as the number of format placeholders. @n 00603 * The syntax for a format placeholder is @a "%[Flags][Width][Length]Type". 00604 * - @a Flags can be omitted or be any of: 00605 * - @c - : Left justify. 00606 * - @c + : Right justify. 00607 * - @c 0 : Pad with leading zeros. 00608 * - @a space : Print space if no sign. 00609 * - @a Width is minimum field width. It can be omitted. 00610 * - @a Length is conversion character. It can be omitted or by any of: 00611 * - @c h : Short integer. 00612 * - @c l : Long integer. 00613 * - @a Type can by any of: 00614 * - @c d, @c i : Integer. 00615 * - @c u : Unsigned. 00616 * - @c x, @c X : Hexadecimal. 00617 * - @c o : Octal. 00618 * - @c b : Binary. 00619 * - @c p : Pointer. 00620 * - @c c : Single char. 00621 * - @c s : Char string. 00622 * - @c n : Nothing. 00623 * 00624 * @note 00625 * To save some bytes from all the hard coded strings the fnet_(s)printf() functions will 00626 * expand all line feeds ("\n") inside the format string to CR LF ("\r\n"). 00627 * So do not use "\r\n" in the format string - it will be expanded to 00628 * "\r\r\n". It is save to add it via a parameter though, e.g. 00629 * fnet_printf("%s", "\r\n");@n 00630 * This feature can be disable/enabled by the @ref FNET_CFG_SERIAL_PRINTF_N_TO_RN 00631 * configuration parameter. 00632 ******************************************************************************/ 00633 fnet_size_t fnet_snprintf( fnet_char_t *str, fnet_size_t size, const fnet_char_t *format, ... ); 00634 00635 #if defined(__cplusplus) 00636 } 00637 #endif 00638 00639 00640 /*! @} */ 00641 00642 #endif
Generated on Tue Jul 12 2022 12:21:53 by
1.7.2