This page presents the process of building kernels with initramfs root file systems for the socfpga environment. To that end it will ignore many of the details that are required to get the basic SoC system up and running and primarily focus on what is required to get the kernel configured properly and to illustrate some ways of leveraging the other building blocks that are readily available for the basic SoC system.

The information in this next section assumes a 14.0 SoC EDS tools release environment, circa July 2014.

If you wish to demonstrate this on the Altera Cyclone V SoC development kit, you can steal a number of the building blocks out of the 14.0 SoC EDS tools release. Here's what you would need:

preloader image:
<14.0 SoC EDS>/examples/hardware/cv_soc_devkit_ghrd/software/preloader/preloader-mkpimage.bin

u-boot image:
<14.0 SoC EDS>/examples/hardware/cv_soc_devkit_ghrd/software/preloader/uboot-socfpga/u-boot.img

u-boot startup script, FPGA configuration files and device tree:
<14.0 SoC EDS>/examples/hardware/cv_soc_devkit_ghrd/sd_fat.tar.gz

The only other things that you need are a root file system and a kernel, and I'd propose that you build those from scratch using the kernel git repo on rocketboards.org, and the yocto git repo or angstrom git repo also on rocketboards.org.

This link describes how you can build the Angstrom root file system images:
Angstrom on SoCFPGA

This link describes how you can build the latest Yocto root file system images:
Building Yocto 1.5 Dora with meta-altera

This link describes how you can build the older Yocto root file system images as well as the the current kernel and u-boot:
GSRD v14.0 - Compiling Linux

The rest of this is rather generic linux information, not specific to the SoC EDS tools at all. If you'd like more information on the initramfs topic, refer to <linux>/Documentation/filesystems/ramfs-rootfs-initramfs.txt.

This page will show how to take an existing root file system image and use that to populate an initramfs and build it into the kernel. This example will have a lot of stuff in the initramfs, on the other end of the usage spectrum you could simply desire to place a single init program on your initramfs.

To demonstrate using an existing root file system image, it is assumed that you have already built an Angtrom root file system or a Yocto root file system using the flows described in the links mentioned above. Both of these flows will produce a root file system packaged in a CPIO archive file which is probably the easiest thing for you to steal to populate your initramfs with.

This example provides a shell script as a utility to extract the CPIO archive into your file system on your development host machine. It extracts all of the real files onto your file system and it extracts all of the device nodes into a file list format that is approprate to feed into the initramfs kernel build flow. To use this script simply change directory into the directory that you wish to stage the initramfs contents and run the script "extract_cpio_for_initramfs.sh <cpio archive>" passing it an absolute path to the CPIO archive file that you wish to use.

Now at this point you can manipulate the contents of the file system that was extracted from the CPIO archive on your development file system, you can add things to it or remove things from it. Whatever is in this directory will eventually be built into your initramfs. If you wish to add or remove device nodes for your initramfs, you can manually edit the device file list that the script extracted as well.

The most obvious thing that you'll need to make sure is accurate in your initramfs staging area is the /lib/modules contents, you'll want to make sure that you install the modules required by your kernel build into that location prior to building this initramfs into your kernel.

Once you have your initramfs contents populated the way you desire, it's time to build this into your kernel. To do that you will need a kernel build environment. This example is based on the socfpga-3.10-ltsi branch of the linux-socfpga git repo housed at this URL:
git://git.rocketboards.org/linux-socfpga.git
http://git.rocketboards.org/linux-socfpga.git

Once you've applied the default socfpga kernel configuration, for instance:

make O=$OUT_DIR socfpga_defconfig

Then you need to run menuconfig to enable the initramfs configuration:

make O=$OUT_DIR menuconfig

Once you are in menuconfig you want to select the "General setup" submenu:

 .config - Linux/arm 3.10.31-ltsi Kernel Configuration
 ──────────────────────────────────────────────────────────────────────────────
  ┌────────────── Linux/arm 3.10.31-ltsi Kernel Configuration ──────────────┐
  │  Arrow keys navigate the menu.  <Enter> selects submenus --->.          │  
  │  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, │  
  │  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </> │  
  │  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >       │  
  │ ┌─────────────────────────────────────────────────────────────────────┐ │  
  │ │    -*- Patch physical to virtual translations at runtime            │ │  
>>│ │        General setup  --->                                          │ │<<
  │ │    [*] Enable loadable module support  --->                         │ │  
  │ │    [*] Enable the block layer  --->                                 │ │  
  │ │        System Type  --->                                            │ │  
  │ └────↓(+)─────────────────────────────────────────────────────────────┘ │  
  ├─────────────────────────────────────────────────────────────────────────┤  
  │        <Select>    < Exit >    < Help >    < Save >    < Load >         │  
  └─────────────────────────────────────────────────────────────────────────┘  

