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