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