test/py/tests/test_dfu.py

   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
   9 import os
  10 import os.path
  11 import pytest
  12 import u_boot_utils
  13
  14 """
  15 Note: This test relies on:
  16
  17 a) boardenv_* to contain configuration values to define which USB ports are
  18 available for testing. Without this, this test will be automatically skipped.
  19 For example:
  20
  21 env__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).
  34 test_file_name = "/dfu_test.bin"
  35 dummy_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
  39 env__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
  74 b) udev rules to set permissions on devices nodes, so that sudo is not
  75 required. For example:
  76
  77 ACTION=="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
  80 open. All that matters is that the user ID running the test can access the
  81 device.)
  82
  83 c) An optional udev rule to give you a persistent value to use in
  84 host_usb_dev_node. For example:
  85
  86 IMPORT{builtin}="path_id"
  87 ENV{ID_PATH}=="?*", ENV{.ID_PORT}=="", SYMLINK+="bus/usb/by-path/$env{ID_PATH}"
  88 ENV{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.
  94 test_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
 112 first_usb_dev_port = None
 113
 114 @pytest.mark.buildconfigspec('cmd_dfu')
 115 @pytest.mark.requiredtool('dfu-util')
 116 def 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)