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