1# Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved. 2# 3# SPDX-License-Identifier: GPL-2.0 4 5# Test U-Boot's "dfu" command. The test starts DFU in U-Boot, waits for USB 6# device enumeration on the host, executes dfu-util multiple times to test 7# various transfer sizes, many of which trigger USB driver edge cases, and 8# finally aborts the "dfu" command in U-Boot. 9 10import os 11import os.path 12import pytest 13import u_boot_utils 14 15""" 16Note: This test relies on: 17 18a) boardenv_* to contain configuration values to define which USB ports are 19available for testing. Without this, this test will be automatically skipped. 20For example: 21 22env__usb_dev_ports = ( 23 { 24 "tgt_usb_ctlr": "0", 25 "host_usb_dev_node": "/dev/usbdev-p2371-2180", 26 # This parameter is optional /if/ you only have a single board 27 # attached to your host at a time. 28 "host_usb_port_path": "3-13", 29 }, 30) 31 32env__dfu_configs = ( 33 # eMMC, partition 1 34 { 35 "alt_info": "/dfu_test.bin ext4 0 1;/dfu_dummy.bin ext4 0 1", 36 "cmd_params": "mmc 0", 37 }, 38) 39b) udev rules to set permissions on devices nodes, so that sudo is not 40required. For example: 41 42ACTION=="add", SUBSYSTEM=="block", SUBSYSTEMS=="usb", KERNELS=="3-13", MODE:="666" 43 44(You may wish to change the group ID instead of setting the permissions wide 45open. All that matters is that the user ID running the test can access the 46device.) 47""" 48 49# The set of file sizes to test. These values trigger various edge-cases such 50# as one less than, equal to, and one greater than typical USB max packet 51# sizes, and similar boundary conditions. 52test_sizes = ( 53 64 - 1, 54 64, 55 64 + 1, 56 128 - 1, 57 128, 58 128 + 1, 59 960 - 1, 60 960, 61 960 + 1, 62 4096 - 1, 63 4096, 64 4096 + 1, 65 1024 * 1024 - 1, 66 1024 * 1024, 67 8 * 1024 * 1024, 68) 69 70first_usb_dev_port = None 71 72@pytest.mark.buildconfigspec('cmd_dfu') 73def test_dfu(u_boot_console, env__usb_dev_port, env__dfu_config): 74 """Test the "dfu" command; the host system must be able to enumerate a USB 75 device when "dfu" is running, various DFU transfers are tested, and the 76 USB device must disappear when "dfu" is aborted. 77 78 Args: 79 u_boot_console: A U-Boot console connection. 80 env__usb_dev_port: The single USB device-mode port specification on 81 which to run the test. See the file-level comment above for 82 details of the format. 83 env__dfu_config: The single DFU (memory region) configuration on which 84 to run the test. See the file-level comment above for details 85 of the format. 86 87 Returns: 88 Nothing. 89 """ 90 91 def start_dfu(): 92 """Start U-Boot's dfu shell command. 93 94 This also waits for the host-side USB enumeration process to complete. 95 96 Args: 97 None. 98 99 Returns: 100 Nothing. 101 """ 102 103 fh = u_boot_utils.attempt_to_open_file( 104 env__usb_dev_port['host_usb_dev_node']) 105 if fh: 106 fh.close() 107 raise Exception('USB device present before dfu command invoked') 108 109 u_boot_console.log.action( 110 'Starting long-running U-Boot dfu shell command') 111 112 cmd = 'setenv dfu_alt_info "%s"' % env__dfu_config['alt_info'] 113 u_boot_console.run_command(cmd) 114 115 cmd = 'dfu 0 ' + env__dfu_config['cmd_params'] 116 u_boot_console.run_command(cmd, wait_for_prompt=False) 117 u_boot_console.log.action('Waiting for DFU USB device to appear') 118 fh = u_boot_utils.wait_until_open_succeeds( 119 env__usb_dev_port['host_usb_dev_node']) 120 fh.close() 121 122 def stop_dfu(ignore_errors): 123 """Stop U-Boot's dfu shell command from executing. 124 125 This also waits for the host-side USB de-enumeration process to 126 complete. 127 128 Args: 129 ignore_errors: Ignore any errors. This is useful if an error has 130 already been detected, and the code is performing best-effort 131 cleanup. In this case, we do not want to mask the original 132 error by "honoring" any new errors. 133 134 Returns: 135 Nothing. 136 """ 137 138 try: 139 u_boot_console.log.action( 140 'Stopping long-running U-Boot dfu shell command') 141 u_boot_console.ctrlc() 142 u_boot_console.log.action( 143 'Waiting for DFU USB device to disappear') 144 u_boot_utils.wait_until_file_open_fails( 145 env__usb_dev_port['host_usb_dev_node'], ignore_errors) 146 except: 147 if not ignore_errors: 148 raise 149 150 def run_dfu_util(alt_setting, fn, up_dn_load_arg): 151 """Invoke dfu-util on the host. 152 153 Args: 154 alt_setting: The DFU "alternate setting" identifier to interact 155 with. 156 fn: The host-side file name to transfer. 157 up_dn_load_arg: '-U' or '-D' depending on whether a DFU upload or 158 download operation should be performed. 159 160 Returns: 161 Nothing. 162 """ 163 164 cmd = ['dfu-util', '-a', str(alt_setting), up_dn_load_arg, fn] 165 if 'host_usb_port_path' in env__usb_dev_port: 166 cmd += ['-p', env__usb_dev_port['host_usb_port_path']] 167 u_boot_utils.run_and_log(u_boot_console, cmd) 168 u_boot_console.wait_for('Ctrl+C to exit ...') 169 170 def dfu_write(alt_setting, fn): 171 """Write a file to the target board using DFU. 172 173 Args: 174 alt_setting: The DFU "alternate setting" identifier to interact 175 with. 176 fn: The host-side file name to transfer. 177 178 Returns: 179 Nothing. 180 """ 181 182 run_dfu_util(alt_setting, fn, '-D') 183 184 def dfu_read(alt_setting, fn): 185 """Read a file from the target board using DFU. 186 187 Args: 188 alt_setting: The DFU "alternate setting" identifier to interact 189 with. 190 fn: The host-side file name to transfer. 191 192 Returns: 193 Nothing. 194 """ 195 196 # dfu-util fails reads/uploads if the host file already exists 197 if os.path.exists(fn): 198 os.remove(fn) 199 run_dfu_util(alt_setting, fn, '-U') 200 201 def dfu_write_read_check(size): 202 """Test DFU transfers of a specific size of data 203 204 This function first writes data to the board then reads it back and 205 compares the written and read back data. Measures are taken to avoid 206 certain types of false positives. 207 208 Args: 209 size: The data size to test. 210 211 Returns: 212 Nothing. 213 """ 214 215 test_f = u_boot_utils.PersistentRandomFile(u_boot_console, 216 'dfu_%d.bin' % size, size) 217 readback_fn = u_boot_console.config.result_dir + '/dfu_readback.bin' 218 219 u_boot_console.log.action('Writing test data to DFU primary ' + 220 'altsetting') 221 dfu_write(0, test_f.abs_fn) 222 223 u_boot_console.log.action('Writing dummy data to DFU secondary ' + 224 'altsetting to clear DFU buffers') 225 dfu_write(1, dummy_f.abs_fn) 226 227 u_boot_console.log.action('Reading DFU primary altsetting for ' + 228 'comparison') 229 dfu_read(0, readback_fn) 230 231 u_boot_console.log.action('Comparing written and read data') 232 written_hash = test_f.content_hash 233 read_back_hash = u_boot_utils.md5sum_file(readback_fn, size) 234 assert(written_hash == read_back_hash) 235 236 # This test may be executed against multiple USB ports. The test takes a 237 # long time, so we don't want to do the whole thing each time. Instead, 238 # execute the full test on the first USB port, and perform a very limited 239 # test on other ports. In the limited case, we solely validate that the 240 # host PC can enumerate the U-Boot USB device. 241 global first_usb_dev_port 242 if not first_usb_dev_port: 243 first_usb_dev_port = env__usb_dev_port 244 if env__usb_dev_port == first_usb_dev_port: 245 sizes = test_sizes 246 else: 247 sizes = [] 248 249 dummy_f = u_boot_utils.PersistentRandomFile(u_boot_console, 250 'dfu_dummy.bin', 1024) 251 252 ignore_cleanup_errors = True 253 try: 254 start_dfu() 255 256 u_boot_console.log.action( 257 'Overwriting DFU primary altsetting with dummy data') 258 dfu_write(0, dummy_f.abs_fn) 259 260 for size in sizes: 261 with u_boot_console.log.section("Data size %d" % size): 262 dfu_write_read_check(size) 263 # Make the status of each sub-test obvious. If the test didn't 264 # pass, an exception was thrown so this code isn't executed. 265 u_boot_console.log.status_pass('OK') 266 ignore_cleanup_errors = False 267 finally: 268 stop_dfu(ignore_cleanup_errors) 269