
Please refer to the online GPFS FAQ at

  https://www.ibm.com/support/knowledgecenter/en/STXKQY/gpfsclustersfaq.html

  for the latest information about GPFS updates, supported kernel levels,
  and kernel patches before building the portability layer.

Linux kernel patches for GPFS can be obtained at

  http://sourceforge.net/tracker/?atid=719124&group_id=130828&func=browse

  which is the patches link for the project
  "General Parallel File System (GPFS)" on Source Forge; only Linux
  kernel patches are kept on the Source Forge site.

You can send license and source code inquiries to gpfs@us.ibm.com
or, in writing, to:

  GPFS Product Manager
  International Business Machines Company
  Dept. LNLA  Mail Station P963
  2455 South Road
  Poughkeepsie NY 12601-5400
  United States of America


To build the Linux portability interface for GPFS
-------------------------------------------------

  It is strongly suggested that you build the source at non root level.
  You will need to change the owner and group permissions accordingly in
  /usr/lpp/mmfs/src.

  When you build as a non root user it is also important that you have
  read access to the linux kernel source files on your machine.  These
  files are normally found in /lib/modules/`uname -r`/build but may
  appear in a different place as enumerated below in step 2 section D.

  You can use the mmbuildgpl command to simplify the build process.
  To build the GPFS portability layer using mmbuildgpl, enter the
  following command:
       /usr/lpp/mmfs/bin/mmbuildgpl

  Each kernel module is specific to a Linux version and platform.
  If you have multiple nodes running exactly the same operating
  system level on the same platform, and only some of these nodes
  have a compiler available, you can build the kernel module on one
  node, then create an installable package that contains the binary
  module for ease of distribution.
  If you choose to generate an installable package for portability
  layer binaries, perform the following additional step:
       /usr/lpp/mmfs/bin/mmbuildgpl --build-package

  If you choose to generate an installable package for portability
  layer binaries for a specific RHEL kernel release, perform the
  following additional step instead:
       /usr/lpp/mmfs/bin/mmbuildgpl --build-package --kernel-release KernelRelease

  Or another way to build the portability layer is to use
  the "Autoconfig" process:

  1) cd /usr/lpp/mmfs/src or
     for BGP IO nodes only, cd /bgsys/drivers/ppcfloor/linux/OS/usr/lpp/mmfs/src
  2) make Autoconfig
  3) make World
  4) make InstallImages

  Alternatively, if you have a platform that requires customization,
  automatic or manual creation of the env.mk file will be necessary as
  follows.

  1) cd /usr/lpp/mmfs/src/config or
     (for BGP IO nodes only, cd /bgsys/drivers/ppcfloor/linux/OS/usr/lpp/mmfs/src)
     cp env.mk.sample env.mk

  2a) Manual creation of the env.mk file.

     A) The default architecture is GPFS_ARCH_X86_64. Only modify the
        architecture choice if your platform is not Intel x86_64 bit based.

     B) Modify the Linux distribution choice according to the software
        distribution your machine runs.

     C) Modify the LINUX_KERNEL_VERSION according to the Linux kernel
        level you are using with your software distribution.

     D) Note also that the kernel header file search path,
        KERNEL_BUILD_DIR, is by default /lib/modules/`uname -r`/build

        Customers who have their kernel source in a different directory
        will need to modify KERNEL_BUILD_DIR.

        YOU MUST HAVE READ ACCESS TO THESE FILES!

  2b) Automatic creation of the env.mk file.

     A) cd /usr/lpp/mmfs/src

     B) make LINUX_KERNEL_RELEASE=customized_kernel_release Autoconfig

        customized_kernel_release follows format similar as the output
        from "uname -r".  For example:
          make LINUX_KERNEL_RELEASE=3.10.0-1127.10.1.el7.x86_64 Autoconfig

     The procedure is only supported for the RHEL release, and
     customized_kernel_release should be lower than the running one
     (uname -r) on the host node.

  3) cd /usr/lpp/mmfs/src or
     for BGP IO nodes only, cd /bgsys/drivers/ppcfloor/linux/OS/usr/lpp/mmfs/src

  4) make World

  All of the libraries and binaries reside in the "bin" subdirectory after the
  build. Kernel modules however are in the "gpl-linux" subdirectory.


