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