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