.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "KW" 1 "2018-05-18" "" "Kernel Workflow"
.SH NAME
kw \- Inglorious kernel developer workflow tool
.SH SYNOPSIS
.sp
\fIkw\fP \fI<command>\fP [<option> ...]
.SH DESCRIPTION
.sp
\fBkw\fP mission is: 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 \fBkworkflow.config\fP file, as discussed in
section \fI\%ABOUT kworflow.config\fP\&.
.SH COMMANDS
.sp
\fBkw\fP offers several subcommands catering to different audiences and targeting
different functionality groups. Most subcommands have sane defaults.
.SS COMMANDS FOR DEPLOY NEW KERNEL IMAGE AND MODULE
.sp
When we develop for Linux Kernel, we continuously want to install or update the
current version of the Kernel image or modules, and these tasks may require
several steps to be accomplished. For this reason, \fBkw\fP provides a command
named \fBdeploy\fP that attempts to handle all the complexity related to
the new Kernel installation. It is essential to highlight that we try to
support two different types of deploy: \fIlocal\fP and \fIremote\fP\&. When you
want to update your host machine, you can use the \fIlocal\fP option.  Also, we
provide the \fIremote\fP option, which is much more flexible since it uses network;
notice that this approach is the most generic one because you can use it for
\fIvm\fP and \fIlocal\fP\&.
.INDENT 0.0
.INDENT 3.5

