test_dfu.py 9.28 KB
Newer Older
Stephen Warren's avatar
Stephen Warren committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14
# Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
#
# SPDX-License-Identifier: GPL-2.0

# Test U-Boot's "dfu" command. The test starts DFU in U-Boot, waits for USB
# device enumeration on the host, executes dfu-util multiple times to test
# various transfer sizes, many of which trigger USB driver edge cases, and
# finally aborts the "dfu" command in U-Boot.

import os
import os.path
import pytest
import u_boot_utils

15
"""
Stephen Warren's avatar
Stephen Warren committed
16 17 18 19 20 21 22 23
Note: This test relies on:

a) boardenv_* to contain configuration values to define which USB ports are
available for testing. Without this, this test will be automatically skipped.
For example:

env__usb_dev_ports = (
    {
24
        "fixture_id": "micro_b",
Stephen Warren's avatar
Stephen Warren committed
25 26 27 28 29 30 31 32 33 34 35
        "tgt_usb_ctlr": "0",
        "host_usb_dev_node": "/dev/usbdev-p2371-2180",
        # This parameter is optional /if/ you only have a single board
        # attached to your host at a time.
        "host_usb_port_path": "3-13",
    },
)

env__dfu_configs = (
    # eMMC, partition 1
    {
36
        "fixture_id": "emmc",
Stephen Warren's avatar
Stephen Warren committed
37 38
        "alt_info": "/dfu_test.bin ext4 0 1;/dfu_dummy.bin ext4 0 1",
        "cmd_params": "mmc 0",
39 40 41 42 43 44 45 46
        # This value is optional.
        # If present, it specified the set of transfer sizes tested.
        # If missing, a default list of sizes will be used, which covers
        #   various useful corner cases.
        # Manually specifying test sizes is useful if you wish to test 4 DFU
        # configurations, but don't want to test every single transfer size
        # on each, to avoid bloating the overall time taken by testing.
        "test_sizes": (63, 64, 65),
Stephen Warren's avatar
Stephen Warren committed
47 48
    },
)
49

Stephen Warren's avatar
Stephen Warren committed
50 51 52 53 54 55 56 57
b) udev rules to set permissions on devices nodes, so that sudo is not
required. For example:

ACTION=="add", SUBSYSTEM=="block", SUBSYSTEMS=="usb", KERNELS=="3-13", MODE:="666"

(You may wish to change the group ID instead of setting the permissions wide
open. All that matters is that the user ID running the test can access the
device.)
58
"""
Stephen Warren's avatar
Stephen Warren committed
59 60 61 62

# The set of file sizes to test. These values trigger various edge-cases such
# as one less than, equal to, and one greater than typical USB max packet
# sizes, and similar boundary conditions.
63
test_sizes_default = (
Stephen Warren's avatar
Stephen Warren committed
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
    64 - 1,
    64,
    64 + 1,
    128 - 1,
    128,
    128 + 1,
    960 - 1,
    960,
    960 + 1,
    4096 - 1,
    4096,
    4096 + 1,
    1024 * 1024 - 1,
    1024 * 1024,
    8 * 1024 * 1024,
)

first_usb_dev_port = None

@pytest.mark.buildconfigspec('cmd_dfu')
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
Stephen Warren's avatar
Stephen Warren committed
86 87 88 89 90 91 92 93 94 95 96 97 98 99
    device when "dfu" is running, various DFU transfers are tested, and the
    USB device must disappear when "dfu" is aborted.

    Args:
        u_boot_console: A U-Boot console connection.
        env__usb_dev_port: The single USB device-mode port specification on
            which to run the test. See the file-level comment above for
            details of the format.
        env__dfu_config: The single DFU (memory region) configuration on which
            to run the test. See the file-level comment above for details
            of the format.

    Returns:
        Nothing.
