1DDISKIT(1) General Commands Manual DDISKIT(1)
2
6 ddiskit - Red Hat tool for Driver Update Disk creation
7
9 ddiskit [-h] [-vvv] [-qQ] [-p PROFILE] [-R RES_DIR] [-T TEMPLATE_DIR]
10 [-P PROFILE_DIR] [-d] [-o DUMP_CONFIG_NAME] [-C KEY=VALUE]...
11 ACTION [ACTION_OPTIONS]...
12
14 ddiskit (pronounced dee-dis-kit) aids and simplifies the creation of
15 (back-ported) out-of-tree kernel module RPMs and Driver Update Disks
16 containing them. These RPMs and DUDs are deemed suitable for using
17 with distributions based on Red Hat Enterprise Linux. This version of
18 ddiskit supports RHEL 7 and backward-compatible with RHEL 6.
19 ddiskit assumes some workflow which is described in the USAGE EXAMPLE
21 section. It is tailored to the process used for developing and releas‐
22 ing Driver Update Disks, and, while it can be used for creating driver
23 packages for RHEL-based distributions in general, it also worth consid‐
24 ering other tools for the similar purpose, like dkms(8) or akmods(1).
25
28 Please refer to the Configuration generation section for the descrip‐
29 tion of "configuration option name" and "default value" fields, and to
30 the ACTIONS section for the description of the actions mentioned.
31 General options
33 -h, --help
34 Print a list of options. ddiskit will exit after this action,
35 ignoring the remainder of the command line.
36 -v, --verbosity
38 Increase output verbosity by 1. Value of 1 means verbose output
39 (it toggles printing of most of executed commands and all warn‐
40 ings), and value of 2 is useful for debugging (it enables print‐
41 ing of all the executed commands output, actions, and messages).
42 Value of 3 further increases output verbosity of issued rpm(1)
43 commands.
44 Configuration option name: defaults.verbosity
46 Default value: 0
47 -p PROFILE, --profile PROFILE
49 Configuration profile to use. Please refer to the Configuration
50 generation section for the additional information about pro‐
51 files.
52 Configuration option name: defaults.profile
54 Default value: none; "default" is provided in package configura‐
55 tion
56 -R RES_DIR, --res-dir RES_DIR
58 Resources directory. Used as a base of evaluation for template
59 and profile directory paths.
60 Configuration option name: defaults.res_dir
62 Default value: none; "/usr/share/ddiskit/" is a hard-coded
63 default.
64 -T TEMPLATE_DIR, --template-dir TEMPLATE_DIR,
66 Templates directory, used as a base for searching for spec or
67 module configuration templates. Please refer to the File path
68 evaluation section for the information regarding template file
69 path resolution.
70 Configuration option name: defaults.template_dir
72 Default value: none; "{res_dir}/templates" is a hard-coded
73 default.
74 -P PROFILE_DIR, --profile-dir PROFILE_DIR
76 Profiles directory, used as a base for searching for profiles.
77 Please refer to the File path evaluation section for the infor‐
78 mation regarding profile file path resolution.
79 Configuration option name: defaults.profile_dir
81 Default value: none; "{res_dir}/profiles" is a hard-coded
82 default.
83 -d, --dump-config
85 Dump the derived configuration after performing the action.
86 Configuration option name: defaults.dump_config
88 Default value: False
89 -o DUMP_CONFIG_NAME, --dump-config-name DUMP_CONFIG_NAME
91 Path to the file targeted for the configuration dump.
92 Configuration option name: defaults.dump_config_name
94 Default value: none; "{config}.generated" is a hard-coded
95 default.
96 -q, --quilt-enable
98 Enable quilt support. Please refer to the QUILT INTEGRATION
99 section for the information regarding quilt integration. The
100 option sets defaults.quilt_support configuration option to True.
101 -Q, --quilt-disable
103 Disable quilt support. The option sets defaults.quilt_support
104 configuration option to False.
105 -C KEY=VALUE, --config-option KEY=VALUE
107 Override arbitrary configuration option that have the name KEY
108 with VALUE. The KEY should follow the "{[sec‐
109 tion_name.]key_name}" syntax, and defaults section is assumed in
110 case section_name part is omitted. The argument can be used
111 multiple times in order to override multiple options.
112 Options for prepare_sources action
114 -c CONFIG, --config CONFIG
115 Path to the module configuration file.
116 Configuration option name: defaults.config
118 Default value: "module.config"
119 -t CONFIG_TEMPLATE, --config-template CONFIG_TEMPLATE
121 Configuration file template. Please refer to the File path
122 evaluation section for the information regarding configuration
123 template file path resolution.
124 Configuration option name: defaults.config_template
126 Default value: none; "config" is a hard-coded default.
127 -g GIT_DIRECTORY, --git-dir GIT_DIRECTORY
129 Path to .git directory containing repository from where source
130 files should be checked out.
131 Configuration option name: defaults.git_dir
133 Default value: none
134 -r REVISION, --git-revision REVISION
136 Revision specification at which source files should be checked
137 out from the repository.
138 Configuration option name: defaults.git_revision
140 Default value: "HEAD"
141 -d DIRECTORIES, --git-src-directory DIRECTORIES
143 Whitespace-separated list of paths which should be checked out
144 from the repository.
145 Configuration option name: defaults.git_src_directory
147 Default value: none
148 -M MAJOR, --major MAJOR
150 Major version number of the distribution the package is built
151 for (for example, "7" for RHEL 7.3).
152 Configuration option name: defaults.major
154 Default value: 7
155 -m MINOR, --minor MINOR
157 Minor version number of the distribution the package is built
158 for (for example, "3" for RHEL 7.3).
159 Configuration option name: defaults.minor
161 Default value: 0
162 Options for generate_spec action
164 -c CONFIG, --config CONFIG
165 Path to the module configuration file.
166 Configuration option name: defaults.config
168 Default value: "module.config"
169 -t SPEC_TEMPLATE, --spec-template SPEC_TEMPLATE
171 RPM spec file template. Please refer to the File path evalua‐
172 tion section for the information regarding RPM spec template
173 file path resolution.
174 Configuration option name: defaults.spec_template
176 Default value: none; "spec" is a hard-coded default.
177 Options for build_rpm action
179 -c CONFIG, --config CONFIG
180 Path to the module configuration file.
181 Configuration option name: defaults.config
183 Default value: "module.config"
184 -a, --tar-all
186 Tar all files, including hidden ones (files with names starting
187 with dot). Otherwise, only files with names starting with non-
188 dot character will be added to the source tarball. The option
189 sets the value of the relevant configuration parameter to True.
190 Note that this check is independent from the check controlled by
191 the defaults.tar_strict configuration parameter.
192 Configuration option name: defaults.tar_all
194 Default value: False
195 -e, --tar-strict
197 Tar only expected files. Only the files with names matching the
198 regular expression pattern provided in defaults.src_patterns
199 configuration option will be added to the source tarball. The
200 option sets the value of the relevant configuration parameter to
201 True. Note that this check is independent from the check con‐
202 trolled by the defaults.tar_all configuration parameter.
203 Configuration option name: defaults.tar_strict
205 Default value: False
206 -s, --srpm
208 Force building of source RPM instead of binary one. ddiskit has
209 several heuristics (whether host architecture is among architec‐
210 tures targeted by module, whether RPM build check passes) that
211 detect possibility of binary RPM build and falls back to build‐
212 ing source RPM only in case they indicated that binary RPM build
213 is impossible; however, one can force building of source RPM
214 instead of binary one with this switch. The option sets the
215 value of the relevant configuration parameter to True.
216 Configuration option name: defaults.srpm
218 Default value: False
219 -m, --mock
221 Enable mock(1) usage for building RPM. See the MOCK SUPPORT
222 section for additional information.
223 Configuration option name: defaults.mock
225 Default value: False
226 -r MOCK_CONFIG, --mock-config MOCK_CONFIG
228 Which mock configuration should be used for building RPM.
229 Configuration option name: defaults.mock_config
231 Default value: "default"
232 -l, --mock-offline
234 Whether to pass --offline option to mock.
235 Configuration option name: defaults.mock_offline
237 Default value: False
238 -O MOCK_OPTIONS, --mock-opts MOCK_OPTIONS
240 Additional options that have to be passed to mock invocations.
241 Shell quoting is supported. Overwrites options set by previous
242 -O and/or -A options.
243 Configuration option name: defaults.mock_opts
245 Default value: none
246 -A MOCK_OPTIONS, --mock-opts-append MOCK_OPTIONS
248 Additional options that have to be passed to mock invocations.
249 Shell quoting is supported. Appends options to the options set
250 by previous -O and/or -A options.
251 Configuration option name: defaults.mock_opts
253 Default value: none
254 -g LEVEL, --check-git-src LEVEL
256 Set the level of source code repository authenticity check. See
257 the SOURCE CODE VERIFICATION section for the details.
258 Configuration option name: defaults.check_get_src
260 Default value: 0
261 -G, --generate-spec-on-build
263 Call the generate_spec action at the beginning of the build_rpm
264 action execution. This saves for calling generate_spec action
265 separately each time module configuration or patch list are
266 changed (assuming that spec file does not need manual changes
267 after generation).
268 Configuration option name: defaults.generate_spec_on_build
270 Default value: 0
271 Options for build_iso action
273 -c CONFIG, --config CONFIG
274 Path to the module configuration file.
275 Configuration option name: defaults.config
277 Default value: "module.config"
278 -i ISOFILE, --isofile ISOFILE
280 File name for the output ISO.
281 Configuration option name: defaults.isofile
283 Default value: none; see also build_iso action description sec‐
284 tion.
285 Options for dump_config action
287 -c CONFIG, --config CONFIG
288 Path to the module configuration file.
289 Configuration option name: defaults.config
291 Default value: "module.config"
292 -o DUMP_CONFIG_NAME, --dump-config-name DUMP_CONFIG_NAME
294 Name of the file where to store configuration dump. This is the
295 same option as the -o option in the General options section, and
296 present here only for convenience.
297 Configuration option name: defaults.dump_config_name
299 Default value: none; "{config}.generated" is a hard-coded
300 default.
301 Options for update_kabi action
303 -c CONFIG, --config CONFIG
304 Path to the module configuration file.
305 Configuration option name: defaults.config
307 Default value: "module.config"
308 -g GIT_DIRECTORY, --git-dir GIT_DIRECTORY
310 Path to .git directory containing repository from where source
311 files should be checked out.
312 Configuration option name: defaults.git_dir
314 Default value: none
315 -d KABI_DIRECTORY, --kabi-dest-dir KABI_DIRECTORY
317 Path to kABI symbol information files directory withing kernel
318 source tree that is ought to be updated.
319 Configuration option name: defaults.kabi_dest_dir
321 Default value: none
322 -e, --extract-kmod
324 Extract kmods from RPMs and use their modversion data instead of
325 RPM "Requires" tags. The option sets defaults.kabi_use_rpm_ko
326 configuration option to True.
327 -E, --no-extract-kmod
329 Do not extract kmods from RPM and use data provided in
330 "Requires" tags instead. The option sets
331 defaults.kabi_use_rpm_ko configuration option to False.
332 -o, --overwrite
334 Overwrite existing kABI symbol information files. The option
335 sets defaults.kabi_files_overwrite configuration option to 2.
336 -O, --no-overwrite
338 Do not overwrite existing kABI symbol information files. The
339 option sets defaults.kabi_files_overwrite configuration option
340 to 0.
341 -i, --overwrite-interactive
343 Ask user when a possibility of existing kABI symbol information
344 file overwrite appears. The option sets
345 defaults.kabi_files_overwrite configuration option to 1.
346 -t, --commit
348 Perform create a git commit with the affected kABI symbol files
349 on success. The option sets defaults.kabi_commit configuration
350 option to True.
351 -n, --no-commit
353 Do not perform create a git commit with the affected kABI symbol
354 files on success. The option sets defaults.kabi_commit configu‐
355 ration option to False.
356 -m MESSAGE, --kabi-commit-message MESSAGE
358 Commit message that is supplied for the git commit with the
359 affected kABI symbol files.
360 Configuration option name: defaults.kabi_commit
362 Default value: none
363 -M SYMVERS_PATH, --symvers-path SYMVERS_PATH
365 Path to a relevant kernel's Module.symvers file (for example,
366 "/usr/src/kernels/KERNEL_VERSION.{arch}/Module.symvers", present
367 in the kernel-devel RPM).
368 Configuration option name: defaults.symvers_path
370 Default value: none
371 -w WHITELIST_PATH, --kabi-whitelist WHITELIST_PATH
373 Path to a file containing a list of symbols already white
374 listed, in Module.symvers format.
375 Configuration option name: defaults.kabi_whitelist
377 Default value: none
378 -b, --break-on-errors
380 Abort when a symbol version conflict is discovered. The option
381 sets defaults.kabi_check_symvers_conflicts configuration option
382 to 2.
383 -B, --no-break-on-version-conflicts
385 Continue processing even if a symbol version conflict is discov‐
386 ered. The option sets defaults.kabi_check_symvers_conflicts
387 configuration option to 0.
388 -a, --ask-on-version-conflicts
390 Ask user what to do when a symbol version conflict is discov‐
391 ered. The option sets defaults.kabi_check_symvers_conflicts
392 configuration option to 1.
393
395 Configuration is a sectioned key-value store, with values being strings
396 and interpreted based on the context (see CONFIGURATION VALUES REFER‐
397 ENCE section for the reference) as strings, integers, booleans (see
398 Boolean values section for the details on boolean value derivation), or
399 arrays.
400 Configuration generation
402 In order to construct its configuration, ddiskit gathers configuration
403 options from the multiple sources, then performs some fixed processing.
404 The sources of configuration options are the following:
405 · Hard-coded defaults, present in ddiskit source code. These are
407 mostly for default configuration search paths and for other values
408 which are expected to be defined one way or another. Currently, it
409 contains the following configuration options:
410 · defaults section
412 · res_dir = "/usr/share/ddiskit"
414 · template_dir = "{res_dir}/templates"
416 · profile_dir = "{res_dir}/profiles"
418 · config_template = "config"
420 · quilt_support = True
422 · spec_template = "spec"
424 · src_patterns = "^Kbuild$|^Kconfig$|^Makefile$|^.*.[ch]$"
426 · global section
428 · module_vendor = "ENTER_MODULE_VENDOR"
430 · module_author = "ENTER_MODULE_AUTHOR"
432 · module_author_email = "ENTER_MODULE_AUTHOR_EMAIL"
434 · The "package" configuration. It contains the rest of the configura‐
436 tion option defaults which should be defined for proper operation
437 (like spec file generation). Package configuration is read from the
438 fixed path "/usr/share/ddiskit/ddiskit.config" which is not expected
439 to be modified by user or system administrator (and is usually over‐
440 written by package update).
441 · The "site" configuration. Located in "/etc/ddiskit.config", this
443 file is treated as a configuration file and is subject to possible
444 changes by the system administrator.
445 · The "user" configuration. In case user wants some user-specific
447 changes (like his own default values for global.module_author or
448 global.module_author_email configuration options, as well as default
449 profile), he should place it in ".ddiskitrc" file in his home direc‐
450 tory.
451 · Profile. The profile in use is derived from defaults.profile and
453 default.profile_dir configuration variables (see more in the File
454 path evaluation section on how the path to the profile is evalu‐
455 ated). It contains overrides suitable for a particular use case
456 (for example, the rh-testing profile contains spec file description
457 suffix with a notice that the package provided is a testing pack‐
458 age). Note that the values for aforementioned configuration vari‐
459 ables can be overridden by -p and -P command line arguments.
460 · Module configuration. This file is usually called "module.config"
462 (but can be overridden by -c command line argument) and contains
463 module-specific configuration. It is usually generated from tem‐
464 plate by prepare_sources action and is self-documented in terms of
465 what values user is expected to provide there.
466 · Command-line arguments. They update defaults section of the configu‐
468 ration dictionary, and usually have key name equal to the long
469 option name, with dashes replaced with underscores. Configuration
470 option name for each specific command line option is provided in the
471 OPTIONS section. Unless explicitly specified (with default value
472 being "none"), command line option always updates the configuration
473 option value.
474 These files are applied one after another in aforementioned order, so
476 the "last wins" rule applies. The exception from the rule are command
477 line options, which take precedence at each point of configuration gen‐
478 eration (during the profile path evaluation, for example).
479 The configuration files themselves are sectioned key-value files, syn‐
481 tax of which is described in the related Python module documentation
482 ⟨https://docs.python.org/2/library/configparser.html⟩, except for the
483 interpolation part, which is home-grown and described in the section
484 Configuration value evaluation.
485 Kernel package versioning scheme
487 Red Hat Enterprise Linux follows specific kernel package versioning
488 scheme, and ddiskit employs it in order to generate proper dependencies
489 on the kernel package. As a result, it expects that in places where
490 kernel version is provided, this version follows specific scheme. More
491 specifically, two version schemes are supported:
492 · Y-stream kernel version. This kernel package version is shipped as
494 a part of General Availability release, and has the following for‐
495 mat:
496 kernel_version.kernel_patchlevel.kernel_sublevel-rhel_release.rpm_dist
498 For example, RHEL 7.3 GA kernel has kernel version 3.10.0-514.el7.
500 Consequently, it is expected that kernel_version, kernel_patchlevel,
501 kernel_sublevel, rhel_release are decimal numbers (having no more
502 than 1, 2, 2, and 4 digits, respectively), and rpm_dist part is pro‐
503 vided in the form of "el<number>", where <number> is a 1-digit or
504 2-digit number not less than 6.
505 · Z-stream kernel version. These kernel packages are provided as a
507 part of updates for the existing release (so-called Z-stream). The
508 versions of these packages have the following format:
509 kernel_version.kernel_patchlevel.kernel_sublevel-rhel_release[.update_release]+.rpm_dist
511 The restrictions on the parts that also used for the Y-stream kernel
513 package version description are the same, and update_release is a
514 number that can have up to 3 digits. Example of a Z-stream kernel
515 package version (RHEL 7.3 update from 2017-05-25):
516 3.10.0-514.21.1.el7.
517 Generally, it is expected that kernel module RPMs and Driver Update
519 Disks are built for using along with the Y-stream GA kernel (and all
520 the following Z-stream kernels, thanks to kABI compatibility), so when
521 Z-stream kernel package version is detected, the user is warned about
522 this. The differences between kernel package dependency generation in
523 these cases are described in the Spec file generation section.
524 In order to enforce these checks, ddiskit uses regular expression-based
526 approach: it checks the version provided in the defaults.kernel_version
527 configuration variable against regular expressions set via the
528 defaults.kernel_flex_version_re and defaults.kernel_fixed_version_re
529 configuration options, which contain Python regular expressions (see
530 Python re module documentation
531 ⟨https://docs.python.org/2/library/re.html⟩ for details about regular
532 expression syntax) for matching Y-stream and Z-stream kernel versioning
533 scheme, respectively. In order to extract parts of kernel version
534 described above, the following regular expression groups are used:
535 version Kernel's major version (kernel_version in the
537 description above).
538 patchlevel Kernel's patch level (kernel_patchlevel).
539 sublevel Kernel's sub-patch level (kernel_sublevel).
540 rpm_release Major part of RPM release (rhel_release).
541 rpm_release_add Remaining part of RPM release (update_release).
542 rpm_dist RPM release dist part (rpm_dist).
543 The default values of the defaults.kernel_flex_version_re and
545 defaults.kernel_fixed_version_re configuration options are set via
546 other configuration options:
547 kernel_flex_verson_re = {kernel_nvr_re}{kernel_dist_re}
549 kernel_fixed_version_re = {kernel_nvr_re}{kernel_fixed_re}{kernel_dist_re}
550 kernel_nvr_re = (?P<version>[0-9]).(?P<patchlevel>[0-9]{1,2}).(?P<sublevel>[0-9]{1,2})-(?P<rpm_release>[0-9]{1,4})
552 kernel_fixed_re = (?P<rpm_release_add>(.[0-9]{1,3})+)
553 kernel_dist_re = (?P<rpm_dist>.el([6-9]|[1-9][0-9]))
554 This allows for some flexibility in case some tuning of these checks is
556 needed.
557 Configuration check
559 After the configuration has been constructed (and in case module con‐
560 figuration is present), it is subject to a set of checks:
561 · Whether global and spec_file configuration sections are present.
563 · Whether all configuration options in global and spec_file sections
565 have non-default values. Default value is a value which is the con‐
566 catenation of "ENTER_" and upper-cased configuration key name
567 ("ENTER_MODULE_NAME" for spec_file.module_name configuration option,
568 for example). The exception is spec_file.firmware_version option, in
569 case spec_file.firmware_include configuration options is set to
570 False.
571 · Whether spec_file.kernel_version has proper format (only Y-stream
573 and Z-stream kernel versions are accepted, see the Kernel package
574 versioning scheme section for the acceptable version string format
575 configuration details).
576 · Whether spec_file.module_name, spec_flie.module_version, and
578 spec_file.module_rpm_release configuration options contain only
579 characters accepted by RPM (alphanumeric plus '.', '-', '_', '+',
580 '%', '{', '}' for spec_file.module_name; alphanumeric plus '.', '_',
581 '+', '%', '{', '}', '~' for spec_flie.module_version and
582 spec_file.module_rpm_release).
583 File path evaluation
585 Paths to various external resource files (like templates and profiles)
586 are evaluated based on provided resource directory and name using the
587 following algorithm:
588 · If resource name does not have slashes, then it is considered that
590 this name refers to the file in the provided directory.
591 · Otherwise, it is interpreted as a path relative to the current work‐
593 ing directory (which is the directory the where module configuration
594 resides).
595 For example, profile "my-profile" is searched relative to profile
597 directory (stored in the defaults.profile_dir configuration option,
598 "/usr/share/ddiskit/profiles" by default), but profile "./my-profile"
599 is searched relative to module's configuration directory.
600 Configuration value evaluation
602 Configuration option values can reference other configuration options
603 using the "{[section_name.]key_name}" syntax. If section is not
604 present, it is assumed that the referenced key is in the same section
605 as the value which references it. If the referenced key is not found,
606 no substitution occurs.
607 For example, let's assume the following configuration file:
609 [foo]
611 foo = aaa {bar} {bar.baz}
612 bar = bbb {baz} {bar.foo}
613 [bar]
615 foo = ccc {baz}
616 bar = ddd {foo.foo}
617 baz = eee
618 After the evaluation, foo.foo key would have the value "aaa bbb {baz}
620 ddd ccc eee eee", foo.bar would equal to "bbb {baz} ccc eee", bar.foo
621 would be "ccc eee", and bar.bar is "ddd ccc eee".
622 Circular dependencies are not explicitly resolved, there's only substi‐
624 tution depth limit present (which is set to 8 currently).
625 Boolean values
627 The values which are treated as boolean can have the following (case-
628 insensitive) values in order to indicate that the value should be eval‐
629 uated to True: 1, t, y, true, or yes. In order to indicate False
630 value, one of the following strings may be used: 0, f, n, false, or no.
631 In case configuration value doesn't evaluate to True or False value, it
632 is evaluated as None. None value is treated as False in most places,
633 but sometimes it is important to provide specific choice, and in these
634 cases error would occur if boolean value was evaluated to None.
635 Spec file generation
637 Before spec file generation takes place, additional configuration pro‐
638 cessing is performed:
639 · spec_file.source_patches and spec_file.source_patches_do generated
641 in accordance with a lexicographically sorted list of patch files
642 found in the patch directory: src/patch relative to the current
643 working directory (except when quilt(1) integration is enabled; see
644 the QUILT INTEGRATION section for details).
645 spec_file.source_patches contains lines in the "PatchN: patch-file-
646 name" format, and spec_file.source_patches_do contains lines in the
647 "%patchN -p1" format. As a result, first configuration variable is
648 suitable for patch file list description, and second is useful in
649 the %prep section for patch applying. If the default.quilt_support
650 configuration option is enabled, file named series is ignored in the
651 patch directory.
652 · spec_file.firmware_files configuration variable contains list of
654 files found in the src/firmware directory with the /lib/firmware/
655 directory prepended, which is suitable for the %files section of the
656 firmware sub-package.
657 · spec_file.firmware_files_install configuration variable contains
659 list for firmware file installation commands in the format "install
660 -m 644 -D source/firmware/firmware-file-path
661 $RPM_BUILD_ROOT/lib/firmware/firmware-file-path", which is suitable
662 for the %install section of the firmware sub-package.
663 · spec_file.firmware_begin configuration option is set to "%if 1" or
665 "%if 0" when the spec_file.firmware_include configuration variable
666 is true or not, respectively.
667 · spec_file.firmware_end configuration variable is set to "%endif".
669 · spec_file.date is set to the current date and time in "%a %b %d %Y"
671 strftime(3) format, if this variable hasn't been set already.
672 · spec_file.kernel_requires is formatted as following (if the variable
674 hasn't been set already):
675 · if the spec_file.kernel_version_min configuration option contains
677 a non-empty value, it is set to
678 Requires: kernel >= spec_file.kernel_version_min
680 · otherwise, if the spec_file.kernel_version_dep configuration
683 option contains a non-empty value, it is set to
684 Requires: kernel = spec_file.kernel_version_dep
686 · otherwise, it is set to
689 Requires: kernel >= kernel_version-kernel_release.kernel_dist
691 Requires: kernel < kernel_version-(kernel_release + 1).kernel_dist
692 if the spec_file.kernel_version configuration option contains a
694 Y-stream kernel version, or
695 Requires: kernel = kernel_version-kernel_release.kernel_dist
697 if the spec_file.kernel_version configuration option contains a
699 Z-stream kernel version (please refer to the Kernel package ver‐
700 sioning scheme section for the additional details regarding Y-
701 stream and Z-stream versions).
702 If spec_file.kernel_version configuration option is not set and mock
704 support is enabled, its value is defaulted to the latest version of
705 the kernel-devel package available in the mock environment.
706 · spec_file.module_requires is set to spec_file.dependencies value
708 with the "Requires: " string prepended, if the variable hasn't been
709 set already. Note that this special configuration variable is dep‐
710 recated, present only for the backward compatibility, and this spe‐
711 cial value generation may be removed in the future.
712 After this configuration processing, parts of the spec template in the
714 "%{[section_name.]key_name}" format (note the presence of percent sign
715 in comparison to the syntax used for configuration option substitution)
716 are replaced with evaluated configuration values. If no appropriate
717 configuration has been found, no replacement occurs. If configuration
718 option evaluates to empty string, %{nil} is inserted into the resulting
719 spec file.
720
722 prepare_sources
723 Prepare initial file and directory structure. This action creates
724 directories where various files are expected to be placed and creates
725 (into a file set in --config option) module configuration from the tem‐
726 plate file (which path is determined by the defaults.template_dir and
727 defaults.config_template configuration variables; please refer to the
728 File path evaluation section for the module configuration template path
729 derivation process). The action creates the following directory hier‐
730 archy:
731 · rpm - directory for storing rpmbuild(1) artifacts.
733 · BUILD - build directory, used by rpmbuild(1).
735 · BUILDROOT - RPM build root.
737 · RPMS - directory where resulting binary RPMs are stored.
739 · SOURCES - directory where source tarball and patches are stored.
741 · SPECS - directory where generated spec file is placed.
743 · SRPMS - directory where resulting source RPM is stored.
745 · src - directory where module sources are expected to be placed.
747 There are not explicit constrains on the kernel module source file
748 layout, but it is expected that the main make file is placed in a
749 directory provided in the spec_file.module_build_dir configuration
750 variable.
751 · patches - directory with patches that should be applied to the
753 source.
754 · firmware - firmware files.
756 Additionally, if the defaults.git_src_directory configuration option
758 (which, in turn, defaults to the value of the spec_file.mod‐
759 ule_build_dir configuration option, provided the latter is non-empty)
760 is set, source files placed inside directories listed in this white‐
761 space-separated list checked out (inside the src directory) from the
762 repository pointed by the defaults.git_dir configuration option at the
763 revision which specification is set in the defaults.git_revision con‐
764 figuration option (the actual revision to checkout is the output of
765 git rev-parse(1) command invocation with the aforementioned specifica‐
766 tion supplied to it).
767 Before configuration template is processed, the following configuration
769 options are also set:
770 · spec_file.module_build_dir - set to the value of first element of
772 whitespace-separated list stored in the defaults.git_src_directory
773 configuration option, or to "ENTER_MODULE_BUILD_DIR", if it is
774 empty.
775 · spec_file.git_hash - set to the value returned by get rev-parse(1)
777 call with defaults.git_revision revision specification supplied.
778 generate_spec
780 Generate spec file from the spec template (which path is determined by
781 the defaults.template_dir and defaults.spec_template configuration
782 variables; please refer to the File path evaluation section for spec
783 template path derivation process) using process described in Spec file
784 generation section. As a result of the execution of this action, the
785 "rpm/SPECS/{spec_file.module_name}.spec" file is generated. During the
786 generation process, the presence of kernel headers for the target ker‐
787 nel version and architectures is also checked, and warning message is
788 printed in case some of them are not present; this check doesn't affect
789 spec file generation process, however.
790 build_rpm
792 The RPM build action includes several steps:
793 · Check for the module configuration file presence (provided in
795 defaults.config configuration variable via the --config command line
796 option). Since some configuration values should be derived directly
797 from it, its absence makes the whole operation senseless, thus the
798 early bailout.
799 · Generate (if the defaults.generate_spec_on_build configuration
801 option is set to True) or check (if the defaults.check_spec_on_build
802 configuration option is set to positive value) spec file. Depending
803 on the check level provided in the defaults.check_spec_on build con‐
804 figuration option, the latter check may lead to warning or to the
805 termination of the action:
806 0 Do not perform the spec file check.
808 1 Perform spec file comparison and issue warning in case generated
810 and existing spec files differ.
811 2 Perform spec file comparison and issue warning in case generated
813 and existing spec files differ, user is asked whether he wants to
814 continue.
815 3 Perform spec file comparison and abort action execution in case
817 of any errors (during spec file generation or comparison).
818 No spec file comparison is performed (regardless of the
820 defaults.check_spec_on_build configuration option value) if spec
821 file generation is enabled (obviously).
822 · Check for Makefile presence. Presence of file named Makefile some‐
824 where in the source tree allows for passing this check. Absence of
825 Makefile leads to early termination with a relevant exit code
826 (please refer to the EXIT STATUS section for details).
827 · In case quilt integration (specified via the configuration option
829 default.quilt_support) is enabled, quilt patches are de-applied.
830 · Source tarball creation. Tar file named "rpm/SOURCES/{spec_file.mod‐
832 ule_name}-{global.module_vendor}-{spec_file.module_version}.tar.bz2"
833 is created, and files present in the src directory added to it, with
834 the following exceptions:
835 · patches subdirectory is skipped.
837 · All RPM files present in the top level of the src directory are
839 skipped.
840 · Files present in the firmware source subdirectory are skipped in
842 case boolean configuration option spec_file.firmware_include is
843 set to False. In case there are files present in this directory,
844 warning message is displayed regarding the matter.
845 · Hidden files (files beginning with dot) are skipped, unless the
847 defaults.tar_all configuration option (controlled via the --tar-
848 all action-specific command line option) is set to True.
849 · Only files matching the pattern set in the defaults.src_patterns
851 configuration option are added, if the defaults.tar_strict con‐
852 figuration option (controlled via the --tar-strict action-spe‐
853 cific command line option) is set to True. The default pattern
854 includes only *.c, *.h, Makefile, Kbuild, and Kconfig files,
855 which should be suitable for the most cases.
856 · All files from the src/patches directory are copied to the
858 rpm/SOURCES directory.
859 · If current host architecture is among architectures provided in the
861 spec_file.kernel_arch architectures, rpmbuild check (rpmbuild -bc
862 --nobuild) succeeded, and the defaults.srpm configuration option
863 (controlled via the --srpm action-specific command line option) is
864 not enabled, an attempt to build binary RPM is performed. Other‐
865 wise, a source RPM is built.
866 · In case quilt integration (specified via the configuration option
868 default.quilt_support) is enabled, quilt patches are applied back.
869 build_iso
871 This action takes list of files and directories that should be placed
872 on the Driver Update Disk as a non-option arguments. It performs the
873 following steps:
874 · Iterate over the files provided in arguments (recursively descending
876 into directories) and add to the list of candidate files which sat‐
877 isfy the following criteria:
878 · file name ends with ".rpm",
880 · rpmquery(1) successfully retrieves information regarding RPM
882 architecture from the package,
883 · RPM is a binary package or RPM is a source package and the
885 global.include_srpm configuration option is enabled,
886 · RPM is not a debug information package (RPM has group other than
888 "Development/Debug"),
889 · RPM has a valid GPG signature (if case GPG signature check is
891 enabled; see RPM SIGNATURE VERIFICATION section for the addi‐
892 tional information).
893 · All satisfying candidates then copied in a temporary directory.
895 Source RPMs are placed in src subdirectory in the disk hierarchy,
896 and binary RPMs are placed in rpms/arch subdirectory, where arch is
897 the architecture of the binary RPM (with all variants of i386, ...,
898 i686 RPM architecture placed in the i386 subdirectory).
899 · RPM repository metadata is generated (using the createrepo(1) com‐
901 mand) in each of the aforementioned binary RPM directories.
902 · rhdd3 file containing Driver Update Disk signature is created in the
904 temporary directory.
905 · ISO image is created with the mkisofs(1) command. The name of the
907 ISO is provided in the defaults.isofile option (which can be set via
908 the --isofile action-specific command line option). In case no
909 explicit ISO file name is provided, it is generated as
910 "dd-{spec_file.module_name}-{spec_file.module_ver‐
911 sion}-{spec_file.module_rpm_release}.{spec_file.rpm_dist}.iso", or,
912 in case one of values of these configuration options is not a
913 string, simply "dd.iso".
914 dump_config
916 Dumps configuration dictionary as it has been evaluated by a process
917 described in the Configuration generation section. Output file for the
918 dump is set in the defaults.dump_config_name option.
919 update_kabi
921 Generate files with kABI symbol information in the Red Hat Enterprise
922 Linux kernel git repository and optionally commit the changes. The
923 action processes kmods and RPMs provided in the positional arguments,
924 collecting versions (checksums) of symbols present in module informa‐
925 tion sections and/or "Requires" RPM tags, and adds to the git reposi‐
926 tory files corresponding to symbols not yet added into it. The process
927 is controlled via the following configuration options:
928 defaults.kabi_use_rpm_ko
930 Whether to process kmod files inside the provided RPMs instead
931 of RPM files themselves.
932 defaults.symvers_symbol_re (string)
934 Regular expression used for parsing lines in symvers files.
935 Expected to contain ver, symbol, file, and export groups.
936 defaults.kabi_files_overwrite (int)
938 Whether to overwrite kABI files if the files with the same name
939 already exist. Can take the following values:
940 0 Do not overwrite existing kABI files.
942 1 Ask user on each possible overwrite.
943 2 Overwrite existing kABI files.
944 defaults.kabi_check_symvers_conflicts (int)
946 Whether to abort the action when a symbol version conflict
947 (between newly added symbol and Module.symvers or kABI white
948 list) is detected. Can take the following values:
949 0 Continue processing.
951 1 Ask user on each occesion.
952 2 Abort the action.
953 defaults.kabi_commit (bool)
955 Whether to commit the changes at the end of the successful kABI
956 files update.
957 defaults.symvers_path (string) [1]
959 Path to the kernel's Module.symvers file.
960 defaults.kabi_whitelist (string) [1]
962 Path to the kABI white list (in Module.symvers format).
963 defaults.git_dir (string)
965 Path to the kernel's git repository.
966 defaults.kabi_dest_dir (string) [2]
968 Path in the kernel's repository to the directory with kABI sym‐
969 bol files.
970 defaults.kabi_file_name_pattern (string) [2]
972 Name of a kABI symbol file.
973 defaults.kabi_file_template (string) [2]
975 Contents template of a kABI symbol file.
976 defaults.kabi_commit_log_template (string) [2]
978 Template of a line in the commit log regarding specific kABI
979 symbol file.
980 defaults.kabi_commit_message (string) [2]
982 Commit message used for the git commit, if defaults.kabi_commit
983 configuration option is enabled.
984 Notes:
986 [1] The arch variable is overridden with with architecture of the kmod
988 currently being processed ("x86_64" or "ppc64le", for example).
989 [2] There are multiple overrides take place during evaluation of the
991 values:
992 sym Symbol being processed.
994 arch Architecture of the kmod being processed.
995 ver Version (checksum) of the symbol being processed.
996 kmod_file File name of the kmod being processed.
997 kernel_file Path to the file inside the kernel tree that con‐
998 tains the definition of the symbol being processed.
999 kernel_export Type of the export ("EXPORT_SYMBOL", for example).
1000 As of now, the rh-release profile contains some useful default values
1002 for the aforementioned configuration options.
1003
1005 ddiskit supports quilt(1) patch workflow. Specifically:
1006 · It de-applies quilt patches before building source tarball and
1008 applies them back after the build.
1009 · It uses contents of the series file in the patches directory as the
1011 source of the list of patches during the generate_spec action, as
1012 well as during the tarball creation in the build_rpm action. The
1013 file itself is excluded from the list of files considered as
1014 patches.
1015 · It ignores hidden files during the tarball creation in the build_rpm
1017 action which avoids inclusion of the .pc directory.
1018 This behaviour (except the last part that is controlled by the
1020 defaults.tar_all configuration option) is controlled by the
1021 defaults.quilt_support configuration option, which is accessible via
1022 the --quilt-enable and --quilt-disable command line options.
1023
1025 ddiskit supports using mock(1) for building RPM. This support is acti‐
1026 vated via the defaults.mock configuration option which is controlled
1027 via the --mock action-specific command line option. When mock support
1028 is enabled, the following changes apply:
1029 · mock(1) is called instead of rpmbuild for source and binary RPM cre‐
1031 ation. Specifically, mock --buildsrpm is called for source RPM cre‐
1032 ation and pair of mock --buildsrpm and mock --rebuild is used to
1033 build binary RPM out of source RPM which is created inside mock
1034 environment.
1035 · No build check (rpmbuild -bc --nobuild) is performed in order to
1037 check whether it is possible to build binary RPM, it is assumed that
1038 mock can handle it.
1039
1041 As a part of the RPM build process (build_rpm action), source code can
1042 be checked for the correspondence with the git repository from which
1043 the code supposedly originates. It is assumed that the sources are
1044 located in the subdirectory provided in the spec_file.module_build_dir
1045 configuration option as of the commit whose ID is provided in the
1046 spec_file.git_hash configuration option. The check is performed via
1047 the git-diff(1) command. The path to the .git directory containing the
1048 git repository against which module's source code should be checked has
1049 to be provided in the defaults.git_repo configuration option. The
1050 necessity of the check itself, as well as its crucialness is specified
1051 via the default.check_git_src configuration option, with the following
1052 meaning of its value:
1053 0 The check is skipped.
1055 1 The check is performed and the warning is issued if the sources dif‐
1057 fer from the ones present in the repository.
1058 2 The check is performed and the build process is aborted in case of
1060 sources discrepancy or other issues during the check.
1061 The source code verification is performed when quilt patches are
1063 already de-applied.
1064
1066 As a part of ISO build process (build_iso action), included RPMs can be
1067 checked for the presence and correctness of their GPG signature. The
1068 necessity of check is controlled via the rpm_gpg_check.check_level con‐
1069 figuration option, which can have one of the following values:
1070 0 The check is skipped.
1072 1 The check is performed and the warning is issued for each RPM that
1074 failed it.
1075 2 The check is performed and RPMs that didn't pass the check are
1077 skipped.
1078 3 The check is performed and ISO creation is aborted if one of RPMs
1080 failed the check.
1081 The boolean configuration option rpm_gpg_check.use_keyring controls
1083 whether specific keyring directory containing specific set of keys
1084 should be used or just GPG keys present in host's RPM DB. In case
1085 usage of keyring directory is enabled, configuration option
1086 rpm_gpg_check.keyring_dir points to the directory containing public GPG
1087 keys. Note that in order to use these files, their names should end
1088 with ".key" (this is, in fact, RPM's implicit assumption).
1089 This check is enabled by default in rh-release profile and allows veri‐
1091 fying that RPMs added to the release ISO have Red Hat's GPG signature.
1092
1094 1. Create initial directory structure and module configuration.
1095 $ ddiskit prepare_sources
1097 Writing new config file (module.config)... OK
1098 Creating directory structure for RPM build ... OK
1099 Creating directory structure for source code ... OK
1100 Put your module source code in src directory.
1101 2. Copy your code into the src directory:
1104 $ tree src
1106 src
1107 ├── drivers
1108 │ └── net
1109 │ └── ethernet
1110 │ └── broadcom
1111 │ ├── Makefile
1112 │ ├── tg3.c
1113 │ └── tg3.h
1114 └── patches
1115 ├── 0001-test.patch
1116 └── 0002-test.patch
1117 · Please, respect the directory hierarchy for the drivers which are
1120 originally part of the kernel tree.
1121 · Additional patches for the code could be placed in the
1123 src/patches directory.
1124 3. Fill out the module.config and generate the spec file:
1126 $ ddiskit generate_spec
1128 Checking config ...
1129 Config check ... OK
1130 RPM spec file "rpm/SPECS/tg3.spec" exists!
1131 Patches found, adding to the spec file:
1132 Patch0: 0001-test.patch
1133 Patch1: 0002-test.patch
1134 Firmware directory is empty or nonexistent, skipping
1135 Writing spec into rpm/SPECS/tg3.spec ... OK
1136 · The resulting spec file is placed in the rpm/SPEC/ directory, you
1139 can optionally check it out before proceeding.
1140 4. Build binary RPM:
1142 $ ddiskit build_rpm
1144 5. Build Driver Update Disk ISO:
1147 $ ddiskit build_iso
1149
1152 /usr/share/ddiskit.config
1153 Package default configuration.
1154 /etc/ddiskit.config
1156 System-wide ("site") configuration.
1157 ~/.ddiskitrc
1159 User configuration.
1160 module.config
1162 Default configuration name.
1163 /usr/share/ddiskit/templates/spec
1165 Template for RPM spec file generation. Path to it can be over‐
1166 ridden by changing defaults.spec_template configuration option
1167 or defaults.template_dir, please refer to the File path evalua‐
1168 tion section for the additional information.
1169 /usr/share/ddiskit/templates/config
1171 Template for module configuration. Path to it can be overridden
1172 by changing defaults.config_template configuration option or
1173 defaults.template_dir, please refer to the File path evaluation
1174 section for the additional information.
1175 /usr/share/ddiskit/profiles/default
1177 Default profile. Contains configuration options which are use‐
1178 ful in non-specific cases (none, currently). The profile in use
1179 is selected via the defaults.profile configuration option. Path
1180 to profile is configured by the defaults.profile_dir, configura‐
1181 tion option, please refer to the File path evaluation section
1182 for the additional information.
1183 /usr/share/ddiskit/profiles/rh-testing
1185 Profile which contains configuration options used for the test‐
1186 ing DUP RPMs by Red Hat. This includes the disclaimer that the
1187 package is provided for the testing purposes.
1188 /usr/share/ddiskit/profiles/rh-release
1190 Profile which contains configuration options used for the
1191 release DUP RPMs by Red Hat. This includes enablement of vari‐
1192 ous strict checks (such as Git commit ID and RPM GPG signature
1193 verification).
1194
1196 0 successful execution.
1197 1 generic error (no additional information available).
1199 2 problems during command line argument parsing.
1201 3 problems during the configuration check phase (see Configuration
1203 check section for the additional information).
1204 4 problem occurred when tried to de-apply quilt patches (patches
1206 do not de-apply cleanly, for example).
1207 5 problem occurred when tried to apply quilt patches.
1209 6 problem occurred during the sources verification.
1211 7 problem occurred during RPM GPG signature verification.
1213 8 problem occurred during git checkout of source files.
1215 9 problem occurred during spec file comparison.
1217 10 symbol version (checksum) conflict occurred (update_kabi
1219 action).
1220 11 problem occurred during git add invocation (update_kabi action).
1222 12 problem occurred during git commit invocation (update_kabi
1224 action).
1225 32 generic input/output error.
1227 34 error occurred while reading configuration file.
1229 35 error occurred while writing module configuration file (pre‐
1231 pare_sources action).
1232 36 spec template file read error (generate_spec action).
1234 38 spec read error (unused currently).
1236 39 spec write error (generate_spec action).
1238 41 source archive write error (build_rpm action).
1240 42 Makefile not found (build_rpm action).
1242 45 Driver Update Disk signature write error.
1244 47 configuration dump file write error.
1246 49 directory structure creation error.
1248
1250 Problems with ddiskit should be reported to ddiskit project bug tracker
1251 ⟨https://github.com/orosp/ddiskit/issues⟩
1252
1254 The initial version of ddiskit was created by John W. Linville in the
1255 year 2005 for 2.6-based Red Hat Enterprise Linux and Fedora Core dis‐
1256 tributions (like 2.6.9-based RHEL 4). It filled "the same need which
1257 Doug Ledford's Device Driver Update Disk Devel Kit filled for prior
1258 generations of Red Hat distributions" which was used for the Linux
1259 2.4-series based Red Hat distributions around the year 2003. In 2007,
1260 the responsibility for maintaining and enhancing ddiskit was passed to
1261 Jon Masters, who then developed ddiskit during the RHEL 5 and RHEL 6
1262 era. The third incarnation of ddiskit was conceived in 2016 by Petr
1263 Oroš in an attempt to bring more automation to the process of Driver
1264 Update Disk creation along with RHEL 7 support.
1265
1267 rpmbuild(1), dkms(8), akmods(1), mock(1), quilt(1)
1268 Jon Masters. Red Hat Driver Update Packages. Official Reference Guide
1270 ⟨http://people.redhat.com/jcm/el6/dup/docs/dup_book.pdf⟩
1271 ddiskit project repository ⟨https://github.com/orosp/ddiskit/⟩
1273 DDISKIT(1)