Provided by: kworkflow_20191112-1_amd64 
NAME
kw - Inglorious kernel developer workflow scripts
SYNOPSIS
kw COMMAND [OPTION ...]
DESCRIPTION
kw is a set of scripts that have a single mission: reduce the overhead related with infrastructure
project setup in projects that have a similar workflow to the Linux Kernel. It can (and should) be
customized by editing the kworkflow.config file, as discussed in section "ABOUT kworflow.config".
COMMANDS
kw offers several subcommands catering to different audiences and targeting different functionality
groups. Most subcommands have sane defaults.
COMMANDS FOR USING QEMU
Projects that use a QEMU VM in the development cycle to host the development environment usually require
that developers use some specific commands to manage this VM. In this section, you can find all commands
available in kw to manage many daily tasks related to QEMU VM operation. Notice that some rules are
specific for the Linux Kernel project.
mo, mount
Mount the QEMU image in a specific directory, based on the data available in the kworkflow.config. Notice
that the configuration file has the information about the source image and destiny mount point.
NOTE:
Only run this command after you turn off your VM.
um, umount
Umount the previously mounted QEMU image.
u, up
Start the QEMU VM based on parameters in the kworkflow.config file.
s, ssh [--script|-s="PATH"]|[--command|-c="COMMAND"]
Ssh into the QEMU VM. The --script parameter expects a bash script as a parameter to evaluate it in the
VM. The --command parameter expects a command to be executed inside the QEMU VM.
i, install
Installs or updates the Linux kernel modules on the QEMU VM. Under the hood, it executes the mount
operation, followed by make modules_install with a specific target, and finally umounts the QEMU image.
NOTE:
Only run this command after you turn off your VM.
p, prepare
(EXPERIMENTAL) Starting from a generic image, prepare sets up the necessary packages, files, etc. inside
the QEMU image so that it is ready for development work. For this to work, you have to:
1. Add your public key in the VM in the authorized_keys file.
2. Remove the requirement for password in the VM to become root.
This command (currently) uses Ansible playbooks.
COMMANDS FOR WORKING WITH CODE
Projects that have a similar workflow to the Linux Kernel usually have a set of tools that simplify part
of the tasks related with the code. This section describes some of the key features supported by kw to
help with code.
b, build
This command calls make on a local Makefile to build the project. It tries to take advantage of your
hardware by using the -j option with the appropriate parameter.
c, codestyle [DIRECTORY|FILE]
The checkpatch tool is one of the most fabulous scripts provided by the Linux Kernel to help developers
follow the code style adopted by the project. This command is a wrapper for checkpatch, with the goal of
simplifying the use of this tool; notice that you can specify a single file or an entire directory.
e, explore [log] [EXPRESSION] [-p] [DIRECTORY|FILE]
The explore command is based on git grep. It can search for string matches in either the git repository
contents or in the git log messages. For example, you can use kw e functionName to find functionName in
the source directory. You can also search the git log history by using log after the e; for instance, kw
e log STRING_MATCH. Additionally, you can use -p to see the diff in the search.
m, maintainers [-a|--authors] [DIRECTORY|FILE]
Based on the Linux Kernel get_maintainers script, this command shows the maintainers of a given Kernel
module (a given file or directory). The [-a|--authors] option will also print the authors of the
top-level target files (non-recursively). Files with more than one author will have their names separated
by ",". This output should not be used by scripts because some authors include "," in their names (e.g.
"Company X, Inc.").
OTHER COMMANDS
This section describes a tool available in kw to help developers keep track of configuration files and
other features provided by kw that do not fit in the previous sections.
g, configm [--save NAME [-d DESCRIPTION][-f]]|[--ls]|[--get NAME [-f]]|[--rm NAME [-f]]
The 'configm' command manages different versions of the project's '.config' file. It provides the save,
load, remove, and list operations of such files.
1. --save NAME [-d DESCRIPTION] [-f]: The save option searches the current directory for a '.config'
file to be kept under the management of kw. The save option expects a name to identify this version of
the file. Additionally, users can add a description by using -d flag. Finally, if the user tries to add
the same name twice, kw will issue a warning; the '-f' will suppress this message.
2. --ls lists all the .config file versions available.
3. --get NAME [-f]: Get a config file based on the NAME and paste it in the current directory. It pop-up
a warning message because this operation override the current .config file. The user can suppress this
warning by using -f flag.
4. --rm NAME [-f]: Remove config labeled with NAME. It pop-up a warning message because it will remove
the config file from kw management. The user can suppress this warning by using -f.
v, vars
Shows configurations being used by kw in the current working directory. To do that, it examines both
global and local kworkflow.config files.
bi
Build and install a new module version. It is a combination of the build and install commands.
alert=[vs|sv,v,s,n]
Some commands take considerable time to execute. kw gives you an option to be notified when they finish.
The commands prepare, build, install, mount, umount, new and bi offer this feature.
1. v enables visual notification.
2. s enables sound notification.
3. vs or sv enables both.
4. n (or any other option) disables notifications (this is the default).
h, help
Show basic help.
ABOUT KWORFLOW.CONFIG
kw reads its configuration from two files: the global PATH/etc/kworkflow.config file and the local
kworkflow.config file present at the current working directory. The global kworkflow.config is a part of
the kw code and provides the overall behavior for kw. Local kworkflow.config settings override global
ones; you may have one kworkflow.config per project. In this section, we describe the possible fields you
can specify in the configuration files.
ssh_ip=IP
Sets the IP address to be used by ssh. By default kw uses localhost.
ssh_port=PORT
Sets the ssh port. By default kw uses 2222.
arch=ARCHITECTURE
Allows you to specify the default architecture used by kw. By default, kw uses x86_64.
virtualizer=VIRTUALIZER
Defines the virtualization tool that should be used by kw. Currently, we only support QEMU and, as a
result, the default is qemu-system-x86_64
mount_point=PATH
Defines the kw mount point, which will be used by libguestfs during the mount/umount operation of a VM.
By default, kw uses /home/$USER/p/mount.
qemu_hw_options=OPTIONS
Sets QEMU options. By default, kw uses -enable-kvm -daemonize -smp 2 -m 1024
qemu_net_options=OPTIONS
Defines the network configuration. By default, kw uses -net nic -net
user,hostfwd=tcp::2222-:22,smb=/home/USER
qemu_path_image=PATH
Specify the VM image path. By default, kw uses /home/USERKW/p/virty.qcow2
alert=[vs|s|v|n]
Default alert options, you have:
1. v: enables visual notification.
2. s enables sound notification.
3. vs or sv enables both.
4. n (or any other option) disables notifications.
sound_alert_command=COMMAND
Command to run for sound completion alert. By default, kw uses paplay INSTALLPATH/sounds/complete.wav &
visual_alert_command=COMMAND
Command to run for visual completion alert. By default, kw uses notify-send -i checkbox -t 10000 "kw"
"Command: \"$COMMAND\" completed!" (Note: You may use COMMAND, which will be replaced by the kw command
whose conclusion the user wished to be alerted.)
EXAMPLE
For these examples, we suppose the fields in your kworkflow.config file is already configured.
First, if you are working in a specific kernel module, and if you want to install your recent changes in
your VM you can use:
cd /KERNEL/PATH
kw i
NOTE:
Turn off your VM before use the intall command.
For building and installing a new module version based on the current kernel version, you can use:
cd /KERNEL/PATH
kw bi
For checking the code style:
cd /KERNEL/PATH
kw c drivers/iio/dummy/
kw c drivers/iio/dummy/iio_simple_dummy.c
If you want to check the maintainers:
cd /KERNEL/PATH
kw m drivers/iio/dummy/iio_simple_dummy.c
In case you want that kw saves your current .config file, you can use:
cd /KERNEL/PATH
kw g --save my_current_config
You can see the config's file maintained by kw with:
kw g --ls
You can turn on your VM with:
kw u
After you start your VM you can ssh into it with:
kw s -c="dmesg -wH"
kw s
NOTE:
You have to wait for the sshd become ready.
AUTHOR
Rodrigo Siqueira <rodrigosiqueiramelo@gmail.com>, Matheus Tavares <matheus.bernardino@usp.br>
COPYRIGHT
GPLv2+
2018-05-18 KW(1)