Commit 0d07cf5e authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

docs: early-userspace: convert docs to ReST and rename to *.rst 



The two files there describes a Kernel API feature, used to
support early userspace stuff. Prepare for moving them to
the kernel API book by converting to ReST format.

The conversion itself was quite trivial: just add/mark a few
titles as such, add a literal block markup, add a table markup
and a few blank lines, in order to make Sphinx to properly parse it.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
parent 93d2c159

Documentation/early-userspace/buffer-format.txt→Documentation/early-userspace/buffer-format.rst

+13 −6
Original line number Diff line number Diff line 
=======================

initramfs buffer format

		       -----------------------

=======================



Al Viro, H. Peter Anvin



Last revision: 2002-01-13



Starting with kernel 2.5.x, the old "initial ramdisk" protocol is
@@ -18,7 +20,8 @@ archive can be compressed using gzip(1). One valid version of an 
initramfs buffer is thus a single .cpio.gz file.



The full format of the initramfs buffer is defined by the following

grammar, where:

grammar, where::



	*	is used to indicate "0 or more occurrences of"

	(|)	indicates alternatives

	+	indicates concatenation
@@ -49,7 +52,9 @@ hexadecimal ASCII numbers fully padded with '0' on the left to the 
full width of the field, for example, the integer 4780 is represented

by the ASCII string "000012ac"):



============= ================== ==============================================

Field name    Field size	 Meaning

============= ================== ==============================================

c_magic	      6 bytes		 The string "070701" or "070702"

c_ino	      8 bytes		 File inode number

c_mode	      8 bytes		 File mode and permissions
@@ -65,6 +70,7 @@ c_rmin 8 bytes Minor part of device node reference 
c_namesize    8 bytes		 Length of filename, including final \0

c_chksum      8 bytes		 Checksum of data field if c_magic is 070702;

				 otherwise zero

============= ================== ==============================================



The c_mode field matches the contents of st_mode returned by stat(2)

on Linux, and encodes the file type and file permissions.
@@ -82,7 +88,8 @@ If the filename is "TRAILER!!!" this is actually an end-of-archive 
marker; the c_filesize for an end-of-archive marker must be zero.





*** Handling of hard links

Handling of hard links

======================



When a nondirectory with c_nlink > 1 is seen, the (c_maj,c_min,c_ino)

tuple is looked up in a tuple buffer.  If not found, it is entered in

Documentation/early-userspace/README→Documentation/early-userspace/early_userspace_support.rst

+3 −0
Original line number Diff line number Diff line 
=======================

Early userspace support

=======================
@@ -26,6 +27,7 @@ archive to be used as the image or have the kernel build process build 
the image from specifications.



CPIO ARCHIVE method

-------------------



You can create a cpio archive that contains the early userspace image.

Your cpio archive should be specified in CONFIG_INITRAMFS_SOURCE and it
@@ -34,6 +36,7 @@ CONFIG_INITRAMFS_SOURCE and directory and file names are not allowed in 
combination with a cpio archive.



IMAGE BUILDING method

---------------------



The kernel build process can also build an early userspace image from

source parts rather than supplying a cpio archive.  This method provides

Documentation/early-userspace/index.rst

0 → 100644
+18 −0
Original line number Diff line number Diff line 
:orphan:



===============

Early Userspace

===============



.. toctree::

    :maxdepth: 1



    early_userspace_support

    buffer-format



.. only::  subproject and html



   Indices

   =======



   * :ref:`genindex`

Documentation/filesystems/nfs/nfsroot.txt

+1 −1
Original line number Diff line number Diff line
@@ -239,7 +239,7 @@ rdinit=<executable file> 
  A description of the process of mounting the root file system can be

  found in:



    Documentation/early-userspace/README

    Documentation/early-userspace/early_userspace_support.rst

Documentation/filesystems/ramfs-rootfs-initramfs.txt

+2 −2
Original line number Diff line number Diff line
@@ -105,7 +105,7 @@ All this differs from the old initrd in several ways: 
  - The old initrd file was a gzipped filesystem image (in some file format,

    such as ext2, that needed a driver built into the kernel), while the new

    initramfs archive is a gzipped cpio archive (like tar only simpler,

    see cpio(1) and Documentation/early-userspace/buffer-format.txt).  The

    see cpio(1) and Documentation/early-userspace/buffer-format.rst).  The

    kernel's cpio extraction code is not only extremely small, it's also

    __init text and data that can be discarded during the boot process.
@@ -159,7 +159,7 @@ One advantage of the configuration file is that root access is not required to 
set permissions or create device nodes in the new archive.  (Note that those

two example "file" entries expect to find files named "init.sh" and "busybox" in

a directory called "initramfs", under the linux-2.6.* directory.  See

Documentation/early-userspace/README for more details.)

Documentation/early-userspace/early_userspace_support.rst for more details.)



The kernel does not depend on external cpio tools.  If you specify a

directory instead of a configuration file, the kernel's build infrastructure

CRA Git | Maintained and supported by SUSTech CRA and CCSE