IVI/artem-kernel

From Tizen Wiki
< IVI
Jump to: navigation, search

Summary

The kernel-x86-ivi kernel is the kernel for Tizen IVI profile.

The original author of wiki this page is Artem Bityutskiy <artem.bityutskiy@linux.intel.com>.

Important

Important things to know when working with the Tizen IVI kernel.

  • We accept only patches from upstream (see this section for details).
  • Always Cc the Tizen IVI mailing list when you want to discuss kernel-related matters with the maintainer. I prefer to have publically-visible conversations unless there is a good reason to keep them private.
  • Don't modify the packaging changelog file (packaging/kernel-x86-ivi.changes) please, I'll do this myself when I release the kernel.

Cloning the kernel

Cloning anonymously

To clone the tree only, use:

git clone git://review.tizen.org/profile/ivi/kernel-x86-ivi.git
# The latest Tizen stuff is in branch "tizen"
git checkout -b tizen origin/tizen

I am behind the proxy, and in the global ".$HOME/.gitconfig" git configuration file I have the following:

# Please, substitute "USER" with your tizen.org user name.
# Please, substitute internal.com with your internal domain name where
# you have direct access. Or just remove that line if it is irrelevant
# for you.
[core]
        gitproxy = none for internal.com
        gitproxy = /home/USER/bin/git-proxy-command.sh

And here is my "git-proxy-command.sh" file:

#!/bin/sh

# Please, substitute "proxy.qu-qu.gov" with your proxy URL.
proxy="proxy.qu-qu.gov"
socat STDIO SOCKS4:$proxy:$1:$2

If you have a clone of the upstream kernel tree, it may be a good idea (but optional) to reference it while cloning using the "--reference" option. This option makes git share common object between the local clone of the upstream tree and kernel-x86-ivi. That will save disk space and make cloning much faster.

The gitweb view of the kernel tree is here: https://review.tizen.org/git/?p=profile/ivi/kernel-x86-ivi.git;a=summary

Cloning for later contributions

Getting gerrit access

Create a tizen.org account and request gerrit access before contributing to the kernel via tizen.org gerrit. Open www.tizen.org, click "Register" and follow the instructions to create an account.

To request gerrit access rights: Login to www.tizen.org, click "My account", then open the "Access Requests" tab, and request gerrit access.

Upload SSH keys

Next, upload your SSH key(s) to the tizen.org gerrit server. Sign in to https://review.tizen.org/gerrit, click "settings" at the right top corner, select "SSH Public keys" and add your public key.

Cloning

Once the tizen.org gerrit server has your public SSH key, you are ready to clone the Tizen IVI kernel.

# Please, substitute "USER" with your tizen.org user name.
git clone ssh://user@review.tizen.org:29418/profile/ivi/kernel-x86-ivi

Find more information here.

I have to pass through the SOCKS proxy, and here is my configuration, just for reference.

In the "$HOME/.ssh/config" file I have the following:

# Please, substitute "USER" with your tizen.org user name.
# Please, substitute "proxy.qu-qu.gov" with your proxy URL.
Host review.tizen.org
        Port 29418
        User USER
        ProxyCommand socat STDIO SOCKS4:proxy.qu-qu.gov:%h:%p

And with this, I can clone the IVI kernel like this:

$ git clone review.tizen.org:profile/ivi/kernel-x86-ivi

Submitting patches to kernel-x86-ivi

The upstream story

We generally accept only those kernel patches that are either in Linuses tree or in a subsystem tree (e.g., wireless-next.git, usb.git, sound.git, etc). In the latter case, the patches should be visible in linux-next.git.

Generally you should back-port patches from upstream kernel trees, with the following exceptions:

  • Enable/disable features in the configuration file (ivi_defconfig);
  • Packaging changes (see the packaging/ sub-directory in the Tizen IVI kernel sources);
  • Reverts of existing commits;
  • Simple and urgent fixes.

In any case, you should demonstrate that you or someone else is working with upstream on the issue (e.g., provide an LKML URL).

Always apply common sense and do not hesitate to talk to the maintainer, with a cc the mailing list.

How to back-port properly

First rule of thumb: you must preserve the original author's name.

Do not modify the commit at all, neither the commit message (except the upstream and JIRA references, see below), nor the patch (except some minor amendments which you may have to do to make the patch apply cleanly). You can append your own "Signed-off-by".

Start with something like the following for all the patches you back-port:

git format-patch -1 <commit_id>

Then add the upstream reference to all of the patches. For example, if you back-port from Linuses tree, you can do the same as Greg KH does in his linux-stable tree. For example, in this commit, which was back-ported from commit 78b495c of Linuses tree, Greg added the following note:

