1 # Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
3 # SPDX-License-Identifier: GPL-2.0
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.
16 Note: This test relies on:
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.
22 env__usb_dev_ports = (
24 "fixture_id": "micro_b",
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",
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),
50 b) udev rules to set permissions on devices nodes, so that sudo is not
51 required. For example:
53 ACTION=="add", SUBSYSTEM=="block", SUBSYSTEMS=="usb", KERNELS=="3-13", MODE:="666"
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
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 = (
81 first_usb_dev_port = None
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.
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
103 """Start U-Boot's dfu shell command.
105 This also waits for the host-side USB enumeration process to complete.
114 fh = u_boot_utils.attempt_to_open_file(
115 env__usb_dev_port['host_usb_dev_node'])
118 raise Exception('USB device present before dfu command invoked')
120 u_boot_console.log.action(
121 'Starting long-running U-Boot dfu shell command')
123 cmd = 'setenv dfu_alt_info "%s"' % env__dfu_config['alt_info']
124 u_boot_console.run_command(cmd)
126 cmd = 'dfu 0 ' + env__dfu_config['cmd_params']
127 u_boot_console.run_command(cmd, wait_for_prompt=False)
128 u_boot_console.log.action('Waiting for DFU USB device to appear')
129 fh = u_boot_utils.wait_until_open_succeeds(
130 env__usb_dev_port['host_usb_dev_node'])
133 def stop_dfu(ignore_errors):
134 """Stop U-Boot's dfu shell command from executing.
136 This also waits for the host-side USB de-enumeration process to
140 ignore_errors: Ignore any errors. This is useful if an error has
141 already been detected, and the code is performing best-effort
142 cleanup. In this case, we do not want to mask the original
143 error by "honoring" any new errors.
150 u_boot_console.log.action(
151 'Stopping long-running U-Boot dfu shell command')
152 u_boot_console.ctrlc()
153 u_boot_console.log.action(
154 'Waiting for DFU USB device to disappear')
155 u_boot_utils.wait_until_file_open_fails(
156 env__usb_dev_port['host_usb_dev_node'], ignore_errors)
158 if not ignore_errors:
161 def run_dfu_util(alt_setting, fn, up_dn_load_arg):
162 """Invoke dfu-util on the host.
165 alt_setting: The DFU "alternate setting" identifier to interact
167 fn: The host-side file name to transfer.
168 up_dn_load_arg: '-U' or '-D' depending on whether a DFU upload or
169 download operation should be performed.
175 cmd = ['dfu-util', '-a', str(alt_setting), up_dn_load_arg, fn]
176 if 'host_usb_port_path' in env__usb_dev_port:
177 cmd += ['-p', env__usb_dev_port['host_usb_port_path']]
178 u_boot_utils.run_and_log(u_boot_console, cmd)
179 u_boot_console.wait_for('Ctrl+C to exit ...')
181 def dfu_write(alt_setting, fn):
182 """Write a file to the target board using DFU.
185 alt_setting: The DFU "alternate setting" identifier to interact
187 fn: The host-side file name to transfer.
193 run_dfu_util(alt_setting, fn, '-D')
195 def dfu_read(alt_setting, fn):
196 """Read a file from the target board using DFU.
199 alt_setting: The DFU "alternate setting" identifier to interact
201 fn: The host-side file name to transfer.
207 # dfu-util fails reads/uploads if the host file already exists
208 if os.path.exists(fn):
210 run_dfu_util(alt_setting, fn, '-U')
212 def dfu_write_read_check(size):
213 """Test DFU transfers of a specific size of data
215 This function first writes data to the board then reads it back and
216 compares the written and read back data. Measures are taken to avoid
217 certain types of false positives.
220 size: The data size to test.
226 test_f = u_boot_utils.PersistentRandomFile(u_boot_console,
227 'dfu_%d.bin' % size, size)
228 readback_fn = u_boot_console.config.result_dir + '/dfu_readback.bin'
230 u_boot_console.log.action('Writing test data to DFU primary ' +
232 dfu_write(0, test_f.abs_fn)
234 u_boot_console.log.action('Writing dummy data to DFU secondary ' +
235 'altsetting to clear DFU buffers')
236 dfu_write(1, dummy_f.abs_fn)
238 u_boot_console.log.action('Reading DFU primary altsetting for ' +
240 dfu_read(0, readback_fn)
242 u_boot_console.log.action('Comparing written and read data')
243 written_hash = test_f.content_hash
244 read_back_hash = u_boot_utils.md5sum_file(readback_fn, size)
245 assert(written_hash == read_back_hash)
247 # This test may be executed against multiple USB ports. The test takes a
248 # long time, so we don't want to do the whole thing each time. Instead,
249 # execute the full test on the first USB port, and perform a very limited
250 # test on other ports. In the limited case, we solely validate that the
251 # host PC can enumerate the U-Boot USB device.
252 global first_usb_dev_port
253 if not first_usb_dev_port:
254 first_usb_dev_port = env__usb_dev_port
255 if env__usb_dev_port == first_usb_dev_port:
256 sizes = env__dfu_config.get('test_sizes', test_sizes_default)
260 dummy_f = u_boot_utils.PersistentRandomFile(u_boot_console,
261 'dfu_dummy.bin', 1024)
263 ignore_cleanup_errors = True
267 u_boot_console.log.action(
268 'Overwriting DFU primary altsetting with dummy data')
269 dfu_write(0, dummy_f.abs_fn)
272 with u_boot_console.log.section('Data size %d' % size):
273 dfu_write_read_check(size)
274 # Make the status of each sub-test obvious. If the test didn't
275 # pass, an exception was thrown so this code isn't executed.
276 u_boot_console.log.status_pass('OK')
277 ignore_cleanup_errors = False
279 stop_dfu(ignore_cleanup_errors)