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