1 # Copyright (c) 2015 Stephen Warren
2 # Copyright (c) 2015-2016, NVIDIA CORPORATION. All rights reserved.
4 # SPDX-License-Identifier: GPL-2.0
6 # Common logic to interact with U-Boot via the console. This class provides
7 # the interface that tests use to execute U-Boot shell commands and wait for
8 # their results. Sub-classes exist to perform board-type-specific setup
9 # operations, such as spawning a sub-process for Sandbox, or attaching to the
10 # serial console of real hardware.
12 import multiplexed_log
19 # Regexes for text we expect U-Boot to send to the console.
20 pattern_u_boot_spl_signon = re.compile('(U-Boot SPL \\d{4}\\.\\d{2}-[^\r\n]*)')
21 pattern_u_boot_main_signon = re.compile('(U-Boot \\d{4}\\.\\d{2}-[^\r\n]*)')
22 pattern_stop_autoboot_prompt = re.compile('Hit any key to stop autoboot: ')
23 pattern_unknown_command = re.compile('Unknown command \'.*\' - try \'help\'')
24 pattern_error_notification = re.compile('## Error: ')
26 class ConsoleDisableCheck(object):
27 """Context manager (for Python's with statement) that temporarily disables
28 the specified console output error check. This is useful when deliberately
29 executing a command that is known to trigger one of the error checks, in
30 order to test that the error condition is actually raised. This class is
31 used internally by ConsoleBase::disable_check(); it is not intended for
34 def __init__(self, console, check_type):
35 self.console = console
36 self.check_type = check_type
39 self.console.disable_check_count[self.check_type] += 1
41 def __exit__(self, extype, value, traceback):
42 self.console.disable_check_count[self.check_type] -= 1
44 class ConsoleBase(object):
45 """The interface through which test functions interact with the U-Boot
46 console. This primarily involves executing shell commands, capturing their
47 results, and checking for common error conditions. Some common utilities
48 are also provided too."""
50 def __init__(self, log, config, max_fifo_fill):
51 """Initialize a U-Boot console connection.
53 Can only usefully be called by sub-classes.
56 log: A mulptiplex_log.Logfile object, to which the U-Boot output
58 config: A configuration data structure, as built by conftest.py.
59 max_fifo_fill: The maximum number of characters to send to U-Boot
60 command-line before waiting for U-Boot to echo the characters
61 back. For UART-based HW without HW flow control, this value
62 should be set less than the UART RX FIFO size to avoid
63 overflow, assuming that U-Boot can't keep up with full-rate
64 traffic at the baud rate.
72 self.max_fifo_fill = max_fifo_fill
74 self.logstream = self.log.get_stream('console', sys.stdout)
76 # Array slice removes leading/trailing quotes
77 self.prompt = self.config.buildconfig['config_sys_prompt'][1:-1]
78 self.prompt_escaped = re.escape(self.prompt)
80 self.disable_check_count = {
84 'error_notification': 0,
87 self.at_prompt = False
88 self.at_prompt_logevt = None
91 """Terminate the connection to the U-Boot console.
93 This function is only useful once all interaction with U-Boot is
94 complete. Once this function is called, data cannot be sent to or
106 self.logstream.close()
108 def run_command(self, cmd, wait_for_echo=True, send_nl=True,
109 wait_for_prompt=True):
110 """Execute a command via the U-Boot console.
112 The command is always sent to U-Boot.
114 U-Boot echoes any command back to its output, and this function
115 typically waits for that to occur. The wait can be disabled by setting
116 wait_for_echo=False, which is useful e.g. when sending CTRL-C to
117 interrupt a long-running command such as "ums".
119 Command execution is typically triggered by sending a newline
120 character. This can be disabled by setting send_nl=False, which is
121 also useful when sending CTRL-C.
123 This function typically waits for the command to finish executing, and
124 returns the console output that it generated. This can be disabled by
125 setting wait_for_prompt=False, which is useful when invoking a long-
126 running command such as "ums".
129 cmd: The command to send.
130 wait_for_each: Boolean indicating whether to wait for U-Boot to
131 echo the command text back to its output.
132 send_nl: Boolean indicating whether to send a newline character
133 after the command string.
134 wait_for_prompt: Boolean indicating whether to wait for the
135 command prompt to be sent by U-Boot. This typically occurs
136 immediately after the command has been executed.
139 If wait_for_prompt == False:
142 The output from U-Boot during command execution. In other
143 words, the text U-Boot emitted between the point it echod the
144 command string and emitted the subsequent command prompts.
147 if self.at_prompt and \
148 self.at_prompt_logevt != self.logstream.logfile.cur_evt:
149 self.logstream.write(self.prompt, implicit=True)
153 if (self.disable_check_count['spl_signon'] == 0):
154 bad_patterns.append(pattern_u_boot_spl_signon)
155 bad_pattern_ids.append('SPL signon')
156 if self.disable_check_count['main_signon'] == 0:
157 bad_patterns.append(pattern_u_boot_main_signon)
158 bad_pattern_ids.append('U-Boot main signon')
159 if self.disable_check_count['unknown_command'] == 0:
160 bad_patterns.append(pattern_unknown_command)
161 bad_pattern_ids.append('Unknown command')
162 if self.disable_check_count['error_notification'] == 0:
163 bad_patterns.append(pattern_error_notification)
164 bad_pattern_ids.append('Error notification')
166 self.at_prompt = False
170 # Limit max outstanding data, so UART FIFOs don't overflow
171 chunk = cmd[:self.max_fifo_fill]
172 cmd = cmd[self.max_fifo_fill:]
174 if not wait_for_echo:
176 chunk = re.escape(chunk)
177 chunk = chunk.replace('\\\n', '[\r\n]')
178 m = self.p.expect([chunk] + bad_patterns)
180 self.at_prompt = False
181 raise Exception('Bad pattern found on console: ' +
182 bad_pattern_ids[m - 1])
183 if not wait_for_prompt:
185 m = self.p.expect([self.prompt_escaped] + bad_patterns)
187 self.at_prompt = False
188 raise Exception('Bad pattern found on console: ' +
189 bad_pattern_ids[m - 1])
190 self.at_prompt = True
191 self.at_prompt_logevt = self.logstream.logfile.cur_evt
192 # Only strip \r\n; space/TAB might be significant if testing
194 return self.p.before.strip('\r\n')
195 except Exception as ex:
196 self.log.error(str(ex))
201 """Send a CTRL-C character to U-Boot.
203 This is useful in order to stop execution of long-running synchronous
204 commands such as "ums".
213 self.log.action('Sending Ctrl-C')
214 self.run_command(chr(3), wait_for_echo=False, send_nl=False)
216 def wait_for(self, text):
217 """Wait for a pattern to be emitted by U-Boot.
219 This is useful when a long-running command such as "dfu" is executing,
220 and it periodically emits some text that should show up at a specific
221 location in the log file.
224 text: The text to wait for; either a string (containing raw text,
225 not a regular expression) or an re object.
231 if type(text) == type(''):
232 text = re.escape(text)
233 self.p.expect([text])
235 def drain_console(self):
236 """Read from and log the U-Boot console for a short time.
238 U-Boot's console output is only logged when the test code actively
239 waits for U-Boot to emit specific data. There are cases where tests
240 can fail without doing this. For example, if a test asks U-Boot to
241 enable USB device mode, then polls until a host-side device node
242 exists. In such a case, it is useful to log U-Boot's console output
243 in case U-Boot printed clues as to why the host-side even did not
244 occur. This function will do that.
253 # If we are already not connected to U-Boot, there's nothing to drain.
254 # This should only happen when a previous call to run_command() or
255 # wait_for() failed (and hence the output has already been logged), or
256 # the system is shutting down.
260 orig_timeout = self.p.timeout
262 # Drain the log for a relatively short time.
263 self.p.timeout = 1000
264 # Wait for something U-Boot will likely never send. This will
265 # cause the console output to be read and logged.
266 self.p.expect(['This should never match U-Boot output'])
267 except u_boot_spawn.Timeout:
270 self.p.timeout = orig_timeout
272 def ensure_spawned(self):
273 """Ensure a connection to a correctly running U-Boot instance.
275 This may require spawning a new Sandbox process or resetting target
276 hardware, as defined by the implementation sub-class.
278 This is an internal function and should not be called directly.
290 self.at_prompt = False
291 self.log.action('Starting U-Boot')
292 self.p = self.get_spawn()
293 # Real targets can take a long time to scroll large amounts of
294 # text if LCD is enabled. This value may need tweaking in the
295 # future, possibly per-test to be optimal. This works for 'help'
296 # on board 'seaboard'.
297 self.p.timeout = 30000
298 self.p.logfile_read = self.logstream
299 if self.config.buildconfig.get('CONFIG_SPL', False) == 'y':
300 self.p.expect([pattern_u_boot_spl_signon])
301 self.p.expect([pattern_u_boot_main_signon])
302 signon = self.p.after
303 build_idx = signon.find(', Build:')
305 self.u_boot_version_string = signon
307 self.u_boot_version_string = signon[:build_idx]
309 match = self.p.expect([self.prompt_escaped,
310 pattern_stop_autoboot_prompt])
312 self.p.send(chr(3)) # CTRL-C
315 self.at_prompt = True
316 self.at_prompt_logevt = self.logstream.logfile.cur_evt
317 except Exception as ex:
318 self.log.error(str(ex))
322 def cleanup_spawn(self):
323 """Shut down all interaction with the U-Boot instance.
325 This is used when an error is detected prior to re-establishing a
326 connection with a fresh U-Boot instance.
328 This is an internal function and should not be called directly.
344 def validate_version_string_in_text(self, text):
345 """Assert that a command's output includes the U-Boot signon message.
347 This is primarily useful for validating the "version" command without
348 duplicating the signon text regex in a test function.
351 text: The command output text to check.
354 Nothing. An exception is raised if the validation fails.
357 assert(self.u_boot_version_string in text)
359 def disable_check(self, check_type):
360 """Temporarily disable an error check of U-Boot's output.
362 Create a new context manager (for use with the "with" statement) which
363 temporarily disables a particular console output error check.
366 check_type: The type of error-check to disable. Valid values may
367 be found in self.disable_check_count above.
370 A context manager object.
373 return ConsoleDisableCheck(self, check_type)