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)