1 /* 2 * Copyright (c) 2017, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 #ifndef OPENTHREAD_PLATFORM_DEBUG_UART_H_ 30 #define OPENTHREAD_PLATFORM_DEBUG_UART_H_ 31 32 #include <openthread/error.h> 33 #include <openthread/platform/logging.h> 34 35 /** 36 * @file 37 * 38 * Note: This is NOT a public thread API, and this header file is *NOT* 39 * installed as part of OpenThread, this is an pseudo-internal 40 * debug feature usable by developers during the course of development. 41 * 42 * This implements a very basic debug uart useful for logging 43 * messages when the primary uart is already engaged (example the NCP) 44 * and encapsulating logs is not practical. 45 * 46 * Implementation Notes: 47 * 48 * Only 3 functions are required to be implemented by the platform. 49 * see/search for the word MUST in the comments below. 50 * 51 * The other functions (without MUST in the comment) are WEAK symbols 52 * that can optionally be overridden by the platform or the application. 53 * 54 * Many of the other functions are simply convenience functions to 55 * aid a developer during their normal course of work and are not 56 * intended to be present, or used in production system. 57 */ 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 /** 64 * @addtogroup internal-debug-api 65 * 66 * @{ 67 */ 68 69 /** 70 * Standard printf() to the debug uart with no log decoration. 71 * 72 * @param[in] fmt printf formatter text 73 * 74 * This is a debug convenience function that is not intended to be 75 * used in anything other then "debug scenarios" by a developer. 76 * 77 * lf -> cr/lf mapping is automatically handled via otPlatDebugUart_putchar() 78 * 79 * @sa otPlatDebugUart_vprintf() for limitations 80 * 81 * This is a WEAK symbol that can easily be overridden as needed. 82 */ 83 void otPlatDebugUart_printf(const char *fmt, ...); 84 85 /** 86 * Standard vprintf() to the debug uart, with no log decoration. 87 * 88 * @param[in] fmt printf formatter text 89 * @param[in] ap va_list value for print parameters. 90 * 91 * Implementation limitation: this formats the text into 92 * a purposely small text buffer on the stack, thus long 93 * messages may be truncated. 94 * 95 * This is a WEAK symbol that can easily be overridden as needed. 96 * 97 * For example, some platforms might override this via a non-WEAK 98 * symbol because the platform provides a UART_vprintf() like 99 * function that can handle an arbitrary length output. 100 */ 101 void otPlatDebugUart_vprintf(const char *fmt, va_list ap); 102 103 /** 104 * Platform specific write single byte to Debug Uart 105 * This should not perform CR/LF mapping. 106 * 107 * MUST be implemented by the platform 108 * 109 * @param[in] c what to transmit 110 */ 111 void otPlatDebugUart_putchar_raw(int c); 112 113 /** 114 * Poll/test debug uart if a key has been pressed. 115 * It would be common to a stub function that returns 0. 116 * 117 * MUST be implemented by the platform 118 * 119 * @retval zero - nothing ready 120 * @retval nonzero - otPlatDebugUart_getc() will succeed. 121 */ 122 int otPlatDebugUart_kbhit(void); 123 124 /** 125 * Poll/Read a byte from the debug uart 126 * 127 * MUST be implemented by the platform 128 * 129 * @retval (negative) no data available, see otPlatDebugUart_kbhit() 130 * @retval (0x00..0x0ff) data byte value 131 * 132 */ 133 int otPlatDebugUart_getc(void); 134 135 /** 136 * Write byte to the uart, expand cr/lf as need. 137 * 138 * A WEAK default implementation is provided 139 * that can be overridden as needed. 140 * 141 * @param[in] c the byte to transmit 142 */ 143 void otPlatDebugUart_putchar(int c); 144 145 /** 146 * identical to "man 3 puts" - terminates with lf 147 * Which is then mapped to cr/lf as required 148 * 149 * A WEAK default implementation is provided 150 * that can be overridden as needed. 151 * 152 * @param[in] s the string to print with a lf at the end 153 */ 154 void otPlatDebugUart_puts(const char *s); 155 156 /** 157 * Write N bytes to the UART, mapping cr/lf 158 * 159 * @param[in] pBytes pointer to bytes to transmit. 160 * @param[in] nBytes how many bytes to transmit. 161 */ 162 void otPlatDebugUart_write_bytes(const uint8_t *pBytes, int nBytes); 163 164 /** 165 * puts() without a terminal newline. 166 * see: "man 3 puts", without a adding a terminal lf 167 * 168 * @param[in] s the string to print without a lf at the end 169 * 170 * Note, the terminal "lf" mapped to cr/lf via 171 * the function otPlatDebugUart_putchar() 172 */ 173 void otPlatDebugUart_puts_no_nl(const char *s); 174 175 /** 176 * Some platforms (simulation) can log to a file. 177 * 178 * @returns OT_ERROR_NONE 179 * @returns OT_ERROR_FAILED 180 * 181 * Platforms that desire this MUST provide an implementation. 182 * 183 */ 184 otError otPlatDebugUart_logfile(const char *filename); 185 186 /** 187 * @} 188 * 189 */ 190 191 #ifdef __cplusplus 192 } // extern "C" 193 #endif 194 195 #endif // OPENTHREAD_PLATFORM_DEBUG_UART_H_ 196