100
    """
Stephen Warren's avatar
Stephen Warren committed
101

102 103 104 105
    # Default alt settings for test and dummy files
    alt_setting_test_file = 0
    alt_setting_dummy_file = 1

Stephen Warren's avatar
Stephen Warren committed
106
    def start_dfu():
107
        """Start U-Boot's dfu shell command.
Stephen Warren's avatar
Stephen Warren committed
108 109 110 111 112 113 114 115

        This also waits for the host-side USB enumeration process to complete.

        Args:
            None.

        Returns:
            Nothing.
116
        """
Stephen Warren's avatar
Stephen Warren committed
117

118 119 120 121 122 123
        fh = u_boot_utils.attempt_to_open_file(
            env__usb_dev_port['host_usb_dev_node'])
        if fh:
            fh.close()
            raise Exception('USB device present before dfu command invoked')

Stephen Warren's avatar
Stephen Warren committed
124 125 126 127 128 129 130 131 132 133 134 135 136 137
        u_boot_console.log.action(
            'Starting long-running U-Boot dfu shell command')

        cmd = 'setenv dfu_alt_info "%s"' % env__dfu_config['alt_info']
        u_boot_console.run_command(cmd)

        cmd = 'dfu 0 ' + env__dfu_config['cmd_params']
        u_boot_console.run_command(cmd, wait_for_prompt=False)
        u_boot_console.log.action('Waiting for DFU USB device to appear')
        fh = u_boot_utils.wait_until_open_succeeds(
            env__usb_dev_port['host_usb_dev_node'])
        fh.close()

    def stop_dfu(ignore_errors):
138
        """Stop U-Boot's dfu shell command from executing.
Stephen Warren's avatar
Stephen Warren committed
139 140 141 142 143 144 145 146 147 148 149 150

        This also waits for the host-side USB de-enumeration process to
        complete.

        Args:
            ignore_errors: Ignore any errors. This is useful if an error has
                already been detected, and the code is performing best-effort
                cleanup. In this case, we do not want to mask the original
                error by "honoring" any new errors.

        Returns:
            Nothing.
151
        """
Stephen Warren's avatar
Stephen Warren committed
152 153 154 155 156 157 158 159 160 161 162 163 164 165

        try:
            u_boot_console.log.action(
                'Stopping long-running U-Boot dfu shell command')
            u_boot_console.ctrlc()
            u_boot_console.log.action(
                'Waiting for DFU USB device to disappear')
            u_boot_utils.wait_until_file_open_fails(
                env__usb_dev_port['host_usb_dev_node'], ignore_errors)
        except:
            if not ignore_errors:
                raise

    def run_dfu_util(alt_setting, fn, up_dn_load_arg):
166
        """Invoke dfu-util on the host.
Stephen Warren's avatar
Stephen Warren committed
167 168 169 170 171 172 173 174 175 176

        Args:
            alt_setting: The DFU "alternate setting" identifier to interact
                with.
            fn: The host-side file name to transfer.
            up_dn_load_arg: '-U' or '-D' depending on whether a DFU upload or
                download operation should be performed.

        Returns:
            Nothing.
177
        """
Stephen Warren's avatar
Stephen Warren committed
178 179 180 181 182 183 184 185

        cmd = ['dfu-util', '-a', str(alt_setting), up_dn_load_arg, fn]
        if 'host_usb_port_path' in env__usb_dev_port:
            cmd += ['-p', env__usb_dev_port['host_usb_port_path']]
        u_boot_utils.run_and_log(u_boot_console, cmd)
        u_boot_console.wait_for('Ctrl+C to exit ...')

    def dfu_write(alt_setting, fn):
186
        """Write a file to the target board using DFU.
Stephen Warren's avatar
Stephen Warren committed
187 188 189 190 191 192 193 194

        Args:
            alt_setting: The DFU "alternate setting" identifier to interact
                with.
            fn: The host-side file name to transfer.

        Returns:
            Nothing.
195
        """
Stephen Warren's avatar
Stephen Warren committed
196 197 198 199

        run_dfu_util(alt_setting, fn, '-D')

    def dfu_read(alt_setting, fn):
200
        """Read a file from the target board using DFU.
