SUSE Linux Enterprise Patch Policy ================================== Summary ------- The SUSE Linux Enterprise (SLE) patch policy mirrors the mainline Linux community's policy for accepting changes. Each commit must contain a small and "obvious" change that can be reviewed individually and, once applied, be able to be used as a bisection point. The kernel should be able to build and boot between each applied patch. Since the SLE kernel is based on an official upstream kernel release and is followed by a hardening process, we expect that nearly all of the patches applied to the base release will be from subsequent official upstream releases intended to address specific issues or to allow for hardware/feature enablement. Background ---------- Before covering the policy itself, we'll discuss a bit of background on how the source code tree is organized. If you've used the SLE kernel source tree at before, you've probably noticed that, unlike the mainline Linux kernel, we don't use a source-level Git repository as our "base". Instead, we use an official kernel.org Linux tar archive as the base and add a series of patches on top of it. This carries with it several benefits. The biggest is that we add metadata "tags" to our patches that allow us to easily associate patches with particular feature requests, bug reports, and/or the pedigree of the patch. Due to the nature of some of our feature requests, we must also occasionally carry patches that, for one reason or another, haven't been accepted into the mainline kernel repository yet. With a full Git repository, it would be difficult to associate the initial commit for a particular feature with any subsequent changes to it. Another benefit is more superficial: with the use of separate patches, we and our users are able to tell, at a glance, which patches are in any given kernel release simply by looking at the source package. This approach works well but has limited options for typical debugging techniques such as bisection. The application of the patch series results in our fully operational SLE kernel but stopping the patch series midway can result in an unbuildable source tree. To help this and similar scenarios, we publish also a fully expanded Git repository at which exactly represents the code as if it were originally used as a standard source code tree repository. This allows us to work with the individual patches *and* have the ability to bisect the tree as the changes are applied. It also makes it easier for partners unfamiliar with how our source tree works to make the transition. Format ------ The SLE patch format follows very closely what you would see on any mailing list associated with Linux kernel development. A SLE patch is formatted like an RFC822 mbox-style mail message, with a few extensions. If the patch is coming from the mainline Linux repository or a subsystem maintainer repository, SUSE has tools that can make adding these tags nearly painless. Each patch should contain the "From" and "Subject" headers found in any email message. The From should contain the name and email address of the patch author. The Subject should contain a short description of the patch, prefixed with the subsystem affected. For instance: From: Jeff Mahoney Subject: init: print hello world at boot time Beyond that, we require several more headers, the full description of the patch, the certification tags used in the mainline kernel, and the patch contents. The required headers are as follows: * Git-commit: [a-f0-9]{40} Contains the SHA-1 Git commit ID of the patch in either the mainline kernel repository or an official maintainer repository. * Git-repo: URL-to-git-repo (starting with `git://`) The URL to the Git repository containing the commit. This tag can be omitted if the commit is from the mainline kernel repository. * Patch-mainline: vMajor.Minor.Patch{-optional-rc} The official kernel release that contains this patch. In the case of a patch accepted into a maintainer branch, "Queued in subsystem maintainer repo" can be used. If the patch has been submitted to a subsystem mailing list for review and is nearly certain to be accepted, "Submitted " can be used. Otherwise, if the patch will never be in the upstream kernel, e.g. in the case of vendor-specific version numbers, etc., then "No" followed by the reason why it will not be accepted (or submitted). Please note that the reason must be compelling for it to be allowed into our kernel repository. * References: list of references A specific reason must exist for each patch to be included into the kernel repository. It can be a fix in response to a bug report or a patch submitted as part of the feature development cycle for a release. We use a shorthand to indicate why a particular patch will be included and it's possible to use more than one. For feature requests, the feature will have to have gone through our feature tracking tool, a Jira instance at . Each feature request will have an ID associated with it and it can be added to the References tag using jsc#id, e.g. jsc#PED-12345. For fixes to bug reports or patches for feature requests submitted via Bugzilla at , the shorthand is bsc#number. Other shorthands referring to different Bugzilla instances are possible too, such as bko, for . Next is the full description of the patch, which should explain why the patch is needed and an overview of what it does. The last "header" portion of the patch contains the certification tags, which consist of "Signed-off-by" and "Acked-by". We and the upstream Linux community depend on patch submitters to "own" their submission and certify they have the right to submit code to the kernel repository. For patches coming from the mainline Linux kernel repository, the certification tags are already in place and only the submitter's tag needs to be added, unless one is also already part of the original patch. Likewise, the SUSE engineer who includes the submission in our kernel tree will add their own "Acked-by" tag. The remaining part of the patch is the actual diff with changes. The patch content should be in the "-ab" format where the patch header itself only contains the filename without any timestamps. An optional `diffstat -p1` output may also be included. Here's an example of a complete patch: ``` From: Upstream Committer Subject: init: print hello world on boot Patch-mainline: v3.8-rc1 Git-commit: deadbeefc0ffeeb1a4b1a4b1a4b1a4b1a4b1a4b1a4 References: jsc#PED-12134 bsc#23123 The kernel started off like every other project. Let's add the hello world message in honor of its roots. Signed-off-by: Upstream Committer Tested-by: Bill User Acked-by: Jeff Mahoney --- init/main.c | 1 + 1 file changed, 1 insertion(+) --- a/init/main.c +++ b/init/main.c @@ -807,6 +807,7 @@ static noinline int init_post(void) system_state = SYSTEM_RUNNING; numa_default_policy(); + printk("Hello world!\n"); current->signal->flags |= SIGNAL_UNKILLABLE; ``` Patch inclusion rules --------------------- As mentioned in the summary, we expect that most patches to the SLE kernel will come from subsequent official upstream kernel releases, or from subsystem maintainer repositories where the patch is on its way to become a part of an official upstream Linux release. The SLE kernel contains hardware enablement driver enhancement/backports for a wide range of devices offered by many vendors. In many cases, the drivers are self-contained but many others have shared dependencies on common infrastructure. The shared dependencies on common infrastructure combined with the need to be able to bisect the resulting kernel means that we must require all partners to submit patch series consisting of individual patches that match upstream commits. In the case where a commit affects multiple drivers, it is acceptable to only include the portions that affect a particular driver as long as it is annotated by appending "(partial)" to the Git-commit line and documenting what is included or dropped. An example using the patch tools is included below. Tools ----- We understand that there are a bunch of rules to follow and that implementing them all can be tedious. SUSE has a set of tools to make working with the patches a lot easier. They are called patchtools and published at . Two important tools are included: fixpatch and exportpatch. Fixpatch adds missing headers and formatting to existing patches, assuming there's at least a Git-commit tag present. Exportpatch, given a list of commit IDs on the command line, searches for each commit in the configured repositories and exports the patches. Exportpatch has a number of options, the following list shows the most useful ones: * `-w` | `--write` Write out each commit into a separate file. The filenames are based on the subject of the header and they get output on stdout for use directly in a series file. * `-d DIR` | `--dir=DIR` Write out each commit into a designated directory. The default is to write into the current directory. * `-F REF` | `--reference=REFERENCE` Add a References tag to the patch output using the specified reference, can be repeated multiple times. * `-x EXTRACT` | `--extract=EXTRACT` It it sometimes desirable to split out chunks of patches that affect only a particular section of the code. This option accepts pathnames to extract. Anything not specified will be skipped. Paths ending with `/` designate everything under that hierarchy. This also adds the "(partial)" notation to the Git-commit tag and adds a Patch-filtered tag indicating which paths were used to extract. Refer to the exportpatch(1) manual page for more details and a complete list of all options. One useful feature of exportpatch is that 3-way merge diffs are handled automatically such that a new, exact 2-way diff is generated. Note that both the `-x` option and the automatic handling of merge commits can generate empty patches. Such patches are skipped entirely and no files are generated. As a quick example, the following invocation would generate patches necessary for a backport of the ixgbe driver from v3.2 against the v3.0 kernel: $ exportpatch -w -d ixgbe \ -x drivers/net/ixgbe/ -x drivers/net/ethernet/intel/ixgbe/ \ -F "jsc#PED-12345" -F "bsc#12354" \ $(git log v3.0..v3.2 --pretty=oneline -- \ drivers/net/ixgbe drivers/net/ethernet/intel/ixgbe | \ cut -b 1-40) \ > ixgbe/series The tool automatically adds an Acked-by tag to the created patches unless you were involved in the original upstream commit process. Be aware that the produced result (obviously) doesn't include any infrastructure changes that might be needed for the patches to build. The first patch in the series looks like this: ``` From 6403eab143205a45a5493166ff8bf7e3646f4a77 Mon Sep 17 00:00:00 2001 From: Joe Perches Date: Fri, 3 Jun 2011 11:51:20 +0000 Subject: drivers/net: Remove unnecessary semicolons Git-commit: 6403eab143205a45a5493166ff8bf7e3646f4a77 (partial) Patch-mainline: v3.1-rc1 References: jsc#PED-12345 bsc#12354 Patch-filtered: drivers/net/ixgbe/ drivers/net/ethernet/intel/ixgbe/ Semicolons are not necessary after switch/while/for/if braces so remove them. Signed-off-by: Joe Perches Signed-off-by: David S. Miller Acked-by: Jeff Mahoney --- drivers/net/ixgbe/ixgbe_82599.c | 4 ++-- drivers/net/ixgbe/ixgbe_common.c | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) --- a/drivers/net/ixgbe/ixgbe_82599.c +++ b/drivers/net/ixgbe/ixgbe_82599.c @@ -1157,7 +1157,7 @@ s32 ixgbe_init_fdir_signature_82599(struct ixgbe_hw *hw, u32 pballoc) default: /* bad value */ return IXGBE_ERR_CONFIG; - }; + } /* Move the flexible bytes to use the ethertype - shift 6 words */ fdirctrl |= (0x6 << IXGBE_FDIRCTRL_FLEX_SHIFT); @@ -1245,7 +1245,7 @@ s32 ixgbe_init_fdir_perfect_82599(struct ixgbe_hw *hw, u32 pballoc) default: /* bad value */ return IXGBE_ERR_CONFIG; - }; + } /* Turn perfect match filtering on */ fdirctrl |= IXGBE_FDIRCTRL_PERFECT_MATCH; --- a/drivers/net/ixgbe/ixgbe_common.c +++ b/drivers/net/ixgbe/ixgbe_common.c @@ -1292,7 +1292,7 @@ static s32 ixgbe_ready_eeprom(struct ixgbe_hw *hw) udelay(5); ixgbe_standby_eeprom(hw); - }; + } /* * On some parts, SPI write time could vary from 0-20mSec on 3.3V @@ -1374,7 +1374,7 @@ static void ixgbe_shift_out_eeprom_bits(struct ixgbe_hw *hw, u16 data, * EEPROM */ mask = mask >> 1; - }; + } /* We leave the "DI" bit set to "0" when we leave this routine. */ eec &= ~IXGBE_EEC_DI; ```