In the "General setup" menu, scroll down to the "Initial RAM filesystem and RAM disk support" option and activate it.

 .config - Linux/arm 3.10.31-ltsi Kernel Configuration
 → General setup ──────────────────────────────────────────────────────────────
  ┌───────────────────────────── General setup ─────────────────────────────┐
  │  Arrow keys navigate the menu.  <Enter> selects submenus --->.          │  
  │  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, │  
  │  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </> │  
  │  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >       │  
  │ ┌────↑(-)─────────────────────────────────────────────────────────────┐ │  
  │ │    [ ] Kernel->user space relay support (formerly relayfs)          │ │  
>>│ │    [ ] Initial RAM filesystem and RAM disk (initramfs/initrd) suppor│ │<<
  │ │    [ ] Optimize for size                                            │ │  
  │ │    -*- Configure standard kernel features (expert users)  --->      │ │  
  │ │    [*] Embedded system                                              │ │  
  │ └────↓(+)─────────────────────────────────────────────────────────────┘ │  
  ├─────────────────────────────────────────────────────────────────────────┤  
  │        <Select>    < Exit >    < Help >    < Save >    < Load >         │  
  └─────────────────────────────────────────────────────────────────────────┘  

Once the "Initial RAM filesystem and RAM disk support" option is activated, you should see the "Initramfs source file(s)" option appear. Select it.

 .config - Linux/arm 3.10.31-ltsi Kernel Configuration
 → General setup ──────────────────────────────────────────────────────────────
  ┌───────────────────────────── General setup ─────────────────────────────┐
  │  Arrow keys navigate the menu.  <Enter> selects submenus --->.          │  
  │  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, │  
  │  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </> │  
  │  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >       │  
  │ ┌────↑(-)─────────────────────────────────────────────────────────────┐ │  
  │ │    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) suppor│ │  
>>│ │    ()    Initramfs source file(s) (NEW)                             │ │<<
  │ │    [*]   Support initial ramdisks compressed using gzip (NEW)       │ │  
  │ │    [ ]   Support initial ramdisks compressed using bzip2 (NEW)      │ │  
  │ │    [ ]   Support initial ramdisks compressed using LZMA (NEW)       │ │  
  │ └────↓(+)─────────────────────────────────────────────────────────────┘ │  
  ├─────────────────────────────────────────────────────────────────────────┤  
  │        <Select>    < Exit >    < Help >    < Save >    < Load >         │  
  └─────────────────────────────────────────────────────────────────────────┘  

You now add your paths to your initramfs source files directory and file list to this option, and then select OK.

 .config - Linux/arm 3.10.31-ltsi Kernel Configuration
 → General setup ──────────────────────────────────────────────────────────────

  ┌─────────────────────── Initramfs source file(s) ────────────────────────┐
  │  Please enter a string value. Use the <TAB> key to move from the input  │  
  │  field to the buttons below it.                                         │  
  │ ┌─────────────────────────────────────────────────────────────────────┐ │  
>>│ │les_dir /data/builds/initramfs-poky-dora-cpio/initramfs_dev_list.txt │ │<<
  │ └─────────────────────────────────────────────────────────────────────┘ │  
  │                                                                         │  
  ├─────────────────────────────────────────────────────────────────────────┤  
  │                         <  Ok  >      < Help >                          │  
  └─────────────────────────────────────────────────────────────────────────┘  

