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