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",
33 # Optional entries (required only when "alt_id_test_file" and
34 # "alt_id_dummy_file" are specified).
35 test_file_name = "/dfu_test.bin"
36 dummy_file_name = "/dfu_dummy.bin"
37 # Above files are used to generate proper "alt_info" entry
38 "alt_info": "/%s ext4 0 2;/%s ext4 0 2" % (test_file_name, dummy_file_name),
44 "alt_info": "/dfu_test.bin ext4 0 1;/dfu_dummy.bin ext4 0 1",
45 "cmd_params": "mmc 0",
46 # This value is optional.
47 # If present, it specified the set of transfer sizes tested.
48 # If missing, a default list of sizes will be used, which covers
49 # various useful corner cases.
50 # Manually specifying test sizes is useful if you wish to test 4 DFU
51 # configurations, but don't want to test every single transfer size
52 # on each, to avoid bloating the overall time taken by testing.
53 "test_sizes": (63, 64, 65),
54 # This value is optional.
55 # The name of the environment variable that the the dfu command reads
56 # alt info from. If unspecified, this defaults to dfu_alt_info, which is
57 # valid for most systems. Some systems use a different variable name.
58 # One example is the Odroid XU3, which automatically generates
59 # $dfu_alt_info, each time the dfu command is run, by concatenating
60 # $dfu_alt_boot and $dfu_alt_system.
61 "alt_info_env_name": "dfu_alt_system",
62 # This value is optional.
63 # For boards which require the "test file" alt setting number other than
64 # default (0) it is possible to specify exact file name to be used as
66 "alt_id_test_file": test_file_name,
67 # This value is optional.
68 # For boards which require the "dummy file" alt setting number other
69 # than default (1) it is possible to specify exact file name to be used
71 "alt_id_dummy_file": dummy_file_name,
75 b) udev rules to set permissions on devices nodes, so that sudo is not
76 required. For example:
78 ACTION=="add", SUBSYSTEM=="block", SUBSYSTEMS=="usb", KERNELS=="3-13", MODE:="666"
80 (You may wish to change the group ID instead of setting the permissions wide
81 open. All that matters is that the user ID running the test can access the
85 # The set of file sizes to test. These values trigger various edge-cases such
86 # as one less than, equal to, and one greater than typical USB max packet
87 # sizes, and similar boundary conditions.
88 test_sizes_default = (
106 first_usb_dev_port = None
108 @pytest.mark.buildconfigspec('cmd_dfu')
109 def test_dfu(u_boot_console, env__usb_dev_port, env__dfu_config):
110 """Test the "dfu" command; the host system must be able to enumerate a USB
111 device when "dfu" is running, various DFU transfers are tested, and the
112 USB device must disappear when "dfu" is aborted.
115 u_boot_console: A U-Boot console connection.
116 env__usb_dev_port: The single USB device-mode port specification on
117 which to run the test. See the file-level comment above for
118 details of the format.
119 env__dfu_config: The single DFU (memory region) configuration on which
120 to run the test. See the file-level comment above for details
128 """Start U-Boot's dfu shell command.
130 This also waits for the host-side USB enumeration process to complete.
139 fh = u_boot_utils.attempt_to_open_file(
140 env__usb_dev_port['host_usb_dev_node'])
143 raise Exception('USB device present before dfu command invoked')
145 u_boot_console.log.action(
146 'Starting long-running U-Boot dfu shell command')
148 dfu_alt_info_env = env__dfu_config.get('alt_info_env_name', \
151 cmd = 'setenv "%s" "%s"' % (dfu_alt_info_env,
152 env__dfu_config['alt_info'])
153 u_boot_console.run_command(cmd)
155 cmd = 'dfu 0 ' + env__dfu_config['cmd_params']
156 u_boot_console.run_command(cmd, wait_for_prompt=False)
157 u_boot_console.log.action('Waiting for DFU USB device to appear')
158 fh = u_boot_utils.wait_until_open_succeeds(
159 env__usb_dev_port['host_usb_dev_node'])
162 def stop_dfu(ignore_errors):
163 """Stop U-Boot's dfu shell command from executing.
165 This also waits for the host-side USB de-enumeration process to
169 ignore_errors: Ignore any errors. This is useful if an error has
170 already been detected, and the code is performing best-effort
171 cleanup. In this case, we do not want to mask the original
172 error by "honoring" any new errors.
179 u_boot_console.log.action(
180 'Stopping long-running U-Boot dfu shell command')
181 u_boot_console.ctrlc()
182 u_boot_console.log.action(
183 'Waiting for DFU USB device to disappear')
184 u_boot_utils.wait_until_file_open_fails(
185 env__usb_dev_port['host_usb_dev_node'], ignore_errors)
187 if not ignore_errors:
190 def run_dfu_util(alt_setting, fn, up_dn_load_arg):
191 """Invoke dfu-util on the host.
194 alt_setting: The DFU "alternate setting" identifier to interact
196 fn: The host-side file name to transfer.
197 up_dn_load_arg: '-U' or '-D' depending on whether a DFU upload or
198 download operation should be performed.
204 cmd = ['dfu-util', '-a', alt_setting, up_dn_load_arg, fn]
205 if 'host_usb_port_path' in env__usb_dev_port:
206 cmd += ['-p', env__usb_dev_port['host_usb_port_path']]
207 u_boot_utils.run_and_log(u_boot_console, cmd)
208 u_boot_console.wait_for('Ctrl+C to exit ...')
210 def dfu_write(alt_setting, fn):
211 """Write a file to the target board using DFU.
214 alt_setting: The DFU "alternate setting" identifier to interact
216 fn: The host-side file name to transfer.
222 run_dfu_util(alt_setting, fn, '-D')
224 def dfu_read(alt_setting, fn):
225 """Read a file from the target board using DFU.
228 alt_setting: The DFU "alternate setting" identifier to interact
230 fn: The host-side file name to transfer.
236 # dfu-util fails reads/uploads if the host file already exists
237 if os.path.exists(fn):
239 run_dfu_util(alt_setting, fn, '-U')
241 def dfu_write_read_check(size):
242 """Test DFU transfers of a specific size of data
244 This function first writes data to the board then reads it back and
245 compares the written and read back data. Measures are taken to avoid
246 certain types of false positives.
249 size: The data size to test.
255 test_f = u_boot_utils.PersistentRandomFile(u_boot_console,
256 'dfu_%d.bin' % size, size)
257 readback_fn = u_boot_console.config.result_dir + '/dfu_readback.bin'
259 u_boot_console.log.action('Writing test data to DFU primary ' +
261 dfu_write(alt_setting_test_file, test_f.abs_fn)
263 u_boot_console.log.action('Writing dummy data to DFU secondary ' +
264 'altsetting to clear DFU buffers')
265 dfu_write(alt_setting_dummy_file, dummy_f.abs_fn)
267 u_boot_console.log.action('Reading DFU primary altsetting for ' +
269 dfu_read(alt_setting_test_file, readback_fn)
271 u_boot_console.log.action('Comparing written and read data')
272 written_hash = test_f.content_hash
273 read_back_hash = u_boot_utils.md5sum_file(readback_fn, size)
274 assert(written_hash == read_back_hash)
276 # This test may be executed against multiple USB ports. The test takes a
277 # long time, so we don't want to do the whole thing each time. Instead,
278 # execute the full test on the first USB port, and perform a very limited
279 # test on other ports. In the limited case, we solely validate that the
280 # host PC can enumerate the U-Boot USB device.
281 global first_usb_dev_port
282 if not first_usb_dev_port:
283 first_usb_dev_port = env__usb_dev_port
284 if env__usb_dev_port == first_usb_dev_port:
285 sizes = env__dfu_config.get('test_sizes', test_sizes_default)
289 dummy_f = u_boot_utils.PersistentRandomFile(u_boot_console,
290 'dfu_dummy.bin', 1024)
292 alt_setting_test_file = env__dfu_config.get('alt_id_test_file', '0')
293 alt_setting_dummy_file = env__dfu_config.get('alt_id_dummy_file', '1')
295 ignore_cleanup_errors = True
299 u_boot_console.log.action(
300 'Overwriting DFU primary altsetting with dummy data')
301 dfu_write(alt_setting_test_file, dummy_f.abs_fn)
304 with u_boot_console.log.section('Data size %d' % size):
305 dfu_write_read_check(size)
306 # Make the status of each sub-test obvious. If the test didn't
307 # pass, an exception was thrown so this code isn't executed.
308 u_boot_console.log.status_pass('OK')
309 ignore_cleanup_errors = False
311 stop_dfu(ignore_cleanup_errors)