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