blob: 5d87eb349bf4d9d7925154c0cf4be64b82c93b92 [file] [log] [blame]
Stephen Warrenf5d196d2016-01-22 12:30:14 -07001# SPDX-License-Identifier: GPL-2.0
Tom Rini83d290c2018-05-06 17:58:06 -04002# Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
Stephen Warrenf5d196d2016-01-22 12:30:14 -07003
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
Stephen Warrene8debf32016-01-26 13:41:30 -070014"""
Stephen Warrenf5d196d2016-01-22 12:30:14 -070015Note: 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 {
Simon Glass871bf7d2018-12-27 08:11:13 -070023 'fixture_id': 'micro_b',
24 'tgt_usb_ctlr': '0',
25 'host_usb_dev_node': '/dev/usbdev-p2371-2180',
Stephen Warrenf5d196d2016-01-22 12:30:14 -070026 # This parameter is optional /if/ you only have a single board
27 # attached to your host at a time.
Simon Glass871bf7d2018-12-27 08:11:13 -070028 'host_usb_port_path': '3-13',
Stephen Warrenf5d196d2016-01-22 12:30:14 -070029 },
30)
31
Simon Glass871bf7d2018-12-27 08:11:13 -070032# 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),
Lukasz Majewskif3a87f52016-04-20 10:57:08 +020038
Stephen Warrenf5d196d2016-01-22 12:30:14 -070039env__dfu_configs = (
40 # eMMC, partition 1
41 {
Simon Glass871bf7d2018-12-27 08:11:13 -070042 'fixture_id': 'emmc',
43 'alt_info': '/dfu_test.bin ext4 0 1;/dfu_dummy.bin ext4 0 1',
44 'cmd_params': 'mmc 0',
Stephen Warren26db3a62016-01-28 13:14:16 -070045 # 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.
Simon Glass871bf7d2018-12-27 08:11:13 -070052 'test_sizes': (63, 64, 65),
Lukasz Majewski8eb37522016-04-18 17:01:15 +020053 # 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.
Simon Glass871bf7d2018-12-27 08:11:13 -070060 'alt_info_env_name': 'dfu_alt_system',
Lukasz Majewskif3a87f52016-04-20 10:57:08 +020061 # This value is optional.
Simon Glass871bf7d2018-12-27 08:11:13 -070062 # For boards which require the 'test file' alt setting number other than
Lukasz Majewskif3a87f52016-04-20 10:57:08 +020063 # default (0) it is possible to specify exact file name to be used as
64 # this parameter.
Simon Glass871bf7d2018-12-27 08:11:13 -070065 'alt_id_test_file': test_file_name,
Lukasz Majewskif3a87f52016-04-20 10:57:08 +020066 # This value is optional.
Simon Glass871bf7d2018-12-27 08:11:13 -070067 # For boards which require the 'dummy file' alt setting number other
Lukasz Majewskif3a87f52016-04-20 10:57:08 +020068 # than default (1) it is possible to specify exact file name to be used
69 # as this parameter.
Simon Glass871bf7d2018-12-27 08:11:13 -070070 'alt_id_dummy_file': dummy_file_name,
Stephen Warrenf5d196d2016-01-22 12:30:14 -070071 },
72)
Stephen Warrend20e5e92016-01-26 15:26:04 -070073
Stephen Warrenf5d196d2016-01-22 12:30:14 -070074b) 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.)
Tom Rini845e10d2016-08-29 09:57:01 -040082
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}"
Stephen Warrene8debf32016-01-26 13:41:30 -070089"""
Stephen Warrenf5d196d2016-01-22 12:30:14 -070090
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.
Stephen Warren26db3a62016-01-28 13:14:16 -070094test_sizes_default = (
Stephen Warrenf5d196d2016-01-22 12:30:14 -070095 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')
Stephen Warren2d26bf62017-09-18 11:11:49 -0600115@pytest.mark.requiredtool('dfu-util')
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700116def test_dfu(u_boot_console, env__usb_dev_port, env__dfu_config):
Stephen Warrene8debf32016-01-26 13:41:30 -0700117 """Test the "dfu" command; the host system must be able to enumerate a USB
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700118 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.
Stephen Warrene8debf32016-01-26 13:41:30 -0700132 """
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700133
134 def start_dfu():
Stephen Warrene8debf32016-01-26 13:41:30 -0700135 """Start U-Boot's dfu shell command.
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700136
137 This also waits for the host-side USB enumeration process to complete.
138
139 Args:
140 None.
141
142 Returns:
143 Nothing.
Stephen Warrene8debf32016-01-26 13:41:30 -0700144 """
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700145
Stephen Warrendaa69f52016-05-05 17:02:06 -0600146 u_boot_utils.wait_until_file_open_fails(
147 env__usb_dev_port['host_usb_dev_node'], True)
Stephen Warrenbe1df822016-01-26 10:59:43 -0700148 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
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700154 u_boot_console.log.action(
155 'Starting long-running U-Boot dfu shell command')
156
Lukasz Majewski8eb37522016-04-18 17:01:15 +0200157 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'])
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700162 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):
Stephen Warrene8debf32016-01-26 13:41:30 -0700172 """Stop U-Boot's dfu shell command from executing.
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700173
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.
Stephen Warrene8debf32016-01-26 13:41:30 -0700185 """
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700186
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):
Stephen Warrene8debf32016-01-26 13:41:30 -0700200 """Invoke dfu-util on the host.
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700201
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.
Stephen Warrene8debf32016-01-26 13:41:30 -0700211 """
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700212
Lukasz Majewskif3a87f52016-04-20 10:57:08 +0200213 cmd = ['dfu-util', '-a', alt_setting, up_dn_load_arg, fn]
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700214 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):
Stephen Warrene8debf32016-01-26 13:41:30 -0700220 """Write a file to the target board using DFU.
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700221
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.
Stephen Warrene8debf32016-01-26 13:41:30 -0700229 """
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700230
231 run_dfu_util(alt_setting, fn, '-D')
232
233 def dfu_read(alt_setting, fn):
Stephen Warrene8debf32016-01-26 13:41:30 -0700234 """Read a file from the target board using DFU.
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700235
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.
Stephen Warrene8debf32016-01-26 13:41:30 -0700243 """
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700244
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):
Stephen Warrene8debf32016-01-26 13:41:30 -0700251 """Test DFU transfers of a specific size of data
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700252
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.
Stephen Warrene8debf32016-01-26 13:41:30 -0700262 """
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700263
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')
Lukasz Majewskic6eb8992016-04-20 10:36:32 +0200270 dfu_write(alt_setting_test_file, test_f.abs_fn)
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700271
272 u_boot_console.log.action('Writing dummy data to DFU secondary ' +
273 'altsetting to clear DFU buffers')
Lukasz Majewskic6eb8992016-04-20 10:36:32 +0200274 dfu_write(alt_setting_dummy_file, dummy_f.abs_fn)
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700275
276 u_boot_console.log.action('Reading DFU primary altsetting for ' +
277 'comparison')
Lukasz Majewskic6eb8992016-04-20 10:36:32 +0200278 dfu_read(alt_setting_test_file, readback_fn)
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700279
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:
Stephen Warren26db3a62016-01-28 13:14:16 -0700294 sizes = env__dfu_config.get('test_sizes', test_sizes_default)
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700295 else:
296 sizes = []
297
298 dummy_f = u_boot_utils.PersistentRandomFile(u_boot_console,
299 'dfu_dummy.bin', 1024)
300
Lukasz Majewskif3a87f52016-04-20 10:57:08 +0200301 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
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700304 ignore_cleanup_errors = True
305 try:
306 start_dfu()
307
308 u_boot_console.log.action(
309 'Overwriting DFU primary altsetting with dummy data')
Lukasz Majewskic6eb8992016-04-20 10:36:32 +0200310 dfu_write(alt_setting_test_file, dummy_f.abs_fn)
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700311
312 for size in sizes:
Stephen Warrena2ec5602016-01-26 13:41:31 -0700313 with u_boot_console.log.section('Data size %d' % size):
Stephen Warrenf5d196d2016-01-22 12:30:14 -0700314 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)