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         fh = u_boot_utils.attempt_to_open_file(
 140             env__usb_dev_port['host_usb_dev_node'])
 141         if fh:
 142             fh.close()
 143             raise Exception('USB device present before dfu command invoked')
 144
 145         u_boot_console.log.action(
 146             'Starting long-running U-Boot dfu shell command')
 147
 148         dfu_alt_info_env = env__dfu_config.get('alt_info_env_name', \
 149                                                        'dfu_alt_info')
 150
 151         cmd = 'setenv "%s" "%s"' % (dfu_alt_info_env,
 152                                     env__dfu_config['alt_info'])
 153         u_boot_console.run_command(cmd)
 154
 155         cmd = 'dfu 0 ' + env__dfu_config['cmd_params']
 156         u_boot_console.run_command(cmd, wait_for_prompt=False)
 157         u_boot_console.log.action('Waiting for DFU USB device to appear')
 158         fh = u_boot_utils.wait_until_open_succeeds(
 159             env__usb_dev_port['host_usb_dev_node'])
 160         fh.close()
 161
 162     def stop_dfu(ignore_errors):
 163         """Stop U-Boot's dfu shell command from executing.
 164
 165         This also waits for the host-side USB de-enumeration process to
 166         complete.
 167
 168         Args:
 169             ignore_errors: Ignore any errors. This is useful if an error has
 170                 already been detected, and the code is performing best-effort
 171                 cleanup. In this case, we do not want to mask the original
 172                 error by "honoring" any new errors.
 173
 174         Returns:
 175             Nothing.
 176         """
 177
 178         try:
 179             u_boot_console.log.action(
 180                 'Stopping long-running U-Boot dfu shell command')
 181             u_boot_console.ctrlc()
 182             u_boot_console.log.action(
 183                 'Waiting for DFU USB device to disappear')
 184             u_boot_utils.wait_until_file_open_fails(
 185                 env__usb_dev_port['host_usb_dev_node'], ignore_errors)
 186         except:
 187             if not ignore_errors:
 188                 raise
 189
 190     def run_dfu_util(alt_setting, fn, up_dn_load_arg):
 191         """Invoke dfu-util on the host.
 192
 193         Args:
 194             alt_setting: The DFU "alternate setting" identifier to interact
 195                 with.
 196             fn: The host-side file name to transfer.
 197             up_dn_load_arg: '-U' or '-D' depending on whether a DFU upload or
 198                 download operation should be performed.
 199
 200         Returns:
 201             Nothing.
 202         """
 203
 204         cmd = ['dfu-util', '-a', alt_setting, up_dn_load_arg, fn]
 205         if 'host_usb_port_path' in env__usb_dev_port:
 206             cmd += ['-p', env__usb_dev_port['host_usb_port_path']]
 207         u_boot_utils.run_and_log(u_boot_console, cmd)
 208         u_boot_console.wait_for('Ctrl+C to exit ...')
 209
 210     def dfu_write(alt_setting, fn):
 211         """Write a file to the target board using DFU.
 212
 213         Args:
 214             alt_setting: The DFU "alternate setting" identifier to interact
 215                 with.
 216             fn: The host-side file name to transfer.
 217
 218         Returns:
 219             Nothing.
 220         """
 221
 222         run_dfu_util(alt_setting, fn, '-D')
 223
 224     def dfu_read(alt_setting, fn):
 225         """Read a file from the target board using DFU.
 226
 227         Args:
 228             alt_setting: The DFU "alternate setting" identifier to interact
 229                 with.
 230             fn: The host-side file name to transfer.
 231
 232         Returns:
 233             Nothing.
 234         """
 235
 236         # dfu-util fails reads/uploads if the host file already exists
 237         if os.path.exists(fn):
 238             os.remove(fn)
 239         run_dfu_util(alt_setting, fn, '-U')
 240
 241     def dfu_write_read_check(size):
 242         """Test DFU transfers of a specific size of data
 243
 244         This function first writes data to the board then reads it back and
 245         compares the written and read back data. Measures are taken to avoid
 246         certain types of false positives.
 247
 248         Args:
 249             size: The data size to test.
 250
 251         Returns:
 252             Nothing.
 253         """
 254
 255         test_f = u_boot_utils.PersistentRandomFile(u_boot_console,
 256             'dfu_%d.bin' % size, size)
 257         readback_fn = u_boot_console.config.result_dir + '/dfu_readback.bin'
 258
 259         u_boot_console.log.action('Writing test data to DFU primary ' +
 260             'altsetting')
 261         dfu_write(alt_setting_test_file, test_f.abs_fn)
 262
 263         u_boot_console.log.action('Writing dummy data to DFU secondary ' +
 264             'altsetting to clear DFU buffers')
 265         dfu_write(alt_setting_dummy_file, dummy_f.abs_fn)
 266
 267         u_boot_console.log.action('Reading DFU primary altsetting for ' +
 268             'comparison')
 269         dfu_read(alt_setting_test_file, readback_fn)
 270
 271         u_boot_console.log.action('Comparing written and read data')
 272         written_hash = test_f.content_hash
 273         read_back_hash = u_boot_utils.md5sum_file(readback_fn, size)
 274         assert(written_hash == read_back_hash)
 275
 276     # This test may be executed against multiple USB ports. The test takes a
 277     # long time, so we don't want to do the whole thing each time. Instead,
 278     # execute the full test on the first USB port, and perform a very limited
 279     # test on other ports. In the limited case, we solely validate that the
 280     # host PC can enumerate the U-Boot USB device.
 281     global first_usb_dev_port
 282     if not first_usb_dev_port:
 283         first_usb_dev_port = env__usb_dev_port
 284     if env__usb_dev_port == first_usb_dev_port:
 285         sizes = env__dfu_config.get('test_sizes', test_sizes_default)
 286     else:
 287         sizes = []
 288
 289     dummy_f = u_boot_utils.PersistentRandomFile(u_boot_console,
 290         'dfu_dummy.bin', 1024)
 291
 292     alt_setting_test_file = env__dfu_config.get('alt_id_test_file', '0')
 293     alt_setting_dummy_file = env__dfu_config.get('alt_id_dummy_file', '1')
 294
 295     ignore_cleanup_errors = True
 296     try:
 297         start_dfu()
 298
 299         u_boot_console.log.action(
 300             'Overwriting DFU primary altsetting with dummy data')
 301         dfu_write(alt_setting_test_file, dummy_f.abs_fn)
 302
 303         for size in sizes:
 304             with u_boot_console.log.section('Data size %d' % size):
 305                 dfu_write_read_check(size)
 306                 # Make the status of each sub-test obvious. If the test didn't
 307                 # pass, an exception was thrown so this code isn't executed.
 308                 u_boot_console.log.status_pass('OK')
 309         ignore_cleanup_errors = False
 310     finally:
 311         stop_dfu(ignore_cleanup_errors)