Once you add your paths to the "Initramfs source file(s)" option, then two more options appear, the "User ID to map to 0" and "Group ID to map to 0" options. Select the "User ID to map to 0" option.

 .config - Linux/arm 3.10.31-ltsi Kernel Configuration
 → General setup ──────────────────────────────────────────────────────────────
  ┌───────────────────────────── General setup ─────────────────────────────┐
  │  Arrow keys navigate the menu.  <Enter> selects submenus --->.          │  
  │  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, │  
  │  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </> │  
  │  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >       │  
  │ ┌────↑(-)─────────────────────────────────────────────────────────────┐ │  
  │ │    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) suppor│ │  
  │ │    (/data/builds/initramfs-poky-dora-cpio/initramfs_files_dir /data/│ │  
>>│ │    (0)     User ID to map to 0 (user root)                          │ │<<
  │ │    (0)     Group ID to map to 0 (group root) (NEW)                  │ │
  │ │    [*]   Support initial ramdisks compressed using gzip (NEW)       │ │  
  │ └────↓(+)─────────────────────────────────────────────────────────────┘ │  
  ├─────────────────────────────────────────────────────────────────────────┤
  │        <Select>    < Exit >    < Help >    < Save >    < Load >         │  
  └─────────────────────────────────────────────────────────────────────────┘  

You typically set this to your own user id since the files that you placed in the staging directory for inclusion in your initramfs will typically carry your user id. If that is not the case then use the user id that the files in your initramfs staging directory actually use. "ls -n" should show you the user id of the files in the staging directory and "id -u" should show you your user id.

 .config - Linux/arm 3.10.31-ltsi Kernel Configuration
 → General setup ──────────────────────────────────────────────────────────────

  ┌──────────────────── User ID to map to 0 (user root) ────────────────────┐
  │  Please enter a decimal value. Fractions will not be accepted.  Use the │  
  │  <TAB> key to move from the input field to the buttons below it.        │  
  │ ┌─────────────────────────────────────────────────────────────────────┐ │  
>>│ │9506                                                                 │ │<<
  │ └─────────────────────────────────────────────────────────────────────┘ │  
  │                                                                         │  
  ├─────────────────────────────────────────────────────────────────────────┤
  │                         <  Ok  >      < Help >                          │  
  └─────────────────────────────────────────────────────────────────────────┘  

Now select the "Group ID to map to 0" option.

 .config - Linux/arm 3.10.31-ltsi Kernel Configuration
 → General setup ──────────────────────────────────────────────────────────────
  ┌───────────────────────────── General setup ─────────────────────────────┐
  │  Arrow keys navigate the menu.  <Enter> selects submenus --->.          │  
  │  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, │  
  │  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </> │  
  │  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >       │  
  │ ┌────↑(-)─────────────────────────────────────────────────────────────┐ │  
  │ │    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) suppor│ │  
  │ │    (/data/builds/initramfs-poky-dora-cpio/initramfs_files_dir /data/│ │  
  │ │    (9506)  User ID to map to 0 (user root)                          │ │  
>>│ │    (0)     Group ID to map to 0 (group root) (NEW)                  │ │<<
  │ │    [*]   Support initial ramdisks compressed using gzip (NEW)       │ │  
  │ └────↓(+)─────────────────────────────────────────────────────────────┘ │  
  ├─────────────────────────────────────────────────────────────────────────┤
  │        <Select>    < Exit >    < Help >    < Save >    < Load >         │  
  └─────────────────────────────────────────────────────────────────────────┘  

You typically set this to your own group id since the files that you placed in the staging directory for inclusion in your initramfs will typically carry your group id. If that is not the case then use the group id that the files in your initramfs staging directory actually use. "ls -n" should show you the group id of the files in the staging directory and "id -g" should show you your group id.

 .config - Linux/arm 3.10.31-ltsi Kernel Configuration
 → General setup ──────────────────────────────────────────────────────────────

  ┌─────────────────── Group ID to map to 0 (group root) ───────────────────┐
  │  Please enter a decimal value. Fractions will not be accepted.  Use the │  
  │  <TAB> key to move from the input field to the buttons below it.        │  
  │ ┌─────────────────────────────────────────────────────────────────────┐ │  
>>│ │86                                                                   │ │<<
  │ └─────────────────────────────────────────────────────────────────────┘ │  
  │                                                                         │  
  ├─────────────────────────────────────────────────────────────────────────┤
  │                         <  Ok  >      < Help >                          │  
  └─────────────────────────────────────────────────────────────────────────┘  

At this point you have entered all of the options required to enable the initramfs build of your kernel so you can exit menuconfig saving your changes and then rebuild the kernel.

 .config - Linux/arm 3.10.31-ltsi Kernel Configuration
 → General setup ──────────────────────────────────────────────────────────────
  ┌───────────────────────────── General setup ─────────────────────────────┐
  │  Arrow keys navigate the menu.  <Enter> selects submenus --->.          │  
  │  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, │  
  │  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </> │  
  │  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >       │  
  │ ┌────↑(-)─────────────────────────────────────────────────────────────┐ │  
  │ │    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) suppor│ │  
  │ │    (/data/builds/initramfs-poky-dora-cpio/initramfs_files_dir /data/│ │  
  │ │    (9506)  User ID to map to 0 (user root)                          │ │  
  │ │    (86)    Group ID to map to 0 (group root)                        │ │
  │ │    [*]   Support initial ramdisks compressed using gzip (NEW)       │ │  
  │ └────↓(+)─────────────────────────────────────────────────────────────┘ │  
  ├─────────────────────────────────────────────────────────────────────────┤
  │        <Select>    < Exit >    < Help >    < Save >    < Load >         │  
  └─────────────────────────────────────────────────────────────────────────┘  

At this point you should be able to rebuild your kernel to incorporate the initramfs:

make O=$OUT_DIR zImage

Then install this zImage onto your boot media and try it out. This should get you booting into the root file system produced by the Yocto or Angstrom flow that you stole it from, but the whole root file system is part of the initramfs built into the kernel at this point.

Once you get the basic initramfs build flow working and producing useful results for you, then there are a couple of other use models that you're probably more interested in using rather than simply bundling up an existing root file system into an initramfs. You probalby have some desire to implement your own init program that takes control of the target when the kernel enters userspace, or maybe you want to even "switch root" from your init program on the initramfs into an existing file system on some other media that your target has access to. This example provides two more program examples for accomplishing both of these tasks which you can try out on your initramfs, the "hello_init.c" program illustrates how to simply create an init program that can be executed by the kernel on your initramfs, and the "hello_switch_root.c" program illustrates how to create an init program that eventually switches over to another file system and executes a new init program. To use the "hello_switch_root.c" program you will need to have the alternate file system installed on the media that you plan to switch to. There is a build script called "build_init.sh" which is provided to illustrate how these init programs can be built.