commit 78b495c39add820ab66ab897af9bd77a5f2e91f6 upstream

If you are back-porting from a subsystem tree, use the name of the subsystem tree instead of "upstream", as follows:

commit 182f514f883abb5f942c94e61c371c4b406352d4 in ext4.git
(git://git.kernel.org/pub/scm/linux/kernel/git/tytso/ext4.git)

Then specify which JIRA issue the patches fix below the upstream reference. For example:

commit 3064837289259843310b266a9422aca5f5b4b9c7 in bluetooth-next.git
(git://git.kernel.org/pub/scm/linux/kernel/git/bluetooth/bluetooth-next.git)
Fixes TIVI-203.

Use the gerrit review messages or a follow-up e-mail for additional information if you are sending your patch by e-mail instead of using gerrit.

Commit messages

If you submit your own patch, keep in mind best practices for writing commit messages. Use a subject line that indicates which subsystem is involved and what the patch is (a fix, an optimization, a clean-up, etc). Describe all the details in the commit message. Explain the problem and how it is addressed. Also, make sure each patch does just one thing. Split your changes into a patch-set when necessary.

See this short description about good commit message, and this longer one.

Where to submit patches

In Tizen gerrit is used for submitting and reviewing patches. To submit kernel-x86-ivi patches, clone it and push the patches to the "refs/for/tizen" reference.

# Clone the kernel
$ git clone --reference $HOME/git/linux review.tizen.org:profile/ivi/kernel-x86-ivi
$ cd kernel-x86-ivi

# Now apply your patches (test them first). Then
# push them out to gerrit.
$ git push origin HEAD:refs/for/tizen

Once the patches are reviewed in gerrit, they will be merged. The maintainer releases the updated kernel and it reaches the Tizen IVI images later.

Do not change the packaging changelog file (packaging/kernel-x86-ivi.changes) - I will do it for you, based on the commit messages.

If you have issues with gerrit, you may also send your patches to me: the maintainer, with a cc the mailing list.

Kernel configuration

The kernel-x86-ivi configuration is called "ivi_defconfig". This configuration is meant to be optimized for Tizen IVI reference devices. The optimization is around boot time: we are trying to make sure most of the required drivers and kernel features are compiled into the kernel (instead of being kernel modules) because this boots the system faster. Drivers that are not necessarily used when Tizen IVI boots up may be kernel modules.

The other general concept is that we are trying to exclude useless drivers and not compile them at all. This makes the kernel package smaller.

We are also trying to support non-target hardware, like commodity laptops, so we try to make sure the drivers for non-target HW are enabled as kernel modules. If you find that a piece of HW you need has a corresponding kernel driver in the kernel but this driver is disabled, file a JIRA issue and assign it to the kernel maintainer.

We also try to keep track of the drivers requested in the following table.

Kernel drivers and features which were enabled due to a request
Description Configuration option(s)
Various virtio and virtual machine drivers to make Tizen IVI work in virtual machines CONFIG_DRM_VMWGFX, CONFIG_DRM_VMWGFX_FBCON, CONFIG_VIRTIO_BLK, CONFIG_VMWARE_BALLOON, CONFIG_VMWARE_PVSCSI, CONFIG_SCSI_VIRTIO, CONFIG_VIRTIO_NET, CONFIG_VIRTIO_CONSOLE, CONFIG_HW_RANDOM_VIRTIO, CONFIG_VIRTIO_PCI, CONFIG_VIRTIO_BALLOON, CONFIG_VIRTIO_MMIO, CONFIG_VIRTIO_MMIO_CMDLINE_DEVICES, CONFIG_SND_ENS1371

Note: CONFIG_DRM_VMWGFX is currently configured as a built-in module (=y). This is a temporary measure until a proper resolution is in place for TIVI-2790

Support various Logitech devices, e.g., requested by Geoffroy Van Custem to support the G27 Racing wheel CONFIG_HID_LOGITECH, CONFIG_LOGITECH_FF, CONFIG_LOGIG940_FF, CONFIG_LOGIWHEELS_FF, CONFIG_HID_LOGITECH_DJ
The kernel->userspace connector feature, required by Murphy, see TIVI-713 CONFIG_CONNECTOR, CONFIG_PROC_EVENTS
The memory controller cgroup, required by systemd, see TIVI-970 CONFIG_MEMCG
HDMI/DP HDA audio codec, requested by Geoffroy VanCutsem CONFIG_SND_HDA_CODEC_HDMI
A contemporary USB-serial adapter driver, requested by Joonas Lahtinen CONFIG_USB_SERIAL_FTDI_SIO
A contemporary USB-ethernet adapter driver, requested by Joonas Lahtinen CONFIG_USB_NET_SMSC75XX
WIFI tethering with connman, see the connman/README file CONFIG_BRIDGE, CONFIG_NETFILTER, CONFIG_NF_CONNTRACK_IPV4, CONFIG_NF_NAT_IPV4, CONFIG_IP_NF_TARGET_MASQUERADE, CONFIG_IP_MULTIPLE_TABLES, CONFIG_NETFILTER_NETLINK_ACCT, CONFIG_NETFILTER_XT_MATCH_NFACCT
Designware USB driver and various USB gadget drivers. The BayTrail SoC includes a DesignWare USB controller capable of supporting the gadget mode. Although we do not use this mode in Tizen IVI, some people may find it useful to have the drivers available. CONFIG_USB_DWC3, CONFIG_USB_DWC3_GADGET, CONFIG_USB_GADGET, CONFIG_USB_ZERO, CONFIG_USB_ETH, CONFIG_USB_G_NCM, CONFIG_USB_FUNCTIONFS, CONFIG_USB_MASS_STORAGE, CONFIG_USB_G_SERIAL
AT keyboard and PS2 mouse drivers, required for running Tizen IVI in VMWare, see TIVI-2025 CONFIG_KEYBOARD_ATKBD, CONFIG_MOUSE_PS2
PCAN USB driver, needed for testing AMB, see TIVI-2263 CONFIG_CAN_PEAK_USB
TouchScreen support for Lenovo X230, see TIVI-2396 CONFIG_INPUT_TABLET, CONFIG_TABLET_USB_WACOM
SCSI adapter exposed to Virtual Machines by VMware, see TIVI-2676. This must be built-in (and not a module) since you need it to mount the rootfs CONFIG_FUSION=y, CONFIG_FUSION_SPI=y
Enable specific CGROUP features, specifically "Network bandwidth management" (net_cls, net_prio) and "Storage bandwidth management" (blkio) in the kernel, see TIVI-2678. Modules were used where available. CONFIG_BLK_CGROUP=y, CONFIG_BLK_DEV_THROTTLING=y, CONFIG_CFQ_GROUP_IOSCHED=y, CONFIG_NET_SCHED=y, CONFIG_NET_CLS_CGROUP=m, CONFIG_CGROUP_NET_PRIO=m
Support libvirt-lxc in kernel, see TIVI-3217 CONFIG_UTS_NS=y, CONFIG_IPC_NS=y, CONFIG_PID_NS=y, CONFIG_USER_NS=y, CONFIG_NETFILTER_XT_TARGET_CHECKSUM=m, CONFIG_BRIDGE_VLAN_FILTERING=y, CONFIG_VLAN_8021Q=m, CONFIG_VETH=m, CONFIG_DEVPTS_MULTIPLE_INSTANCES=y, CONFIG_CFS_BANDWIDTH=y
Support i801 SMBus device. MAX9867 audio codec is controlled over a SMBus port, so this driver enables userspace to control it by using /dev/i2c dev. See TC-59 CONFIG_I2C_I801=m

Debugging boot issues

Unfortunately, sometimes Tizen IVI systems may not boot to the UI or console, in which case you usually see a black screen or the splash image and no useful information.

The reason for this is that we use the the "quiet" kernel option in Tizen IVI to facilitate a faster boot. This option affects both kernel and systemd startup messages. The first step to fix this is to remove the "quiet" option from the Tizen IVI kernel boot arguments.

For MBR images edit the "/boot/extlinux/extlinux.conf" file. For EFI images edit the "/boot/loader/entries/vmlinuz-<version>.conf" file.

Capturing boot logs via serial line

Usually disabling the "quiet" option is enough to resolve the problem or to understand where it is. Sometimes the problem is in one of the systemd services, not in the kernel. Enable the serial port logging if useful error messages are not shown on the display.

To enable serial port logging add the following options to the Tizen IVI kernel boot arguments: "console=tty0 console=ttyS0,115200 ignore_loglevel". This will make the Tizen IVI kernel send all the kernel output to the serial line. The serial console should be available on a successful boot.

Use the "minicom" program to capture the boot output on the host side (confirm you have minicom configured properly).

Useful tips

How to change the configuration file

Use the following example to change the kernel configuration (for example, to add support for a feature or a driver).

For example, change the ivi_defconfig configuration, found in the "arch/x86/configs" subdirectory, to enable the "PPS" (Pulse Per Second) subsystem (CONFIG_PPS).

$ make ARCH=i386 ivi_defconfig # Configure the kernel
$ make ARCH=i386 menuconfig # or xconfig or gconfig

# Enable the PPS feature, exit the configurator

$ make ARCH=i386 savedefconfig
$ mv defconfig arch/x86/configs/ivi_defconfig
$ git commit -a -s

In general terms, first apply the configuration you need to change (ivi_defconfig), modify it, save it ("savedefconfig), and possibly commit it.

How to fetch files from an RPM

# This will fetch all files from the kernel package and place them
# in the current directory.
$ rpm2cpio kernel-x86-ivi.i686.rpm | cpio -idmv

Git e-mail aliases

It is useful to have aliases for the most frequently used e-mail addresses. They are helpful when dealing with "git send-email". Add something like the following to the ".gitconfig" file:

[sendemail]
        aliasesfile=/home/dedekind/.mutt-aliases
        aliasfiletype=mutt

where the ".mutt-aliases" file contains records like these:

alias lkml           Linux Kernel      <linux-kernel@vger.kernel.org>
alias artem          Artem Bityutskiy  <artem.bityutskiy@linux.intel.com>

When using 'git send-email', specify something like "--to lkml" instead of "--to "linux-kernel@vger.kernel.org"".

How to add a project to the watchlist in tizen.org gerrit

  1. Confirm that you have a tizen.org account and gerrit access rights (see this section).
  2. Open https://review.tizen.org/gerrit and sign in
  3. In the upper right corner click "Settings"
  4. On the left-side menu select "Watched Projects"
  5. In the "Project name" field type "profile/ivi/kernel-x86-ivi" and press "Enter"

How use "git send-email"

When working with upstream send your patches to one of the mailing lists. This is usually done using the "git send-email" command.

Suppose you have a properly formatted patch-set that you created using the "git format-patch" command. You can send your patches upstream using the following command:

$ git send-email --to maintainer@email.org --cc mailing.list@qu-qu.org 0*

You should know where to send the patch to (see this section for more information).

Note: "git send-email" can sometimes send e-mails to people you did not expect. For example, it may send the e-mails to the names found in the "Signed-off-by:" tags. Configure "git send-email" to prevent this. Here is my configuration (from "$HOME/.gitconfig")

[sendemail]
        smtpserver = smtp.intel.com
        signedoffcc = false
        suppresscc = all
        chainreplyto = false
        assume8bitEncoding = utf-8

More tips:

  • always use the "--dry-run" option to check that "git send-email" will do what you want
  • "git send-email" is interactive, so you do not have to specify the recipients at the command line
  • never use chained "In-Reply-To:" ("--chain-reply-to" option) - it is much more difficult to work with in the mailing list

Where in upstream to send my patch to?

Identify the following if you have to upstream your patches:

  1. maintainers' name
  2. the mailing list to send the patch to
  3. the kernel tree to create the patch against

This information is typically found in the "MAINTAINERS" file which is a part of the Linux kernel tree. Check the file, find the subsystem you are going to change, and then send the patch to the subsystem maintainer(s) and cc the subsystem mailing list(s). The "MAINTAINERS" file also typically has the subsystem's git tree URL. Clone the subsystem git tree and make sure your patch applies against this tree. For non-trivial patches make sure it also actually works with this tree.

The "scripts/get_maintainer.pl" script (also part of the kernel tree) can help you find out the names. For example, if you have a patch "hda.patch", run:

$ scripts/get_maintainer.pl --scm hda.patch

or if you change file "sound/pci/hda/hda_intel.c" and want to know where to send the patch, run:

$ scripts/get_maintainer.pl --scm -f sound/pci/hda/hda_intel.c
Jaroslav Kysela <perex@perex.cz> (maintainer:SOUND)
Takashi Iwai <tiwai@suse.de> (maintainer:SOUND,commit_signer:69/69=100%)
Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com> (commit_signer:4/69=6%)
David Henningsson <david.henningsson@canonical.com> (commit_signer:4/69=6%)
alsa-devel@alsa-project.org (moderated list:SOUND)
linux-kernel@vger.kernel.org (open list)
git git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git
git git://git.alsa-project.org/alsa-kernel.git
git git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

From the output you can see that Jaroslav Kysela is the maintainer, as well as Takashi Iwai. Pierre-Louis Bossart signed 6% of commits for this file, just like David Henningsson. The "alsa-devel@alsa-project.org" is the mailing list for the sound subsystem. There is a list of related kernel trees. The top records are usually the most relevant.

Run "scripts/get_maintainer.pl -h" for more details.

In this particular case you should probably clone the "sound.git" tree, make sure the patch can be cleanly applied to this tree using the "git apply --check hda.patch" command, then send the patch to the maintainers and the mailing list using the following command (see this section for more info):

git send-email --from "Your Name <your@email>" --to "Jaroslav Kysela <perex@perex.cz>" --to "Takashi Iwai <tiwai@suse.de>" --cc "alsa-devel@alsa-project.org" --cc "linux-kernel@vger.kernel.org" hda.patch