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