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