Merge lp:~codehelp/lava-dispatcher/multinode-docs-update into lp:lava-dispatcher/multinode
- multinode-docs-update
- Merge into multinode
Proposed by
Neil Williams
Status: | Merged |
---|---|
Approved by: | Neil Williams |
Approved revision: | 691 |
Merged at revision: | 690 |
Proposed branch: | lp:~codehelp/lava-dispatcher/multinode-docs-update |
Merge into: | lp:lava-dispatcher/multinode |
Diff against target: |
723 lines (+369/-52) 5 files modified
doc/debugging.rst (+119/-0) doc/multinode.rst (+51/-0) doc/multinodeapi.rst (+18/-0) doc/usecaseone.rst (+95/-38) doc/usecasetwo.rst (+86/-14) |
To merge this branch: | bzr merge lp:~codehelp/lava-dispatcher/multinode-docs-update |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Milo Casagrande (community) | Approve | ||
Review via email: mp+181775@code.launchpad.net |
Commit message
Description of the change
This is the update containing the docs as shown in the demo.
To post a comment you must log in.
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1 | === added file 'doc/debugging.rst' |
2 | --- doc/debugging.rst 1970-01-01 00:00:00 +0000 |
3 | +++ doc/debugging.rst 2013-08-23 10:36:27 +0000 |
4 | @@ -0,0 +1,119 @@ |
5 | +.. _debugging: |
6 | + |
7 | +Debugging LAVA test definitions |
8 | +******************************* |
9 | + |
10 | +.. _singlenode: |
11 | + |
12 | +Convert Multi-Node jobs to single node |
13 | +====================================== |
14 | + |
15 | +The scripts available in the :ref:`multinode_api` are not installed for |
16 | +test jobs which are not part of a MultiNode group, so the job will simply |
17 | +fail that test as a ``command not found``. |
18 | + |
19 | +Therefore, by reversing the :ref:`changes_to_json`, a MultiNode JSON file |
20 | +can be converted to singlenode. |
21 | + |
22 | +Other calls which may require communication with other devices may need |
23 | +to be removed from your YAML. This can be extended to retain a set of |
24 | +singlenode YAML files in which new wrapper scripts and new builds are |
25 | +tested. |
26 | + |
27 | +The Job Definition of one job within a MultiNode group may be a good |
28 | +starting point for creating a singlenode equivalent. |
29 | + |
30 | +.. _set_x: |
31 | + |
32 | +Always use set -x in wrapper scripts |
33 | +==================================== |
34 | + |
35 | +By viewing the complete log, the complete processing of the wrapper script |
36 | +becomes obvious. |
37 | + |
38 | +:: |
39 | + |
40 | + #!/bin/sh |
41 | + set -e |
42 | + set -x |
43 | + |
44 | +.. _shell_operators: |
45 | + |
46 | +Avoid using shell operators in YAML lines |
47 | +========================================= |
48 | + |
49 | +Pipes, redirects and nested sub shells will not work reliably when put |
50 | +directly into the YAML. Use a wrapper script (with :ref:`set -x <set_x>`). |
51 | + |
52 | +:: |
53 | + |
54 | + #!/bin/sh |
55 | + |
56 | + set -e |
57 | + set -x |
58 | + ifconfig|grep "inet addr"|grep -v "127.0.0.1"|cut -d: -f2|cut -d' ' -f1 |
59 | + |
60 | +Un-nested sub-shells do work:: |
61 | + |
62 | + - lava-test-case multinode-send-network --shell lava-send network hostname=$(hostname) fqdn=$(hostname -f) |
63 | + |
64 | +.. _check_messageid: |
65 | + |
66 | +Check that your message ID labels are consistent |
67 | +================================================ |
68 | + |
69 | +A :ref:`lava_wait` must be preceded by a :ref:`lava_send` from at least |
70 | +one other device in the group or the waiting device will :ref:`timeout <timeouts>` |
71 | + |
72 | +This can be a particular problem if you remove test definitions from the |
73 | +JSON or edit a YAML file without checking other uses of the same file. |
74 | + |
75 | +``#`` can be used as a comment in YAML but JSON does not support |
76 | +comments, so take care. |
77 | + |
78 | +.. _parsers: |
79 | + |
80 | +Test your result parsers |
81 | +======================== |
82 | + |
83 | +If the YAML uses a custom result parser, configure one of your YAML files |
84 | +to output the entire test result output to stdout so that you can |
85 | +reliably capture a representative block of output. Test your proposed |
86 | +result parser against the block using your favourite language. |
87 | + |
88 | +Comment out the parser from the YAML if there are particular problems, |
89 | +just to see what the default LAVA parsers can provide. |
90 | + |
91 | +.. _paths: |
92 | + |
93 | +Be obsessive about paths and scripts |
94 | +==================================== |
95 | + |
96 | +* If you use ``cd`` in your YAML, always store where you were and where you end up using ``pwd``. |
97 | +* Output your location prior to calling local wrapper scripts. |
98 | +* Ensure that all wrapper scripts are executable in your VCS |
99 | +* Ensure that the relevant interpreter is installed. e.g. python is not necessarily part of the test image. |
100 | +* Consider installing ``realpath`` and use that to debug your directory structure. |
101 | + * Avoid the temptation of using absolute paths - LAVA may need to change the absolute locations. |
102 | + |
103 | +.. _failed_tests: |
104 | + |
105 | +A failed test is not necessarily a bug in the test |
106 | +================================================== |
107 | + |
108 | +Always check whether the test result came back as failed due to some |
109 | +cause other than the test definition itself. Particularly with MultiNode, |
110 | +a test result can fail due to some problem on a different board within |
111 | +the group. |
112 | + |
113 | +.. _json_files: |
114 | + |
115 | +Check your JSON files |
116 | +===================== |
117 | + |
118 | +Syntax problems will be picked up by LAVA when you submit but also check |
119 | +that the URLs listed in the JSON are correct. Keep your YAML descriptions, |
120 | +names and filenames unique so that it is easier to pick up if the JSON |
121 | +simply calls the wrong YAML test definition. |
122 | + |
123 | + |
124 | |
125 | === modified file 'doc/multinode.rst' |
126 | --- doc/multinode.rst 2013-08-19 10:36:07 +0000 |
127 | +++ doc/multinode.rst 2013-08-23 10:36:27 +0000 |
128 | @@ -29,6 +29,7 @@ |
129 | |
130 | multinodeapi.rst |
131 | multinode-usecases.rst |
132 | + debugging.rst |
133 | |
134 | Hardware requirements and virtualisation |
135 | **************************************** |
136 | @@ -70,6 +71,8 @@ |
137 | If more than one, but not all, roles share one particular action, that action will need to be repeated |
138 | within the JSON file, once for each role using that action. |
139 | |
140 | +.. _changes_to_json: |
141 | + |
142 | Changes to submission JSON |
143 | ========================== |
144 | |
145 | @@ -159,6 +162,8 @@ |
146 | or a lava-wait will fail on any node which waits longer than the default timeout. The node will receive a failure |
147 | response. |
148 | |
149 | +.. _timeouts: |
150 | + |
151 | Recommendations on timeouts |
152 | =========================== |
153 | |
154 | @@ -178,6 +183,52 @@ |
155 | waiting jobs have already failed due to a problem elsewhere in the group. If timeouts are too short, |
156 | jobs will fail unnecessarily. |
157 | |
158 | +Balancing timeouts |
159 | +^^^^^^^^^^^^^^^^^^ |
160 | + |
161 | +Individual actions and commands can have differing timeouts, so avoid the temptation to change the |
162 | +default timeout when a particular action times out in a Multi-Node job. If a particular ``lava-test-shell`` |
163 | +takes a long time, set an explicit timeout for that particular action: |
164 | + |
165 | +:: |
166 | + |
167 | + { |
168 | + "timeout": 900, |
169 | + "job_name": "netperf multinode tests", |
170 | + "logging_level": "DEBUG", |
171 | + } |
172 | + |
173 | + |
174 | +:: |
175 | + |
176 | + { |
177 | + "command": "lava_test_shell", |
178 | + "parameters": { |
179 | + "testdef_repos": [ |
180 | + { |
181 | + "git-repo": "git://git.linaro.org/people/guoqing.zhu/netperf-multinode.git", |
182 | + "testdef": "netperf-multinode-c-network.yaml" |
183 | + } |
184 | + ], |
185 | + "timeout": 2400, |
186 | + "role": "client" |
187 | + } |
188 | + }, |
189 | + { |
190 | + "command": "lava_test_shell", |
191 | + "parameters": { |
192 | + "testdef_repos": [ |
193 | + { |
194 | + "git-repo": "git://git.linaro.org/people/guoqing.zhu/netperf-multinode.git", |
195 | + "testdef": "netperf-multinode-s-network.yaml" |
196 | + } |
197 | + ], |
198 | + "timeout": 1800, |
199 | + "role": "server" |
200 | + } |
201 | + }, |
202 | + |
203 | + |
204 | Running a server on the device-under-test |
205 | ***************************************** |
206 | |
207 | |
208 | === modified file 'doc/multinodeapi.rst' |
209 | --- doc/multinodeapi.rst 2013-08-19 10:36:07 +0000 |
210 | +++ doc/multinodeapi.rst 2013-08-23 10:36:27 +0000 |
211 | @@ -1,3 +1,5 @@ |
212 | +.. _multinode_api: |
213 | + |
214 | MultiNode API |
215 | ============= |
216 | |
217 | @@ -6,6 +8,8 @@ |
218 | definitions which need to transfer files, long messages or other large amounts of data need to set up their |
219 | own network configuration, access and download methods and do the transfer in the test definition. |
220 | |
221 | +.. _lava_self: |
222 | + |
223 | lava-self |
224 | --------- |
225 | |
226 | @@ -13,6 +17,8 @@ |
227 | |
228 | Usage: ``lava-self`` |
229 | |
230 | +.. _lava_role: |
231 | + |
232 | lava-role |
233 | --------- |
234 | |
235 | @@ -25,6 +31,8 @@ |
236 | |
237 | $ ./run-$(lava-role) |
238 | |
239 | +.. _lava-group: |
240 | + |
241 | lava-group |
242 | ---------- |
243 | |
244 | @@ -42,6 +50,8 @@ |
245 | highbank02 backend |
246 | highbank03 backend |
247 | |
248 | +.. _lava_send: |
249 | + |
250 | lava-send |
251 | --------- |
252 | |
253 | @@ -55,6 +65,8 @@ |
254 | Examples will be provided below, together with ``lava-wait`` and |
255 | ``lava-wait-all``. |
256 | |
257 | +.. _lava_wait: |
258 | + |
259 | lava-wait |
260 | --------- |
261 | |
262 | @@ -75,6 +87,8 @@ |
263 | will be returned by subsequent calls to ``lava-wait`` for that message |
264 | ID. Use a different message ID to collate different message data. |
265 | |
266 | +.. _lava_wait_all: |
267 | + |
268 | lava-wait-all |
269 | ------------- |
270 | |
271 | @@ -108,6 +122,8 @@ |
272 | As with ``lava-wait``, the message ID is persistent for the duration of |
273 | the MultiNode group. |
274 | |
275 | +.. _lava_sync: |
276 | + |
277 | lava-sync |
278 | --------- |
279 | |
280 | @@ -119,6 +135,8 @@ |
281 | ``lava-sync foo`` is effectively the same as ``lava-send foo`` followed |
282 | by ``lava-wait-all foo``. |
283 | |
284 | +.. _lava_network: |
285 | + |
286 | lava-network |
287 | ------------ |
288 | |
289 | |
290 | === modified file 'doc/usecaseone.rst' |
291 | --- doc/usecaseone.rst 2013-08-19 10:36:07 +0000 |
292 | +++ doc/usecaseone.rst 2013-08-23 10:36:27 +0000 |
293 | @@ -1,34 +1,39 @@ |
294 | +.. _use_case_one: |
295 | + |
296 | Use Case One - Setting up a simple client:server test definition. |
297 | ***************************************************************** |
298 | |
299 | -One device needs to obtain / prepare some data and then make the data |
300 | +One device needs to obtain / prepare some data and then make the data |
301 | available to another device in the same group. |
302 | |
303 | Source Code |
304 | =========== |
305 | |
306 | - * The YAML snippets in this example are not complete, for a working example of the code, see: |
307 | +* The YAML snippets in this example are not complete, for a working example of the code, see: |
308 | |
309 | https://git.linaro.org/gitweb?p=people/neilwilliams/multinode-yaml.git;a=blob_plain;f=forwarder.yaml;hb=refs/heads/master |
310 | |
311 | https://git.linaro.org/gitweb?p=people/neilwilliams/multinode-yaml.git;a=blob_plain;f=receiver.yaml;hb=refs/heads/master |
312 | |
313 | - https://git.linaro.org/gitweb?p=people/neilwilliams/multinode-yaml.git;a=blob_plain;f=json/kvm-beagleblack-group.json;hb=HEAD |
314 | + https://git.linaro.org/gitweb?p=people/neilwilliams/multinode-yaml.git;a=blob_plain;f=json/beagleblack-use-case.json;hb=HEAD |
315 | |
316 | Requirements |
317 | ============ |
318 | |
319 | - * A mechanism to obtain the data, presumably from some third-party source |
320 | - * A sync to ensure that the file is ready to be offered to the other device |
321 | - * This ensures that the attempt to receive does not start early |
322 | - * A message to the original board that the data has been received and verified |
323 | - * This ensures that any cleanup of the data does not happen before the transfer is complete. |
324 | +1. A mechanism to obtain the data, presumably from some third-party source |
325 | +2. A sync to ensure that the file is ready to be offered to the other device |
326 | + |
327 | + 2.1. This ensures that the attempt to receive does not start early |
328 | + |
329 | +3. A message to the original board that the data has been received and verified |
330 | + |
331 | + 3.1. This ensures that any cleanup of the data does not happen before the transfer is complete. |
332 | |
333 | Methods |
334 | ======= |
335 | |
336 | - * Install a package which can obtain the data from the third party source |
337 | - * Install a package which can provide the means to get the data to the other board |
338 | +* Install a package which can obtain the data from the third party source |
339 | +* Install a package which can provide the means to get the data to the other board |
340 | |
341 | Control flow |
342 | ============ |
343 | @@ -66,8 +71,8 @@ |
344 | of the filter. To start each YAML file, ensure that the metadata contains |
345 | two metadata fields: |
346 | |
347 | - * format - **Lava-Test Test Definition 1.0** |
348 | - * description - your own descriptive text |
349 | +* format : **Lava-Test Test Definition 1.0** |
350 | +* description : your own descriptive text |
351 | |
352 | It is useful to also add the maintainer field with your email address |
353 | as this will be needed later if the test is to be added to one of the |
354 | @@ -82,10 +87,50 @@ |
355 | maintainer: |
356 | - neil.williams@linaro.org |
357 | |
358 | +Installing packages for use in a test |
359 | +------------------------------------- |
360 | + |
361 | +If your test image raises a usable network interface by default on boot, |
362 | +the YAML can specify a list of packages which need to be installed for |
363 | +this test definition: |
364 | + |
365 | +:: |
366 | + |
367 | + install: |
368 | + deps: |
369 | + - wget |
370 | + - apache2 |
371 | + |
372 | +If your test needs to raise the network interface itself, the package |
373 | +installation will need to be done in the run steps:: |
374 | + |
375 | + run: |
376 | + steps: |
377 | + - lava-test-case linux-linaro-ubuntu-route-ifconfig-up --shell ifconfig eth0 up |
378 | + - lava-test-case apt-update --shell apt-get update |
379 | + - lava-test-case install-deps --shell apt-get -y install wget apache2 |
380 | + |
381 | +Note that although KVM devices can use apt, the network interface fails |
382 | +the LAVA test, so use the manual install steps for non-bridged KVM devices. |
383 | |
384 | Preparing the test to send data |
385 | ------------------------------- |
386 | |
387 | +``modify-data.sh`` would, presumably, unpack the data, modify it in |
388 | +some way and pack it back up again. In this example, it would be a no-op |
389 | +but note that it still needs to exist in the top level directory of your |
390 | +VCS repo and be executable. |
391 | + |
392 | +Any packages required by ``modify-data.sh`` need to be added to the install |
393 | +deps of sender.yaml. Providing useful contents of ``modify-data.sh`` is |
394 | +left as an exercise for the reader. |
395 | + |
396 | +Modification happens before the :ref:`lava_sync` ``download`` which tells the |
397 | +receiver that the data is ready to be transferred. |
398 | + |
399 | +The sender then waits for the receiver to acknowledge a correct download |
400 | +using :ref:`lava_sync` ``received`` and cleans up. |
401 | + |
402 | sender.yaml |
403 | ^^^^^^^^^^^ |
404 | |
405 | @@ -98,7 +143,6 @@ |
406 | |
407 | run: |
408 | steps: |
409 | - - lava-test-case linux-linaro-ubuntu-route-ifconfig-up --shell ifconfig eth0 up |
410 | - lava-test-case multinode-network --shell lava-network broadcast eth0 |
411 | - lava-test-case wget-file --shell wget -O /var/www/testfile http://releases.linaro.org/latest/android/arndale/userdata.tar.bz2 |
412 | - ./modify-data.sh |
413 | @@ -112,12 +156,10 @@ |
414 | The receiver needs to know where to find the data. The sender can ensure that the |
415 | file is in a particular location, it is up to the YAML to get the rest of the |
416 | information of the network address of the sender. This example assumes that the |
417 | -data is modified in some undisclosed manner by the ```./modify-data.sh``` |
418 | +data is modified in some undisclosed manner by the ``./modify-data.sh`` |
419 | script which is part of your testdef_repo before the receiver is notified. |
420 | -Any packages required by ```modify-data.sh``` need to be added to the install |
421 | -deps of sender.yaml. The contents of ```modify-data.sh``` are left as an exercise for the reader. |
422 | |
423 | -The LAVA MultiNode API provides ways of querying the network information of devices |
424 | +The LAVA :ref:`multinode_api` provides ways of querying the network information of devices |
425 | within the group. In order to offer the data via apache, the sender needs to |
426 | raise a suitable network interface, so it calls ifconfig as a lava test case |
427 | first and then uses the lava-network API call to broadcast network information |
428 | @@ -159,33 +201,40 @@ |
429 | get-data.sh |
430 | ^^^^^^^^^^^ |
431 | |
432 | +Always use **set -x** in any wrapper / helper scripts which you expect |
433 | +to use in a test run to be able to debug test failures. |
434 | + |
435 | +Ensure that the scripts are marked as executable in your VCS and |
436 | +that the appropriate interpreter is installed in your test image. |
437 | + |
438 | :: |
439 | |
440 | #!/bin/sh |
441 | set -e |
442 | - DEVICE=`lava-group | grep -m1 -v kvm|cut -f2` |
443 | + set -x |
444 | + DEVICE=`lava-group | grep -m1 receiver|cut -f2` |
445 | SOURCE=`lava-network query $DEVICE ipv4|grep -v LAVA|cut -d: -f2` |
446 | wget -O /tmp/testfile http://${SOURCE}/testfile |
447 | |
448 | |
449 | -The ```$DEVICE``` simply matches the first device name in this group |
450 | -which contains the string 'kvm' and returns the full name of that device, |
451 | -e.g. multinode-kvm02 |
452 | +The ``$DEVICE`` simply matches the first device name in this group |
453 | +which contains the string 'receiver' (which comes from the ``role`` |
454 | +specified in the JSON) and returns the full name of that device, |
455 | +e.g. multinode-kvm02 or staging-beagleblack03 |
456 | |
457 | This device name is then passed to lava-network query to get the ipv4 |
458 | -details of that device within this group. The value of ```$SOURCE``` |
459 | +details of that device within this group. The value of ``$SOURCE`` |
460 | is an IPv4 address of the sender (assuming that your JSON has defined a |
461 | -device_type for the sender as a device which would contain |
462 | -the 'kvm' string in the name.) |
463 | +role for the sender which would contain the 'receiver' string in the name.) |
464 | |
465 | -Finally, ```get-data.sh``` does the work of receiving the data from |
466 | +Finally, ``get-data.sh`` does the work of receiving the data from |
467 | the sender. The verification of the data is left as an exercise for |
468 | the reader - one simple method would be for the sender to checksum the |
469 | -(modified) data and use ```lava-send``` to make that checksum available |
470 | -to devices within the group. The receiver can then use ```lava-wait``` |
471 | +(modified) data and use ``lava-send`` to make that checksum available |
472 | +to devices within the group. The receiver can then use ``lava-wait`` |
473 | to get that checksum. |
474 | |
475 | -Once ```get-data.sh``` returns, the receiver notifies the sender that |
476 | +Once ``get-data.sh`` returns, the receiver notifies the sender that |
477 | the transfer is complete, processes the data as it sees fit and cleans up. |
478 | |
479 | Preparing the JSON |
480 | @@ -193,7 +242,7 @@ |
481 | |
482 | The JSON ties the YAML test definition with the hardware and software to |
483 | run the test definition. The JSON is also where multiple test |
484 | -definitions are combined into a single !MultiNode test. |
485 | +definitions are combined into a single MultiNode test. |
486 | |
487 | General settings |
488 | ---------------- |
489 | @@ -289,8 +338,7 @@ |
490 | If any action has no role specified, it will be actioned for all roles. |
491 | |
492 | For Use Case One, we have a different YAML file for each role, so |
493 | -we have two lava_test_shell commands. (The content happens to be the |
494 | -same in this example.) |
495 | +we have two lava_test_shell commands. |
496 | |
497 | :: |
498 | |
499 | @@ -326,7 +374,8 @@ |
500 | ^^^^^^^^^^^^^^ |
501 | |
502 | The results for the entire group get aggregated into a single result |
503 | -bundle. |
504 | +bundle. Ensure that the bundle stream exists on the specified server |
505 | +and that you have permission to add to that stream. |
506 | |
507 | :: |
508 | |
509 | @@ -334,7 +383,7 @@ |
510 | { |
511 | "command": "submit_results_on_host", |
512 | "parameters": { |
513 | - "stream": "/anonymous/instance-manager/", |
514 | + "stream": "/anonymous/use-cases/", |
515 | "server": "http://validation.linaro.org/RPC2/" |
516 | } |
517 | } |
518 | @@ -343,7 +392,7 @@ |
519 | Prepare a filter for the results |
520 | ================================ |
521 | |
522 | -Now decide how your are going to analyse the results of tests using |
523 | +Now decide how you are going to analyse the results of tests using |
524 | this definition, using the name of the test definition specified in |
525 | the YAML metadata. |
526 | |
527 | @@ -385,7 +434,7 @@ |
528 | |
529 | On the website for the instance running the tests, click on Dashboard |
530 | and Filters. If you have permissions, there will be a link entitled |
531 | -*Add new filter...*. |
532 | +*Add new filter...*. |
533 | |
534 | The filter name should include most of the data about what this filter |
535 | is intended to do, without whitespace. This name will be preserved through |
536 | @@ -406,13 +455,13 @@ |
537 | |
538 | Within a test definition, a filter can also select only particular test |
539 | cases. In this Use Case, for example, the filter could choose only the |
540 | -```multinode-network```, ```multinode-get-network``` or ```file-sync``` |
541 | +``multinode-network``, ``multinode-get-network`` or ``file-sync`` |
542 | test cases. Continue to add tests and/or test cases - the more tests |
543 | and/or test cases are added to the filter, the fewer results will |
544 | match. |
545 | |
546 | Click the *Preview* button to apply the filter to the current set of |
547 | -results **without saving the filter**. |
548 | +results **without saving the filter**. |
549 | |
550 | In the preview, if there are columns with no data or rows with no data |
551 | for specific columns, these will show up as missing data in the filter |
552 | @@ -450,7 +499,7 @@ |
553 | |
554 | The full version of this use case are available: |
555 | |
556 | -http://git.linaro.org/gitweb?p=people/neilwilliams/multinode-yaml.git;a=blob_plain;f=json/kvm-beagleblack-group.json;hb=refs/heads/master |
557 | +http://git.linaro.org/gitweb?p=people/neilwilliams/multinode-yaml.git;a=blob_plain;f=json/kvm-beagleblack-group.json;hb=HEAD |
558 | |
559 | Example test results are visible here: |
560 | |
561 | @@ -462,3 +511,11 @@ |
562 | did not have a bridged configuration, so the internal networking of the kvm meant |
563 | that although the KVM could connect to the beaglebone-black, the beaglebone-black |
564 | could not connect to the kvm. |
565 | + |
566 | +https://git.linaro.org/gitweb?p=people/neilwilliams/multinode-yaml.git;a=blob_plain;f=json/beagleblack-use-case.json;hb=HEAD |
567 | + |
568 | +https://staging.validation.linaro.org/dashboard/image-reports/beagleblack-usecase |
569 | + |
570 | +https://staging.validation.linaro.org/dashboard/streams/anonymous/codehelp/bundles/cf4eb9e0022232e97aaec2737b3cd436cd37ab14/ |
571 | + |
572 | +This example uses two beaglebone-black devices. |
573 | |
574 | === modified file 'doc/usecasetwo.rst' |
575 | --- doc/usecasetwo.rst 2013-08-19 10:36:07 +0000 |
576 | +++ doc/usecasetwo.rst 2013-08-23 10:36:27 +0000 |
577 | @@ -1,3 +1,5 @@ |
578 | +.. _use_case_two: |
579 | + |
580 | Use Case Two - Setting up the same job on multiple devices |
581 | ********************************************************** |
582 | |
583 | @@ -7,7 +9,7 @@ |
584 | Source Code |
585 | =========== |
586 | |
587 | -The test definition itself could be an unchanged singlenode test definition, e.g. |
588 | +The test definition itself could be an unchanged singlenode test definition, e.g. |
589 | |
590 | https://git.linaro.org/gitweb?p=qa/test-definitions.git;a=blob_plain;f=ubuntu/smoke-tests-basic.yaml;hb=refs/heads/master |
591 | |
592 | @@ -30,10 +32,9 @@ |
593 | Preparing the YAML |
594 | ================== |
595 | |
596 | -In this use case, the same YAML file is to be used to test multiple devices. |
597 | -Select your YAML file and, if appropriate, edit the name in the metadata. |
598 | - |
599 | -TBD: MultiNode API |
600 | +In the first part of this use case, the same YAML file is to be used to |
601 | +test multiple devices. Select your YAML file and, if appropriate, edit |
602 | +the name in the metadata. |
603 | |
604 | Preparing the JSON |
605 | =================== |
606 | @@ -41,8 +42,8 @@ |
607 | The change from a standard single-node JSON file is to expand the device_type |
608 | or device field to a device_group. |
609 | |
610 | -The change for multiple devices in MultiNode is within the ```device_group```. To run the test |
611 | -multiple devices of the same type, simply increase the ```count``: |
612 | +The change for multiple devices in MultiNode is within the ``device_group``. To run the test |
613 | +multiple devices of the same type, simply increase the ``count``: |
614 | |
615 | :: |
616 | |
617 | @@ -55,15 +56,15 @@ |
618 | "tags": [ |
619 | "use-case-two" |
620 | ] |
621 | - } |
622 | + } |
623 | } |
624 | |
625 | -If the rest of the JSON refers to a ```role``` other than the one specified |
626 | -in the ```device_group```, those JSON sections are ignored. |
627 | +If the rest of the JSON refers to a ``role`` other than the one specified |
628 | +in the ``device_group``, those JSON sections are ignored. |
629 | |
630 | -If other actions in the JSON do not mention a ```role```, the action will |
631 | -occur on all devices in the ```device_group```. So with a single role, |
632 | -it only matters that a role exists in the ```device_group```. |
633 | +If other actions in the JSON do not mention a ``role``, the action will |
634 | +occur on all devices in the ``device_group``. So with a single role, |
635 | +it only matters that a role exists in the ``device_group``. |
636 | |
637 | actions |
638 | ------- |
639 | @@ -136,13 +137,84 @@ |
640 | Prepare a filter for the results |
641 | ================================ |
642 | |
643 | -The filter for this use case uses a ```required attribute``` |
644 | +The filter for this use case uses a ``required attribute`` |
645 | of **target.device_type** to only show results for the specified |
646 | devices (to cover reuse of the YAML on other boards later). |
647 | |
648 | It is also possible to add a second filter which matches a specific **target** |
649 | device. |
650 | |
651 | +Adding synchronisation |
652 | +====================== |
653 | + |
654 | +So far, the multiple devices have been started together but then had no |
655 | +further interaction. |
656 | + |
657 | +The :ref:`multinode_api` supports communication between devices within |
658 | +a group and provides synchronisation primitives. The simplest of these |
659 | +primitives, :ref:`lava_sync` was used in :ref:`use_case_one` but there are more |
660 | +possibilities available. |
661 | + |
662 | +:ref:`lava_sync` is a special case of a :ref:`lava_send` followed by a |
663 | +:ref:`lava_wait_all`. |
664 | + |
665 | +Sending messages |
666 | +---------------- |
667 | + |
668 | +Messages can be sent using :ref:`lava_send` which is a non-blocking call. |
669 | +At a later point, another device in the group can collect the message |
670 | +using ``lava-wait`` or ``lava-wait-all`` which will block until |
671 | +the message is available. |
672 | + |
673 | +The message can be a simple identifier (e.g. 'download' or 'ready') and |
674 | +is visible to all devices in the group. |
675 | + |
676 | +Key value pairs can also be sent using the API to broadcast particular |
677 | +information. |
678 | + |
679 | +If multiple devices send the same message ID, the data is collated by |
680 | +the LAVA Coordinator. Key value pairs sent with any message ID are |
681 | +tagged with the device name which sent the key value pairs. |
682 | + |
683 | +Receiving messages |
684 | +------------------ |
685 | + |
686 | +Message reception will block until the message is available. |
687 | + |
688 | +For :ref:`lava_wait`, the message is deemed available as soon as any device |
689 | +in the group has sent a message with the matching ID. If no devices have |
690 | +sent such a message, any device asking for ``lava-wait`` on that ID |
691 | +will block until a different board uses ``lava-send`` with the expected |
692 | +message ID. |
693 | + |
694 | +For :ref:`lava_wait_all`, the message is only deemed available if **all |
695 | +devices in the group** have already sent a message with the expected message |
696 | +ID. Therefore, using ``lava-wait-all`` requires a preceding |
697 | +``lava-send``. |
698 | + |
699 | +When using ``lava-wait-all MESSAGEID ROLE``, the message is only deemed |
700 | +available if **all devices with the matching role in the group** have |
701 | +sent a message with the expected message ID. If the receiving device has |
702 | +the specified role, that device must use a ``lava-send`` for the same |
703 | +message ID before using ``lava-wait-all MESSAGEID ROLE``. |
704 | + |
705 | +:: |
706 | + |
707 | + - lava-test-case multinode-send-network --shell lava-send ready |
708 | + - lava-test-case multinode-get-network --shell lava-wait ready |
709 | + |
710 | +It is up to the test writer to ensure that when :ref:`lava_wait` is used, |
711 | +that the message ID is sufficiently unique that the first use of that |
712 | +message ID denotes the correct point in the YAML. |
713 | + |
714 | +:: |
715 | + |
716 | + - lava-test-case multinode-send-message --shell lava-send sending source=$(lava-self) role=$(lava-role) hostname=$(hostname -f) kernver=$(uname -r) kernhost=$(uname -n) |
717 | + - lava-test-case multinode-wait-message --shell lava-wait-all sending |
718 | + |
719 | +This example will wait until all devices in the group have sent the |
720 | +message ID ''sending'' (with or without the associated key value pairs). |
721 | + |
722 | Summary |
723 | ======= |
724 |
It looked good on the demo, and going through it I do not see anything broken or wrong.
So, +1 from me.