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