test/py/tests/test_dfu.py

   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
  10 import os
  11 import os.path
  12 import pytest
  13 import u_boot_utils
  14
  15 """
  16 Note: This test relies on:
  17
  18 a) boardenv_* to contain configuration values to define which USB ports are
  19 available for testing. Without this, this test will be automatically skipped.
  20 For example:
  21
  22 env__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).
  35 test_file_name = "/dfu_test.bin"
  36 dummy_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
  40 env__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
  75 b) udev rules to set permissions on devices nodes, so that sudo is not
  76 required. For example:
  77
  78 ACTION=="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
  81 open. All that matters is that the user ID running the test can access the
  82 device.)
  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.
  88 test_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
 106 first_usb_dev_port = None
 107
 108 @pytest.mark.buildconfigspec('cmd_dfu')
 109 def 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)