.nf
:ref:\(gakw\-deploy<deploy\-doc>\(ga
.fi

.IP "System Message: ERROR/3 (<stdin>:, line 47)"
Unknown interpreted text role \(dqref\(dq.
.UNINDENT
.UNINDENT
.SS COMMANDS FOR WORKING WITH CODE
.sp
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 \fBkw\fP to help with code.
.INDENT 0.0
.INDENT 3.5
.nf

.nf
:ref:\(gakw\-build<build\-doc>\(ga
.fi


.nf
:ref:\(gakw\-codestyle<codestyle\-doc>\(ga
.fi


.nf
:ref:\(gakw\-explore<explore\-doc>\(ga
.fi


.nf
:ref:\(gakw\-maintainers<maintainers\-doc>\(ga
.fi

.fi
.sp
.IP "System Message: ERROR/3 (<stdin>:, line 55)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 56)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 57)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 58)"
Unknown interpreted text role \(dqref\(dq.
.UNINDENT
.UNINDENT
.SS SUBSYSTEM COMMANDS
.sp
Linux kernel has multiple subsystems that expose operations via sysfs or
provide mechanisms for userspace to interact with the driver. For this reason,
kw offers some options that target some specific subsystems for providing
facilities for users to interact with a particular subsystem. Currently, we
only support drm.
.INDENT 0.0
.INDENT 3.5

.nf
:ref:\(gakw\-drm<drm\-doc>\(ga
.fi

.IP "System Message: ERROR/3 (<stdin>:, line 68)"
Unknown interpreted text role \(dqref\(dq.
.UNINDENT
.UNINDENT
.SS COMMAND TO DEBUG THE LINUX KERNEL
.sp
Linux kernel provides multiple mechanisms for debugging; in particular, kw
tries to simplify the debug process for three of them: events, ftrace, and
dmesg. All the debug options are intended to support remote and local targets.
.INDENT 0.0
.INDENT 3.5

.nf
:ref:\(gakw\-debug<debug\-doc>\(ga
.fi

.IP "System Message: ERROR/3 (<stdin>:, line 77)"
Unknown interpreted text role \(dqref\(dq.
.UNINDENT
.UNINDENT
.SS OTHER COMMANDS
.sp
This section describes a tool available in \fBkw\fP to help developers keep track
of configuration files and other features provided by \fBkw\fP that do not fit in
the previous sections.
.INDENT 0.0
.INDENT 3.5
.nf

.nf
:ref:\(gakw\-backup<backup\-doc>\(ga
.fi


.nf
:ref:\(gakw\-init<init\-doc>\(ga
.fi


.nf
:ref:\(gakw\-device<device\-doc>\(ga
.fi


.nf
:ref:\(gakw\-ssh<ssh\-doc>\(ga
.fi


.nf
:ref:\(gakw\-kernel\-config\-manager<kernel\-config\-manager\-doc>\(ga
.fi


.nf
:ref:\(gakw\-vars<vars\-doc>\(ga
.fi


.nf
:ref:\(gakw\-diff<diff\-doc>\(ga
.fi


.nf
:ref:\(gakw\-report<report\-doc>\(ga
.fi


.nf
:ref:\(gakw\-pomodoro<pomodoro\-doc>\(ga
.fi


.nf
:ref:\(gakw\-mail<mail\-doc>\(ga
.fi


.nf
:ref:\(gakw\-self\-update<self\-update\-doc>\(ga
.fi

.fi
.sp
.IP "System Message: ERROR/3 (<stdin>:, line 85)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 86)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 87)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 88)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 89)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 90)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 91)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 92)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 93)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 94)"
Unknown interpreted text role \(dqref\(dq.
.IP "System Message: ERROR/3 (<stdin>:, line 95)"
Unknown interpreted text role \(dqref\(dq.
.UNINDENT
.UNINDENT
.SS clear\-cache
.sp
Clean all files generated by kw.
.SS h, help
.sp
Show basic help.
.SS version, \-\-version, \-v
.sp
Show kworkflow version.
.SH ABOUT KWORFLOW.CONFIG
.sp
\fBkw\fP reads its configuration from two files: the global
\fI<path>/etc/kworkflow.config\fP file and the local \fBkworkflow.config\fP file
present at the current working directory. The global \fBkworkflow.config\fP is a
part of the \fBkw\fP code and provides the overall behavior for \fBkw\fP\&. Local
\fBkworkflow.config\fP settings override global ones; you may have one
\fBkworkflow.config\fP per project. In this section, we describe the possible
fields you can specify in the configuration files.
.SS ssh_user=<user>
.sp
Sets the user to be used by ssh. By default \fBkw\fP uses \fBroot\fP\&.
.SS ssh_ip=<ip>
.sp
Sets the IP address to be used by ssh. By default \fBkw\fP uses \fBlocalhost\fP\&.
.SS ssh_port=<port>
.sp
Sets the ssh port. By default \fBkw\fP uses \fB2222\fP\&.
.SS ssh_configfile=<ssh\-config\-file>
.sp
Provides an optional SSH configuration file to be used by ssh. For more details
see \fBman ssh_config\fP\&.
.SS hostname=<hostname>
.sp
Sets the hostname to be used when an SSH configuration file is provided.
.SS arch=<architecture>
.sp
Allows you to specify the default architecture used by \fBkw\fP\&. By default,
\fBkw\fP uses \fBx86_64\fP\&.
.SS kernel_img_name=<kernel\-image\-name>
.sp
Use this option as a way to indicate to kw the kernel image name. This is the
file present in the directory \fBarch/*/boot/\fP; keep in mind that the kernel
image name might change based on the user config file or target architecture.
.SS cross_compile=<cross\-compile\-toolchain\-name>
.sp
Kw supports cross compile setup, use this option to indicate the target
toolchain.
.SS menu_config=<menu\-option>
.sp
Default kernel menu used by \fBkw\fP, the default is \fBnconfig\fP\&.
.SS alert=[vs | s | v | n]
.sp
Default alert options, you have:
.INDENT 0.0
.IP 1. 3
v: enables visual notification.
.IP 2. 3
s: enables sound notification.
.IP 3. 3
vs or sv: enables both.
.IP 4. 3
n (or any other option): disables notifications.
.UNINDENT
.SS sound_alert_command=<command>
.sp
Command to run for sound completion alert. By default, \fBkw\fP uses
\fBpaplay INSTALLPATH/sounds/complete.wav &\fP
.SS visual_alert_command=<command>
.sp
Command to run for visual completion alert. By default, \fBkw\fP uses
\fBnotify\-send \-i checkbox \-t 10000 \(dqkw\(dq \(dqCommand: \e\e\(dq$COMMAND\e\e\(dq completed!\(dq\fP
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
You may use the \fICOMMAND\fP variable, which will be replaced by the kw command
whose conclusion the user wished to be alerted of.
.UNINDENT
.UNINDENT
.SS default_deploy_target
.sp
By default, \fBkw\fP deploys in the \fIremote\fP; however, you can change this
behavior with this variable. The available options are: \fIlocal\fP and \fIremote\fP\&.
.SS reboot_remote_by_default
.sp
Reboot machine after the deploy finishes.
.SS gui_on=<command>
.sp
This option is disabled by default, if enabled, it requires a command that
instructs kw to turn on the GUI.
.SS gui_off=<command>
.sp
This option is disabled by default, if enabled, it requires a command that
instructs kw to turn off the GUI.
.SH EXAMPLES
.sp
For these examples, we suppose the fields in your \fBkworkflow.config\fP file is
already configured.
.sp
First, if you are working in a specific kernel module, and if you want to
install your recent changes in your local machine you can use:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd <kernel\-path>
kw d \-\-local \-\-modules
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For building and installing a new module version based on the current kernel
version, you can use:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd <kernel\-path>
kw bd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For checking the code style:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd <kernel\-path>
kw c drivers/iio/dummy/
kw c drivers/iio/dummy/iio_simple_dummy.c
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you want to check the maintainers:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd <kernel\-path>
kw m drivers/iio/dummy/iio_simple_dummy.c
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In case you want that kw saves your current .config file, you can use:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd <kernel\-path>
kw k \-\-save my_current_config
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can see the config\(aqs file maintained by kw with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kw k \-\-list
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can turn on your VM with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kw u
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After you start your VM you can ssh into it with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kw s \-c=\(dqdmesg \-wH\(dq
kw s
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can see data related to your kw usage by using the \fB\-\-statistics\fP flag on
the report option, see some examples below:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kw report \-\-statistics \-\-day
kw report \-\-statistics \-\-week
kw report \-\-statistics \-\-month
kw report \-\-statistics \-\-year
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can also request a specific day, week, month, or year. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kw report \-\-statistics \-\-day=2020/05/12
kw report \-\-statistics \-\-week=2020/02/29
kw report \-\-statistics \-\-month=2020/04
kw report \-\-statistics \-\-year=1984
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you are working with DRM drivers, you can take advantage of load and unload
commands combined with GUI control commands. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kw drm \-\-load\-module=\(aqamdgpu\(aq \-\-gui\-on # Load a driver and trigger the user GUI
kw drm \-\-unload\-module=\(aqamdgpu\(aq # Turn off user GUI and unload the driver
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you need to debug an issue based on event values, you can try the debug
options. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kw debug \-\-list # Show all events debug available in the target
kw debug \-\-list \-\-event=\(dqamdgpu_dm\(dq # Show all events available under amdgpu_dm
kw debug \-\-event=\(aqamdgpu_dm:amdgpu_dm_dce_clocks_state[sclk_khz > 0]\(aq # Enable amdgpu_dm_dce_clocks_state event and filter by sclk_khz > 0
kw debug \-\-disable \-\-event=\(aqamdgpu_dm:amdgpu_dm_dce_clocks_state\(aq # Disable amdgpu_dm_dce_clocks_state events
kw debug \-\-event=\(aqamdgpu_dm:amdgpu_dm_dce_clocks_state\(aq \-\-history # Save each debug in a separated set of files
kw debug \-\-event=\(aqamdgpu_dm:amdgpu_dm_dce_clocks_state\(aq \-\-follow # Wait for new event message
kw debug \-\-event=\(aqamdgpu_dm:amdgpu_dm_dce_clocks_state\(aq \-\-cmd=\(dqexport DISPLAY=:0.0 && xrandr \-\-props\(dq # Enable amdgpu_dm_dce_clocks_state, run \(dqexport DISPLAY=:0.0 && xrandr \-\-props\(dq, collect logs, and disable events
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
You have to wait for the sshd to become ready.
.UNINDENT
.UNINDENT
.SH AUTHOR
Rodrigo Siqueira <rodrigosiqueiramelo@gmail.com>, Matheus Tavares <matheus.bernardino@usp.br>
.SH COPYRIGHT
GPLv2+
.\" Generated by docutils manpage writer.
.