lustre/kernel_patches/README

   1
   2 Lustre requires changes to the core kernel before it can be compiled against
   3 hte core kernel source tree.  We use Andrew Morton's 'patch-scripts' utilties
   4 to keep the complexity of managing changes across multiple kernel targets down.
   5 They handle the ordering metadata, application, refreshing, and removal of
   6 patches  for us.  Please read scripts/docco.txt for a more thorough explanation
   7 of what 'patch-scripts' do.
   8
   9 We create a thin wrapper around patchscripts with our ./prepare_tree.sh.  It
  10 exports two environment variables.  PATCHSCRIPTS is a relative path from the
  11 kernel source tree to the checked-out patchscripts repository.  It is requires
  12 for patchscripts to operate on data outside the kernel source tree.  It also
  13 puts the absolute path to the scripts/ directory at the front of PATH.
  14 Finally, it creates a 'series' link from the kernel tree back to the proper
  15 series file for that kernel tree.  More on that below.
  16
  17 prepare_tree.sh and the patch-scripts commands are the only interface we should
  18 use on a daily basis.  We should never have to manage the patches by hand.
  19 This will save us heart-ache once we're good with the tools.  I promise.
  20
  21 Data to be aware of:
  22
  23 patches/
  24         contains all the patch files themselves.  We should have a patch per
  25         functional change.
  26
  27 series/
  28         the text files that patch-utils use to define the ordering of patches
  29         that are applied to a tree.  We have a series file for each kernel
  30         tree variant that requires wildly different patches.  (architecture
  31         differences, stock vs. redhat, etc)
  32
  33 pc/
  34         control files for patch-utils.  These are per tree and should never
  35         be in cvs.
  36
  37 txt/
  38         text descriptions of the patches.  Nice, but not functionally required.
  39
  40 First, before anything happens, you need to prep a tree for use with
  41 patch-utils.  This means putting a series link in the file and setting the
  42 environment variable:
  43
  44         $ eval `./prepare_tree.sh -t /tmp/kernels/linux-2.4.18 -r stock-2.4`
  45
  46 prepare-tree.sh is careful to output variable assignments to stdout and
  47 everything else to stderr so the eval won't go awry.  It also is clever about
  48 resolving the series name, so tab-completed relative paths to the series files
  49 can be used with -r.  (it assumes that series/ is under where prepare_tree.sh
  50 was executed from).  The series link that is created from the tree back into
  51 the cvs repository is created by force.  Don't re-run the command with a
  52 different role.  (this should probably be fixed)
  53
  54 With this in place, the shell that did the eval is ready to wield patch-utils.
  55
  56 ] To apply all the patches to a given tree:
  57
  58         $ eval `./prepare_tree.sh -t /tmp/kernels/linux-2.4.18 -r stock-2.4`
  59         $ cd /tmp/kernels/linux-2.4.18
  60         $ pushpatch 100000
  61                 ( the huge number just serves to iterate through the patches )
  62
  63 ] To refresh the patches against a newer kernel that the series applies to.
  64
  65 Say the series file 'rh-8.0-dev' corresponds to a CFS policy of tracking the
  66 most recent red hat 8.0 distro kernel.   It used to be 2.4.18-14, say, and RH
  67 has now released RH 2.4.18-17.8.0 and CFS has decided to move to it.  We
  68 want to update the patches in cvs HEAD to be against 2.4.18-17.8.0
  69
  70         $ eval `./prepare_tree.sh -t /tmp/linux-2.4.18-17.8.0 -r rh-8.0-dev`
  71         $ cd /tmp/linux-2.4.18-17.8.0
  72         $ for a in $NUM_PATCHES_HAVE ; do
  73                 pushpatch;
  74                 refpatch;
  75           done
  76
  77 ] To add a new series
  78
  79 Simply add a new empty file to the series/ directory, choosing a descriptive
  80 name for the series.
  81
  82 ] To add a patch into a series
  83
  84 Ideally a patch can be added to the end of the series.  This is most easily
  85 done with patch-utils import_patch.  After the patch is imported it still needs
  86 to be applied and refreshed with 'pushpatch' and 'refpatch'.  ___remember to
  87 cvs add the patch with -ko___ so that tags in the context of the diff aren't
  88 change by CVS, rendering the patch unusable.
  89
  90 It is considered valuable to have a common HEAD which can be checked out to
  91 patch a kernel and build lustre across lots of targets.  This creates some
  92 friction in the desire to keep a single canonical set of patches in CVS.  We
  93 solve this with the patch-utils scripts by having well-named patches that are
  94 bound to the different series.  Say alpha and ia64 kernel trees both need a
  95 common lustre patch.  Ideally they'd both have our-funcionality.patch in their
  96 series, but perhaps the code path we want to alter is different in the trees
  97 and not in the architecture-dependant part of the kernel.  For this we'd want
  98 our-functionality-ia64.patch in the ia64 series file, and
  99 our-functionality-alpha.patch in the alpha.  This split becomes irritating to
 100 manage as shared changes want to be pushed to all the patches.  This will be a
 101 pain as long as the kernel's we're receiving don't share revision control
 102 somehow.  At least the patch utils make it relatively painless to 'pushpatch'
 103 the source patch, clean up rejects, test, and 'refpatch' to generate the new
 104 patch for that series.