86f9b1f174
OBS-URL: https://build.opensuse.org/package/show/Kernel:stable/kernel-source?expand=0&rev=351
315 lines
13 KiB
Plaintext
315 lines
13 KiB
Plaintext
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 indended 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
|
|
(kernel-source.git[1]) tree 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 also must occasionally carry patches
|
|
that, for one reason or another, haven't been accepted into the mainline
|
|
kernel repository yet. With a full (published[2]) 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. Patches are grouped into subsystems (including
|
|
architecture, "core" vm/scheduler, VFS, individual file systems, driver
|
|
core, networking core, block layer, and leaf drivers) so finding patches
|
|
that affect a particular part of the kernel can be easily found. Patches
|
|
are placed in directories such as patches.fixes, patches.suse, etc. When
|
|
submitting patches for inclusion, it's not necessary to choose a directory.
|
|
We'll put them in the appropriate place.
|
|
|
|
Historically, this approach has worked 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.
|
|
Beginning with the SLE11 SP2 development cycle, we've published a fully
|
|
expanded git repository (kernel.git[2]) that 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 published here[3] 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.
|
|
|
|
e.g.
|
|
From: Jeff Mahoney <jeffm@suse.com>
|
|
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 headers we require 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[4] 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 <date> <list@site.org>" 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
|
|
- There must be a reason 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, FATE. Each feature request will have an ID
|
|
associated with it and it can be added to the References tag using
|
|
FATE#number, e.g. FATE#12345.
|
|
|
|
For fixes for bug reports (or patches for feature requests submitted
|
|
via Bugzilla, the shorthand is bnc#number. bnc is shorthand for
|
|
bugzilla.novell.com. There are others such as bko, for
|
|
bugzilla.kernel.org.
|
|
|
|
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 we only need the submitter's tag added (if not
|
|
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.
|
|
|
|
There may be an optional diffstat -p1 output added before the patch content.
|
|
|
|
The patch content itself should be in "-ab" format where the patch header
|
|
itself only contains the filename without any timestamps.
|
|
|
|
Here's an example of a complete patch:
|
|
|
|
-------->8--------
|
|
From: Upstream Committer <coder@somesite.com>
|
|
Subject: init: print hello world on boot
|
|
Patch-mainline: v3.8-rc1
|
|
Git-commit: deadbeefc0ffeeb1a4b1a4b1a4b1a4b1a4b1a4b1a4
|
|
References: FATE#12134 bnc#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 <coder@somesite.com>
|
|
Tested-by: Bill User <bill.user@example.com>
|
|
Acked-by: Jeff Mahoney <jeffm@suse.com>
|
|
---
|
|
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;
|
|
|
|
--------8<--------
|
|
|
|
|
|
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 (which imply that the patch will ultimately be
|
|
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 contain the portions that effect 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. We have a set of tools, published here[3], to make
|
|
working with the patches a lot easier.
|
|
|
|
There are two tools: fixpatch and exportpatch. Fixpatch will add 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
|
|
commandline, will search for each commit in the configured repositories
|
|
and export the patches.
|
|
|
|
There are several command line options that are useful.
|
|
|
|
-w|--write -- will write out each commit into a separate file. The filenames
|
|
are based on the subject of the header and the filenames will
|
|
be output on stdout for use directly in a series file.
|
|
|
|
-d DIR|--dir=DIR -- will write out each commit into a designated directory.
|
|
The default is to write into the current directory.
|
|
-f|--force -- By default exportpatch will not export commits that are local
|
|
to the repository on disk. It will also refuse to overwrite
|
|
existing patch files. This option overrides these checks.
|
|
-F REF|--reference=REFERENCE -- Adds References automatically and can be
|
|
specified 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 a (partial)
|
|
notation to the Git-commit tag and adds
|
|
a Patch-filtered: tag indicating which
|
|
paths were used to extract.
|
|
|
|
There are also two other features that are used automatically. The first is
|
|
that 3-way merge diffs are handled automatically such that a new, exact
|
|
two-way diff is generated. Note that both the -x option and the automatic
|
|
handling of merge commits can generate empty patches -- empty patches are
|
|
skipped entirely and no files are generated.
|
|
|
|
A quick example for generating the patches necessary for a backport of the
|
|
ixgbe driver against the 3.0 kernel. Please note that it (obviously) skips
|
|
any infrastructure changes required for the patches to build. The Acked-by
|
|
tags will automatically be added unless you were involved in the original
|
|
upstream commit process.
|
|
|
|
exportpatch -w -d ixgbe -x drivers/net/ixgbe/ \
|
|
-x drivers/net/ethernet/intel/ixgbe/ \
|
|
-F "FATE#12345" -F "bnc#12354" \
|
|
$(git log v3.0.. --pretty=oneline -- drivers/net/ixgbe \
|
|
drivers/net/ethernet/intel/ixgbe |cut -b 1-40) > ixgbe/series
|
|
|
|
The first patch in that series looks like this:
|
|
--------8<--------
|
|
From 6403eab143205a45a5493166ff8bf7e3646f4a77 Mon Sep 17 00:00:00 2001
|
|
From: Joe Perches <joe@perches.com>
|
|
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: FATE#12345 bnc#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 <joe@perches.com>
|
|
Signed-off-by: David S. Miller <davem@davemloft.net>
|
|
Acked-by: Jeff Mahoney <jeffm@suse.com>
|
|
---
|
|
|
|
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;
|
|
|
|
-------->8--------
|
|
|
|
Links:
|
|
[1]: http://kernel.suse.com/cgit/kernel-source/log/?h=SLE12
|
|
[2]: http://kernel.suse.com/cgit/kernel/log/?h=SLE12
|
|
[3]: http://download.opensuse.org/repositories/Kernel:/tools/
|
|
[4]: http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git
|