summaryrefslogtreecommitdiffstats
path: root/scripts
diff options
context:
space:
mode:
authorTom Zanussi <tom.zanussi@intel.com>2012-01-24 00:26:56 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-03-22 19:21:15 +0000
commit095c80b2be35153060753c17cee4b47207d0286e (patch)
treeb7018bfada3006daa654f272cd2b89c68e73bbaf /scripts
parent1e40e8a2306cac37e0dccfdc042a3d39c5cd9159 (diff)
downloadpoky-095c80b2be35153060753c17cee4b47207d0286e.tar.gz
yocto-bsp-tools: add help/usage
This is essentially 'the documentation' for the Yocto BSP tools, along with a few related functions. Signed-off-by: Tom Zanussi <tom.zanussi@intel.com>
Diffstat (limited to 'scripts')
-rw-r--r--scripts/lib/bsp/help.py570
1 files changed, 570 insertions, 0 deletions
diff --git a/scripts/lib/bsp/help.py b/scripts/lib/bsp/help.py
new file mode 100644
index 0000000000..200a4f8c09
--- /dev/null
+++ b/scripts/lib/bsp/help.py
@@ -0,0 +1,570 @@
1# ex:ts=4:sw=4:sts=4:et
2# -*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
3#
4# Copyright (c) 2012, Intel Corporation.
5# All rights reserved.
6#
7# This program is free software; you can redistribute it and/or modify
8# it under the terms of the GNU General Public License version 2 as
9# published by the Free Software Foundation.
10#
11# This program is distributed in the hope that it will be useful,
12# but WITHOUT ANY WARRANTY; without even the implied warranty of
13# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14# GNU General Public License for more details.
15#
16# You should have received a copy of the GNU General Public License along
17# with this program; if not, write to the Free Software Foundation, Inc.,
18# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19#
20# DESCRIPTION
21# This module implements some basic help invocation functions along
22# with the bulk of the help topic text for the Yocto BSP Tools.
23#
24# AUTHORS
25# Tom Zanussi <tom.zanussi (at] intel.com>
26#
27
28import subprocess
29import logging
30
31
32def subcommand_error(args):
33 logging.info("invalid subcommand %s" % args[0])
34
35
36def display_help(subcommand, subcommands):
37 """
38 Display help for subcommand.
39 """
40 if subcommand not in subcommands:
41 return False
42
43 help = subcommands.get(subcommand, subcommand_error)[2]
44 pager = subprocess.Popen('less', stdin=subprocess.PIPE)
45 pager.communicate(help)
46
47 return True
48
49
50def yocto_help(args, usage_str, subcommands):
51 """
52 Subcommand help dispatcher.
53 """
54 if len(args) == 1 or not display_help(args[1], subcommands):
55 print(usage_str)
56
57
58def invoke_subcommand(args, parser, main_command_usage, subcommands):
59 """
60 Dispatch to subcommand handler borrowed from combo-layer.
61 Should use argparse, but has to work in 2.6.
62 """
63 if not args:
64 logging.error("No subcommand specified, exiting")
65 parser.print_help()
66 elif args[0] == "help":
67 yocto_help(args, main_command_usage, subcommands)
68 elif args[0] not in subcommands:
69 logging.error("Unsupported subcommand %s, exiting\n" % (args[0]))
70 parser.print_help()
71 else:
72 usage = subcommands.get(args[0], subcommand_error)[1]
73 subcommands.get(args[0], subcommand_error)[0](args[1:], usage)
74
75
76##
77# yocto-bsp help and usage strings
78##
79
80yocto_bsp_usage = """
81
82 Create a customized Yocto BSP layer.
83
84 usage: yocto-bsp [--version] [--help] COMMAND [ARGS]
85
86 The most commonly used 'yocto-bsp' commands are:
87 create Create a new Yocto BSP
88 list List available values for options and BSP properties
89
90 See 'yocto-bsp help COMMAND' for more information on a specific command.
91"""
92
93yocto_bsp_help_usage = """
94
95 usage: yocto-bsp help <subcommand>
96
97 This command displays detailed help for the specified subcommand.
98"""
99
100yocto_bsp_create_usage = """
101
102 Create a new Yocto BSP
103
104 usage: yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
105 [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
106
107 This command creates a Yocto BSP based on the specified parameters.
108 The new BSP will be a new Yocto BSP layer contained by default within
109 the top-level directory specified as 'meta-bsp-name'. The -o option
110 can be used to place the BSP layer in a directory with a different
111 name and location.
112
113 The value of the 'karch' parameter determines the set of files that
114 will be generated for the BSP, along with the specific set of
115 'properties' that will be used to fill out the BSP-specific portions
116 of the BSP. The possible values for the 'karch' paramter can be
117 listed via 'yocto-bsp list karch'.
118"""
119
120yocto_bsp_create_help = """
121
122NAME
123 yocto-bsp create - Create a new Yocto BSP
124
125SYNOPSIS
126 yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
127 [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
128
129DESCRIPTION
130 This command creates a Yocto BSP based on the specified
131 parameters. The new BSP will be a new Yocto BSP layer contained
132 by default within the top-level directory specified as
133 'meta-bsp-name'. The -o option can be used to place the BSP layer
134 in a directory with a different name and location.
135
136 The value of the 'karch' parameter determines the set of files
137 that will be generated for the BSP, along with the specific set of
138 'properties' that will be used to fill out the BSP-specific
139 portions of the BSP. The possible values for the 'karch' paramter
140 can be listed via 'yocto-bsp list karch'.
141
142 The BSP-specific properties that define the values that will be
143 used to generate a particular BSP can be specified on the
144 command-line using the -i option and supplying a JSON object
145 consisting of the set of name:value pairs needed by the BSP.
146
147 If the -i option is not used, the user will be interactively
148 prompted for each of the required property values, which will then
149 be used as values for BSP generation.
150
151 The set of properties available for a given architecture can be
152 listed using the 'yocto-bsp list' command.
153
154 Specifying -c causes the Python code generated and executed to
155 create the BSP to be dumped to the 'bspgen.out' file in the
156 current directory, and is useful for debugging.
157
158 NOTE: Once created, you should add your new layer to your
159 bblayers.conf file in order for it to be subsquently seen and
160 modified by the yocto-kernel tool.
161
162 NOTE for x86- and x86_64-based BSPs: The generated BSP assumes the
163 presence of the of the meta-intel layer, so you should also have a
164 meta-intel layer present and added to your bblayers.conf as well.
165"""
166
167yocto_bsp_list_usage = """
168
169 usage: yocto-bsp list karch
170 yocto-bsp list <karch> properties
171 [-o <JSON PROPERTY FILE> | --outfile <JSON PROPERTY_FILE>]
172 yocto-bsp list <karch> property <xxx>
173 [-o <JSON PROPERTY FILE> | --outfile <JSON PROPERTY_FILE>]
174
175 This command enumerates the complete set of possible values for a
176 specified option or property needed by the BSP creation process.
177
178 The first form enumerates all the possible values that exist and can
179 be specified for the 'karch' parameter to the 'yocto bsp create'
180 command.
181
182 The second form enumerates all the possible properties that exist and
183 must have values specified for them in the 'yocto bsp create' command
184 for the given 'karch'.
185
186 The third form enumerates all the possible values that exist and can
187 be specified for any of the enumerable properties of the given
188 'karch' in the 'yocto bsp create' command.
189
190 See 'yocto-bsp help list' for more details.
191"""
192
193yocto_bsp_list_help = """
194
195NAME
196 yocto-bsp list - List available values for options and BSP properties
197
198SYNOPSIS
199 yocto-bsp list karch
200 yocto-bsp list <karch> properties
201 [--o <JSON PROPERTY FILE> | -outfile <JSON PROPERTY_FILE>]
202 yocto-bsp list <karch> property <xxx>
203 [--o <JSON PROPERTY FILE> | -outfile <JSON PROPERTY_FILE>]
204
205DESCRIPTION
206 This command enumerates the complete set of possible values for a
207 specified option or property needed by the BSP creation process.
208
209 The first form enumerates all the possible values that exist and
210 can be specified for the 'karch' parameter to the 'yocto bsp
211 create' command. Example output for the 'list karch' command:
212
213 $ yocto-bsp list karch
214 Architectures available:
215 arm
216 powerpc
217 i386
218 mips
219 x86_64
220 qemu
221
222 The second form enumerates all the possible properties that exist
223 and must have values specified for them in the 'yocto bsp create'
224 command for the given 'karch'. This command is mainly meant to
225 allow the development user interface alternatives to the default
226 text-based prompting interface. If the -o option is specified,
227 the list of properties, in addition to being displayed, will be
228 written to the specified file as a JSON object. In this case, the
229 object will consist of the set of name:value pairs corresponding
230 to the (possibly nested) dictionary of properties defined by the
231 input statements used by the BSP. Some example output for the
232 'list properties' command:
233
234 $ yocto-bsp list arm properties
235 "touchscreen" : {
236 "msg" : Does your BSP have a touchscreen? (y/N)
237 "default" : n
238 "type" : boolean
239 }
240 "uboot_loadaddress" : {
241 "msg" : Please specify a value for UBOOT_LOADADDRESS.
242 "default" : 0x80008000
243 "type" : edit
244 "prio" : 40
245 }
246 "kernel_choice" : {
247 "prio" : 10
248 "default" : linux-yocto_3.2
249 "depends-on" : use_default_kernel
250 "depends-on-val" : n
251 "msg" : Please choose the kernel to use in this BSP =>
252 "type" : choicelist
253 "gen" : bsp.kernel.kernels
254 }
255 "if kernel_choice == "linux-yocto_3.0":" : {
256 "base_kbranch_linux_yocto_3_0" : {
257 "prio" : 20
258 "default" : yocto/standard
259 "depends-on" : new_kbranch_linux_yocto_3_0
260 "depends-on-val" : y
261 "msg" : Please choose a machine branch to base this BSP on =>
262 "type" : choicelist
263 "gen" : bsp.kernel.all_branches
264 }
265 .
266 .
267 .
268
269 Each entry in the output consists of the name of the input element
270 e.g. "touchscreen", followed by the properties defined for that
271 element enclosed in braces. This information should provide
272 sufficient information to create a complete user interface with.
273 Two features of the scheme provide for conditional input. First,
274 if a Python "if" statement appears in place of an input element
275 name, the set of enclosed input elements apply and should be
276 presented to the user only if the 'if' statement evaluates to
277 true. The test in the if statement will always reference another
278 input element in the list, which means that the element being
279 tested should be presented to the user before the elements
280 enclosed by the if block. Secondly, in a similar way, some
281 elements contain "depends-on" and depends-on-val" tags, which mean
282 that the affected input element should only be presented to the
283 user if the element it depends on has already been presented to
284 the user and the user has selected the specified value for that
285 element.
286
287 The third form enumerates all the possible values that exist and
288 can be specified for any of the enumerable properties of the given
289 'karch' in the 'yocto bsp create' command. If the -o option is
290 specified, the list of values for the given property, in addition
291 to being displayed, will be written to the specified file as a
292 JSON object. In this case, the object will consist of the set of
293 name:value pairs corresponding to the array of property values
294 associated with the property.
295
296 $ yocto-bsp list i386 property xserver_choice
297 ["xserver_vesa", "VESA xserver support"]
298 ["xserver_emgd", "EMGD xserver support (proprietary)"]
299 ["xserver_i915", "i915 xserver support"]
300
301 $ yocto-bsp list arm property base_kbranch_linux_yocto_3_0
302 Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.0...
303 ["yocto/base", "yocto/base"]
304 ["yocto/eg20t", "yocto/eg20t"]
305 ["yocto/emgd", "yocto/emgd"]
306 ["yocto/emgd-1.10", "yocto/emgd-1.10"]
307 ["yocto/gma500", "yocto/gma500"]
308 ["yocto/pvr", "yocto/pvr"]
309 ["yocto/standard/arm-versatile-926ejs", "yocto/standard/arm-versatile-926ejs"]
310 ["yocto/standard/base", "yocto/standard/base"]
311 ["yocto/standard/beagleboard", "yocto/standard/beagleboard"]
312 ["yocto/standard/cedartrail", "yocto/standard/cedartrail"]
313 .
314 .
315 .
316 ["yocto/standard/qemu-ppc32", "yocto/standard/qemu-ppc32"]
317 ["yocto/standard/routerstationpro", "yocto/standard/routerstationpro"]
318
319 The third form as well is meant mainly for developers of
320 alternative interfaces - it allows the developer to fetch the
321 possible values for a given input element on-demand. This
322 on-demand capability is especially valuable for elements that
323 require relatively expensive remote operations to fulfill, such as
324 the example that returns the set of branches available in a remote
325 git tree above.
326
327"""
328
329##
330# yocto-kernel help and usage strings
331##
332
333yocto_kernel_usage = """
334
335 Modify and list Yocto BSP kernel config items and patches.
336
337 usage: yocto-kernel [--version] [--help] COMMAND [ARGS]
338
339 The most commonly used 'yocto-kernel' commands are:
340 config list List the modifiable set of bare kernel config options for a BSP
341 config add Add or modify bare kernel config options for a BSP
342 config rm Remove bare kernel config options from a BSP
343 patch list List the patches associated with a BSP
344 patch add Patch the Yocto kernel for a BSP
345 patch rm Remove patches from a BSP
346
347 See 'yocto-kernel help COMMAND' for more information on a specific command.
348
349"""
350
351
352yocto_kernel_help_usage = """
353
354 usage: yocto-kernel help <subcommand>
355
356 This command displays detailed help for the specified subcommand.
357"""
358
359yocto_kernel_config_list_usage = """
360
361 List the modifiable set of bare kernel config options for a BSP
362
363 usage: yocto-kernel config list <bsp-name>
364
365 This command lists the 'modifiable' config items for a BSP i.e. the
366 items which are eligible for modification or removal by other
367 yocto-kernel commands.
368
369 'modifiable' config items are the config items contained a BSP's
370 user-config.cfg base config.
371"""
372
373
374yocto_kernel_config_list_help = """
375
376NAME
377 yocto-kernel config list - List the modifiable set of bare kernel
378 config options for a BSP
379
380SYNOPSIS
381 yocto-kernel config list <bsp-name>
382
383DESCRIPTION
384 This command lists the 'modifiable' config items for a BSP
385 i.e. the items which are eligible for modification or removal by
386 other yocto-kernel commands.
387"""
388
389
390yocto_kernel_config_add_usage = """
391
392 Add or modify bare kernel config options for a BSP
393
394 usage: yocto-kernel config add <bsp-name> [<CONFIG_XXX=x> ...]
395
396 This command adds one or more CONFIG_XXX=x items to a BSP's user-config.cfg
397 base config.
398"""
399
400
401yocto_kernel_config_add_help = """
402
403NAME
404 yocto-kernel config add - Add or modify bare kernel config options
405 for a BSP
406
407SYNOPSIS
408 yocto-kernel config add <bsp-name> [<CONFIG_XXX=x> ...]
409
410DESCRIPTION
411 This command adds one or more CONFIG_XXX=x items to a BSP's
412 foo.cfg base config.
413
414 NOTE: It's up to the user to determine whether or not the config
415 options being added make sense or not - this command does no
416 sanity checking or verification of any kind to ensure that a
417 config option really makes sense and will actually be set in in
418 the final config. For example, if a config option depends on
419 other config options, it will be turned off by kconfig if the
420 other options aren't set correctly.
421"""
422
423
424yocto_kernel_config_rm_usage = """
425
426 Remove bare kernel config options from a BSP
427
428 usage: yocto-kernel config rm <bsp-name>
429
430 This command removes (turns off) one or more CONFIG_XXX items from a
431 BSP's user-config.cfg base config.
432
433 The set of config items available to be removed by this command for a
434 BSP is listed and the user prompted for the specific items to remove.
435"""
436
437
438yocto_kernel_config_rm_help = """
439
440NAME
441 yocto-kernel config rm - Remove bare kernel config options from a
442 BSP
443
444SYNOPSIS
445 yocto-kernel config rm <bsp-name>
446
447DESCRIPTION
448 This command removes (turns off) one or more CONFIG_XXX items from a
449 BSP's user-config.cfg base config.
450
451 The set of config items available to be removed by this command
452 for a BSP is listed and the user prompted for the specific items
453 to remove.
454"""
455
456
457yocto_kernel_patch_list_usage = """
458
459 List the patches associated with the kernel for a BSP
460
461 usage: yocto-kernel patch list <bsp-name>
462
463 This command lists the patches associated with a BSP.
464
465 NOTE: this only applies to patches listed in the kernel recipe's
466 user-patches.scc file (and currently repeated in its SRC_URI).
467"""
468
469
470yocto_kernel_patch_list_help = """
471
472NAME
473 yocto-kernel patch list - List the patches associated with the kernel
474 for a BSP
475
476SYNOPSIS
477 yocto-kernel patch list <bsp-name>
478
479DESCRIPTION
480 This command lists the patches associated with a BSP.
481
482 NOTE: this only applies to patches listed in the kernel recipe's
483 user-patches.scc file (and currently repeated in its SRC_URI).
484"""
485
486
487yocto_kernel_patch_add_usage = """
488
489 Patch the Yocto kernel for a specific BSP
490
491 usage: yocto-kernel patch add <bsp-name> [<PATCH> ...]
492
493 This command adds one or more patches to a BSP's machine branch. The
494 patch will be added to the BSP's linux-yocto kernel user-patches.scc
495 file (and currently repeated in its SRC_URI) and will be guaranteed
496 to be applied in the order specified.
497"""
498
499
500yocto_kernel_patch_add_help = """
501
502NAME
503 yocto-kernel patch add - Patch the Yocto kernel for a specific BSP
504
505SYNOPSIS
506 yocto-kernel patch add <bsp-name> [<PATCH> ...]
507
508DESCRIPTION
509 This command adds one or more patches to a BSP's machine branch.
510 The patch will be added to the BSP's linux-yocto kernel
511 user-patches.scc file (and currently repeated in its SRC_URI) and
512 will be guaranteed to be applied in the order specified.
513
514 NOTE: It's up to the user to determine whether or not the patches
515 being added makes sense or not - this command does no sanity
516 checking or verification of any kind to ensure that a patch can
517 actually be applied to the BSP's kernel branch; it's assumed that
518 the user has already done that.
519"""
520
521
522yocto_kernel_patch_rm_usage = """
523
524 Remove a patch from the Yocto kernel for a specific BSP
525
526 usage: yocto-kernel patch rm <bsp-name>
527
528 This command removes one or more patches from a BSP's machine branch.
529 The patch will be removed from the BSP's linux-yocto kernel
530 user-patches.scc file (and currently repeated in its SRC_URI) and
531 kernel SRC_URI dir.
532
533 The set of patches available to be removed by this command for a BSP
534 is listed and the user prompted for the specific patches to remove.
535"""
536
537
538yocto_kernel_patch_rm_help = """
539
540NAME
541 yocto-kernel patch rm - Remove a patch from the Yocto kernel for a specific BSP
542
543SYNOPSIS
544 yocto-kernel patch rm <bsp-name>
545
546DESCRIPTION
547 This command removes one or more patches from a BSP's machine
548 branch. The patch will be removed from the BSP's linux-yocto
549 kernel user-patches.scc file (and currently repeated in its
550 SRC_URI).
551
552 The set of patches available to be removed by this command for a
553 BSP is listed and the user prompted for the specific patches to
554 remove.
555"""
556
557##
558# test code
559##
560
561test_bsp_properties = {
562 'smp': 'yes',
563 'touchscreen': 'yes',
564 'keyboard': 'no',
565 'xserver': 'yes',
566 'xserver_choice': 'xserver-i915',
567 'features': ['goodfeature', 'greatfeature'],
568 'tunefile': 'tune-quark',
569}
570