1/* 2 * Copyright (c) 2015-2017, ARM Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6#include <asm_macros.S> 7#define USE_FINISH_CONSOLE_REG_2 8#include <console_macros.S> 9 10 /* 11 * This file contains a skeleton console driver that can be used as 12 * basis for a real console driver. Console drivers in Trusted Firmware 13 * can be instantiated multiple times. Each instance is described by a 14 * separate console_t structure which must be registered with the common 15 * console framework via console_register(). Console drivers should 16 * define a console_xxx_register() function that initializes a new 17 * console_t structure passed in from the caller and registers it after 18 * initializing the console hardware. Drivers may define their own 19 * structures extending console_t to store private driver information. 20 * Console drivers *MUST* take care that the console callbacks they 21 * implement only change registers allowed in the clobber lists defined 22 * in this file. (Note that in addition to the explicit clobber lists, 23 * any function may always clobber the intra-procedure-call registers 24 * X16 and X17, but may never depend on them retaining their values 25 * across any function call.) 26 * Platforms using drivers based on this template need to enable 27 * MULTI_CONSOLE_API := 1 in their platform.mk. 28 */ 29 30 .globl console_xxx_register 31 .globl console_xxx_putc 32 .globl console_xxx_getc 33 .globl console_xxx_flush 34 35 /* ----------------------------------------------- 36 * int console_xxx_register(console_xxx_t *console, 37 * ...additional parameters as desired...) 38 * Function to initialize and register the console. 39 * The caller needs to pass an empty console_xxx_t 40 * structure in which *MUST* be allocated in 41 * persistent memory (e.g. a global or static local 42 * variable, *NOT* on the stack). 43 * In : x0 - pointer to empty console_t structure 44 * x1 through x7: additional parameters as desired 45 * Out: x0 - 1 on success, 0 on error 46 * Clobber list : x0 - x7 47 * ----------------------------------------------- 48 */ 49func console_xxx_register 50 /* 51 * Store parameters (e.g. hardware base address) in driver-specific 52 * console_xxx_t structure field if they will need to be retrieved 53 * by later console callback (e.g. putc). 54 * Example: 55 */ 56 str x1, [x0, #CONSOLE_T_XXX_BASE] 57 str x2, [x0, #CONSOLE_T_XXX_SOME_OTHER_VALUE] 58 59 /* 60 * Initialize console hardware, using x1 - x7 parameters as needed. 61 * Keep console_t pointer in x0 for later. 62 */ 63 64 /* 65 * Macro to finish up registration and return (needs valid x0 + x30). 66 * If any of the argument is unspecified, then the corresponding 67 * entry in console_t is set to 0. 68 */ 69 finish_console_register xxx putc=1, getc=1, flush=1 70 71 /* Jump here if hardware init fails or parameters are invalid. */ 72register_fail: 73 mov w0, #0 74 ret 75endfunc console_xxx_register 76 77 /* -------------------------------------------------------- 78 * int console_xxx_putc(int c, console_xxx_t *console) 79 * Function to output a character over the console. It 80 * returns the character printed on success or -1 on error. 81 * In : w0 - character to be printed 82 * x1 - pointer to console_t struct 83 * Out: w0 - printed character on success, < 0 on error. 84 * Clobber list : x0, x1, x2 85 * -------------------------------------------------------- 86 */ 87func console_xxx_putc 88 /* 89 * Retrieve values we need (e.g. hardware base address) from 90 * console_xxx_t structure pointed to by x1. 91 * Example: 92 */ 93 ldr x1, [x1, #CONSOLE_T_XXX_BASE] 94 95 /* 96 * Write w0 to hardware. 97 */ 98 99 ret 100 101 /* Jump here if output fails for any reason. */ 102putc_error: 103 mov w0, #-1 104 ret 105endfunc console_xxx_putc 106 107 /* --------------------------------------------- 108 * int console_xxx_getc(console_xxx_t *console) 109 * Function to get a character from the console. 110 * Even though console_getc() is blocking, this 111 * callback has to be non-blocking and always 112 * return immediately to allow polling multiple 113 * drivers concurrently. 114 * Returns the character grabbed on success, 115 * ERROR_NO_PENDING_CHAR if no character was 116 * available at this time, or any value 117 * between -2 and -127 if there was an error. 118 * In : x0 - pointer to console_t struct 119 * Out: w0 - character on success, 120 * ERROR_NO_PENDING_CHAR if no char, 121 * < -1 on error 122 * Clobber list : x0, x1 123 * --------------------------------------------- 124 */ 125func console_xxx_getc 126 /* 127 * Retrieve values we need (e.g. hardware base address) from 128 * console_xxx_t structure pointed to by x0. 129 * Example: 130 */ 131 ldr x1, [x0, #CONSOLE_T_XXX_BASE] 132 133 /* 134 * Try to read character into w0 from hardware. 135 */ 136 137 ret 138 139 /* Jump here if there is no character available at this time. */ 140getc_no_char: 141 mov w0, #ERROR_NO_PENDING_CHAR 142 ret 143 144 /* Jump here if there was any hardware error. */ 145getc_error: 146 mov w0, #-2 /* may pick error codes between -2 and -127 */ 147 ret 148endfunc console_xxx_getc 149 150 /* --------------------------------------------- 151 * int console_xxx_flush(console_xxx_t *console) 152 * Function to force a write of all buffered 153 * data that hasn't been output. 154 * In : x0 - pointer to console_xxx_t struct 155 * Out: w0 - 0 on success, < 0 on error 156 * Clobber list : x0, x1, x2, x3, x4, x5 157 * --------------------------------------------- 158 */ 159func console_xxx_flush 160 /* 161 * Retrieve values we need (e.g. hardware base address) from 162 * console_xxx_t structure pointed to by x0. 163 * Example: 164 */ 165 ldr x1, [x0, #CONSOLE_T_XXX_BASE] 166 167 /* 168 * Flush all remaining output from hardware FIFOs. Do not return until 169 * all data has been flushed or there was an unrecoverable error. 170 */ 171 172 mov w0, #0 173 ret 174 175 /* Jump here if an unrecoverable error has been encountered. */ 176flush_error: 177 mov w0, #-1 178 ret 179endfunc console_xxx_flush 180