Stephen Warren's avatar
Stephen Warren committed
201 202 203 204 205 206 207 208

        Args:
            alt_setting: The DFU "alternate setting" identifier to interact
                with.
            fn: The host-side file name to transfer.

        Returns:
            Nothing.
209
        """
Stephen Warren's avatar
Stephen Warren committed
210 211 212 213 214 215 216

        # dfu-util fails reads/uploads if the host file already exists
        if os.path.exists(fn):
            os.remove(fn)
        run_dfu_util(alt_setting, fn, '-U')

    def dfu_write_read_check(size):
217
        """Test DFU transfers of a specific size of data
Stephen Warren's avatar
Stephen Warren committed
218 219 220 221 222 223 224 225 226 227

        This function first writes data to the board then reads it back and
        compares the written and read back data. Measures are taken to avoid
        certain types of false positives.

        Args:
            size: The data size to test.

        Returns:
            Nothing.
228
        """
Stephen Warren's avatar
Stephen Warren committed
229 230 231 232 233 234 235

        test_f = u_boot_utils.PersistentRandomFile(u_boot_console,
            'dfu_%d.bin' % size, size)
        readback_fn = u_boot_console.config.result_dir + '/dfu_readback.bin'

        u_boot_console.log.action('Writing test data to DFU primary ' +
            'altsetting')
236
        dfu_write(alt_setting_test_file, test_f.abs_fn)
Stephen Warren's avatar
Stephen Warren committed
237 238 239

        u_boot_console.log.action('Writing dummy data to DFU secondary ' +
            'altsetting to clear DFU buffers')
240
        dfu_write(alt_setting_dummy_file, dummy_f.abs_fn)
Stephen Warren's avatar
Stephen Warren committed
241 242 243

        u_boot_console.log.action('Reading DFU primary altsetting for ' +
            'comparison')
244
        dfu_read(alt_setting_test_file, readback_fn)
Stephen Warren's avatar
Stephen Warren committed
245 246 247 248 249 250 251 252 253 254 255 256 257 258 259

        u_boot_console.log.action('Comparing written and read data')
        written_hash = test_f.content_hash
        read_back_hash = u_boot_utils.md5sum_file(readback_fn, size)
        assert(written_hash == read_back_hash)

    # This test may be executed against multiple USB ports. The test takes a
    # long time, so we don't want to do the whole thing each time. Instead,
    # execute the full test on the first USB port, and perform a very limited
    # test on other ports. In the limited case, we solely validate that the
    # host PC can enumerate the U-Boot USB device.
    global first_usb_dev_port
    if not first_usb_dev_port:
        first_usb_dev_port = env__usb_dev_port
    if env__usb_dev_port == first_usb_dev_port:
260
        sizes = env__dfu_config.get('test_sizes', test_sizes_default)
Stephen Warren's avatar
Stephen Warren committed
261 262 263 264 265 266 267 268 269 270 271 272
    else:
        sizes = []

    dummy_f = u_boot_utils.PersistentRandomFile(u_boot_console,
        'dfu_dummy.bin', 1024)

    ignore_cleanup_errors = True
    try:
        start_dfu()

        u_boot_console.log.action(
            'Overwriting DFU primary altsetting with dummy data')
273
        dfu_write(alt_setting_test_file, dummy_f.abs_fn)
Stephen Warren's avatar
Stephen Warren committed
274 275

        for size in sizes:
276
            with u_boot_console.log.section('Data size %d' % size):
Stephen Warren's avatar
Stephen Warren committed
277 278 279 280 281 282 283
                dfu_write_read_check(size)
                # Make the status of each sub-test obvious. If the test didn't
                # pass, an exception was thrown so this code isn't executed.
                u_boot_console.log.status_pass('OK')
        ignore_cleanup_errors = False
    finally:
        stop_dfu(ignore_cleanup_errors)