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