To install the Linux portability interface for GPFS
--------------------------------------------------------------------------

  This step installs the binaries for the portability interface.

  1) su

  2) make InstallImages

     Binaries and kernel modules will be generated after the build finishes
     for portability layer.
     Binary lxtrace-`uname -r` generated during the
     build step will be installed in /usr/lpp/mmfs/bin.
     Three kernel modules tracedev.ko, mmfslinux.ko, and mmfs26 will be
     installed to /lib/modules/`uname -r`/extra.

     If this kernel configuration applies to other machines in the cluster,
     you may either generate the binary RPM package by "make rpm", and then
     have the package installed on those machines or iteratively perform the
     above compile and install steps on each machine.

  If you choose to generate a RPM package for portability layer binaries, the
  following additional step is needed:

  3) make rpm

     You may then copy the generated rpm packages to other machines for
     deployment. The generated RPM can ONLY be deployed to the machine with
     identical architecture, distribution level, Linux kernel version and GPFS
     version.

     Note that during the package generation, temporary files will be put to
     /tmp/rpm directory. Please make sure there is sufficient space available.
     By default, the generated RPM goes to /usr/src/packages/RPMS/<arch>
     for Suse Linux Enterprise Server and /usr/src/redhat/RPMS/<arch> for
     Redhat Enterprise Linux.

Additional Notes
----------------

  Most of the source code headers are in the "ibm-kxi" and "ibm-linux"
  directories, while the source code is in the "gpl-linux" directory.

  The "config" directory provides the configuration information for
  the build (env.mk, kdef.mk, gdef.mk).


Troubleshooting build problems
------------------------------
Most commonly encountered build problems are caused by an incorrect setting
of the kernel source tree.  GPFS leverages Kbuild infrastructure in Linux
kernel in order to build; a subset of kernel tree which is sufficient for
Kbuild to run is enough to GPFS. For SuSE Enterprise Server and Redhat
Enterprise Linux, the default source tree that work is
/lib/modules/`uname -r`/build.

Some files in the full source tree, most notably include/linux/version.h and
include/linux/autoconf.h, are often configured dynamically by an external shell
script (e.g. /etc/init.d/running-kernel on SuSE Enterprise Server), which
copies a set of files into the source tree to make it match the currently
booted kernel (that way one can boot different kernels but have the same
source tree always configured to match it).

If the kernel source tree is updated but the shell reconfiguration script
hasn't run (it usually runs during the boot sequence), or the script didn't
work correctly, the kernel source tree may not be configured properly.
This may be due to the existence of a /usr/src/linux/.config file.  When
this file exists, running-kernel assumes the kernel has been customized and
does not perform synchronization of the header files-GPFS's makefiles detect
this configuration and decline to run.  To correct this, remove or rename the
.config file.

NOTE: On SuSE Enterprise Server 10 for PowerPC, /etc/init.d/running-kernel
that ships with the GA level of distribution (kernel-source-2.6.16.21-0.8)
contains a bug that results in the wrong set of files being copied to the
kernel source tree.  This bug will be fixed with SLES10 SP1.  If the official
fix is unavailable, the following change should also address the problem:

--- running-kernel.orig 2006-10-06 14:54:36.000000000 -0500
+++ /etc/init.d/running-kernel  2006-10-06 14:59:58.000000000 -0500
@@ -53,6 +53,7 @@
     arm*|sa110)        arch=arm ;;
     s390x)     arch=s390 ;;
     parisc64)  arch=parisc ;;
+    ppc64)     arch=powerpc ;;
     esac
     # FIXME: How to handle uml?

