include/debug_uart.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Early debug UART support
   4  *
   5  * (C) Copyright 2014 Google, Inc
   6  * Writte by Simon Glass <sjg@chromium.org>
   7  */
   8
   9 #ifndef _DEBUG_UART_H
  10 #define _DEBUG_UART_H
  11
  12 /*
  13  * The debug UART is intended for use very early in U-Boot to debug problems
  14  * when an ICE or other debug mechanism is not available.
  15  *
  16  * To use it you should:
  17  * - Make sure your UART supports this interface
  18  * - Enable CONFIG_DEBUG_UART
  19  * - Enable the CONFIG for your UART to tell it to provide this interface
  20  *       (e.g. CONFIG_DEBUG_UART_NS16550)
  21  * - Define the required settings as needed (see below)
  22  * - Call debug_uart_init() before use
  23  * - Call printch() to output a character
  24  *
  25  * Depending on your platform it may be possible to use this UART before a
  26  * stack is available.
  27  *
  28  * If your UART does not support this interface you can probably add support
  29  * quite easily. Remember that you cannot use driver model and it is preferred
  30  * to use no stack.
  31  *
  32  * You must not use this UART once driver model is working and the serial
  33  * drivers are up and running (done in serial_init()). Otherwise the drivers
  34  * may conflict and you will get strange output.
  35  *
  36  *
  37  * To enable the debug UART in your serial driver:
  38  *
  39  * - #include <debug_uart.h>
  40  * - Define _debug_uart_init(), trying to avoid using the stack
  41  * - Define _debug_uart_putc() as static inline (avoiding stack usage)
  42  * - Immediately afterwards, add DEBUG_UART_FUNCS to define the rest of the
  43  *     functionality (printch(), etc.)
  44  *
  45  * If your board needs additional init for the UART to work, enable
  46  * CONFIG_DEBUG_UART_BOARD_INIT and write a function called
  47  * board_debug_uart_init() to perform that init. When debug_uart_init() is
  48  * called, the init will happen automatically.
  49  */
  50
  51 /**
  52  * debug_uart_init() - Set up the debug UART ready for use
  53  *
  54  * This sets up the UART with the correct baud rate, etc.
  55  *
  56  * Available CONFIG is:
  57  *
  58  *    - CONFIG_DEBUG_UART_BASE: Base address of UART
  59  *    - CONFIG_BAUDRATE: Requested baud rate
  60  *    - CONFIG_DEBUG_UART_CLOCK: Input clock for UART
  61  */
  62 void debug_uart_init(void);
  63
  64 #ifdef CONFIG_DEBUG_UART_BOARD_INIT
  65 void board_debug_uart_init(void);
  66 #else
  67 static inline void board_debug_uart_init(void)
  68 {
  69 }
  70 #endif
  71
  72 /**
  73  * printch() - Output a character to the debug UART
  74  *
  75  * @ch:         Character to output
  76  */
  77 void printch(int ch);
  78
  79 /**
  80  * printascii() - Output an ASCII string to the debug UART
  81  *
  82  * @str:        String to output
  83  */
  84 void printascii(const char *str);
  85
  86 /**
  87  * printhex2() - Output a 2-digit hex value
  88  *
  89  * @value:      Value to output
  90  */
  91 void printhex2(uint value);
  92
  93 /**
  94  * printhex4() - Output a 4-digit hex value
  95  *
  96  * @value:      Value to output
  97  */
  98 void printhex4(uint value);
  99
 100 /**
 101  * printhex8() - Output a 8-digit hex value
 102  *
 103  * @value:      Value to output
 104  */
 105 void printhex8(uint value);
 106
 107 #ifdef CONFIG_DEBUG_UART_ANNOUNCE
 108 #define _DEBUG_UART_ANNOUNCE    printascii("<debug_uart> ");
 109 #else
 110 #define _DEBUG_UART_ANNOUNCE
 111 #endif
 112
 113 #define serial_dout(reg, value) \
 114         serial_out_shift((char *)com_port + \
 115                 ((char *)reg - (char *)com_port) * \
 116                         (1 << CONFIG_DEBUG_UART_SHIFT), \
 117                 CONFIG_DEBUG_UART_SHIFT, value)
 118 #define serial_din(reg) \
 119         serial_in_shift((char *)com_port + \
 120                 ((char *)reg - (char *)com_port) * \
 121                         (1 << CONFIG_DEBUG_UART_SHIFT), \
 122                 CONFIG_DEBUG_UART_SHIFT)
 123
 124 /*
 125  * Now define some functions - this should be inserted into the serial driver
 126  */
 127 #define DEBUG_UART_FUNCS \
 128 \
 129         static inline void _printch(int ch) \
 130         { \
 131                 if (ch == '\n') \
 132                         _debug_uart_putc('\r'); \
 133                 _debug_uart_putc(ch); \
 134         } \
 135 \
 136         void printch(int ch) \
 137         { \
 138                 _printch(ch); \
 139         } \
 140 \
 141         void printascii(const char *str) \
 142         { \
 143                 while (*str) \
 144                         _printch(*str++); \
 145         } \
 146 \
 147         static inline void printhex1(uint digit) \
 148         { \
 149                 digit &= 0xf; \
 150                 _debug_uart_putc(digit > 9 ? digit - 10 + 'a' : digit + '0'); \
 151         } \
 152 \
 153         static inline void printhex(uint value, int digits) \
 154         { \
 155                 while (digits-- > 0) \
 156                         printhex1(value >> (4 * digits)); \
 157         } \
 158 \
 159         void printhex2(uint value) \
 160         { \
 161                 printhex(value, 2); \
 162         } \
 163 \
 164         void printhex4(uint value) \
 165         { \
 166                 printhex(value, 4); \
 167         } \
 168 \
 169         void printhex8(uint value) \
 170         { \
 171                 printhex(value, 8); \
 172         } \
 173 \
 174         void debug_uart_init(void) \
 175         { \
 176                 board_debug_uart_init(); \
 177                 _debug_uart_init(); \
 178                 _DEBUG_UART_ANNOUNCE \
 179         } \
 180
 181 #endif