initramfs buffer format

initramfs buffer 형식 개요

문서 제목은 `initramfs buffer format`이며 Al Viro와 H. Peter Anvin이 작성했습니다.

kernel 2.5.x에서 기존 `initial ramdisk` protocol에 `initial ramfs` protocol이 추가되었습니다. initramfs 내용은 initrd와 같은 memory buffer protocol로 전달되지만 내용 형식은 다릅니다. initramfs buffer에는 ramfs filesystem으로 펼칠 archive가 들어 있으며, 이 문서는 그 buffer format을 규정합니다.

initramfs buffer format은 CPIO의 `newc` 또는 `crc` format을 기반으로 하며 `cpio(1)` utility로 만들 수 있습니다. cpio archive는 `gzip(1)` 또는 `CONFIG_DECOMPRESS_*`가 제공하는 다른 algorithm으로 압축할 수 있으므로, 단일 `.cpio.gz` file도 유효한 initramfs buffer입니다.

initramfs grammar

전체 initramfs buffer format은 다음 grammar로 정의됩니다. `*`는 0회 이상 반복, `(|)`는 대안, `+`는 이어 붙이기, `GZIP()`·`BZIP2()`·`LZMA()`·`XZ()`·`LZO()`·`LZ4()`·`ZSTD()`는 operand 압축, `ALGN(n)`은 n-byte boundary까지 null byte로 padding함을 뜻합니다.

*        is used to indicate "0 or more occurrences of"
(|)        indicates alternatives
+        indicates concatenation
GZIP()        indicates gzip compression of the operand
BZIP2()        indicates bzip2 compression of the operand
LZMA()        indicates lzma compression of the operand
XZ()        indicates xz compression of the operand
LZO()        indicates lzo compression of the operand
LZ4()        indicates lz4 compression of the operand
ZSTD()        indicates zstd compression of the operand
ALGN(n)        means padding with null bytes to an n-byte boundary

initramfs := ("\0" | cpio_archive | cpio_compressed_archive)*

cpio_compressed_archive := (GZIP(cpio_archive) | BZIP2(cpio_archive)
        | LZMA(cpio_archive) | XZ(cpio_archive) | LZO(cpio_archive)
        | LZ4(cpio_archive) | ZSTD(cpio_archive))

cpio_archive := cpio_file* + (<nothing> | cpio_trailer)

cpio_file := ALGN(4) + cpio_header + filename + "\0" + ALGN(4) + data

cpio_trailer := ALGN(4) + cpio_header + "TRAILER!!!\0" + ALGN(4)

사람이 이해하기 쉽게 말하면 initramfs buffer는 `newc` 또는 `crc` format의 압축되거나 압축되지 않은 cpio archive 모음입니다. member 사이에는 padding 목적으로 임의 개수의 zero byte를 넣을 수 있습니다.

cpio end-of-archive를 나타내는 `TRAILER!!!` entry는 선택 사항이지만, 존재할 때 무시되지는 않습니다. hard link 처리에서 tuple buffer를 reset하는 의미가 있습니다.

cpio_header 구조와 field 규칙

`cpio_header`의 모든 field는 field width 전체를 왼쪽의 `0`으로 채운 hexadecimal ASCII number입니다. 예를 들어 integer 4780은 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
c_uid              8 bytes                 File uid
c_gid              8 bytes                 File gid
c_nlink              8 bytes                 Number of links
c_mtime              8 bytes                 Modification time
c_filesize    8 bytes                 Size of data field
c_maj              8 bytes                 Major part of file device number
c_min              8 bytes                 Minor part of file device number
c_rmaj              8 bytes                 Major part of device node reference
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
============= ================== ==============================================

`c_magic`은 `070701` 또는 `070702`이고, `c_ino`는 inode number, `c_mode`는 file type·mode·permission, `c_uid`와 `c_gid`는 owner ID, `c_nlink`는 link count, `c_mtime`은 modification time, `c_filesize`는 data field 크기입니다.

`c_maj`와 `c_min`은 file device number의 major/minor 부분이고, `c_rmaj`와 `c_rmin`은 device node reference의 major/minor 부분입니다. `c_namesize`는 마지막 `\0`을 포함한 filename 길이이며, `c_chksum`은 `c_magic`이 `070702`일 때 data field checksum이고 그 외에는 0입니다.

`c_mode`는 Linux의 `stat(2)`가 반환하는 `st_mode` 내용과 일치하며 file type과 permission을 encode합니다. `c_mtime`은 `CONFIG_INITRAMFS_PRESERVE_MTIME=y`가 아니면 무시됩니다.

regular file이나 symlink가 아닌 file의 `c_filesize`는 0이어야 합니다. `c_namesize`는 `PATH_MAX`를 넘지 않는 한 trailing `\0`을 둘 이상 포함할 수 있습니다. 이를 이용해 뒤따르는 file data segment를 filesystem block boundary 같은 정렬 경계에 맞출 수 있습니다.

`c_chksum`은 data field의 모든 byte를 더한 단순 32-bit unsigned sum입니다. `cpio(1)`은 이를 `crc`라고 부르지만 cyclic redundancy check와는 다른, 훨씬 약한 방식입니다. 이름이 부정확해도 실제로 사용하는 algorithm은 이 합계입니다.

filename이 `TRAILER!!!`이면 실제 file이 아니라 end-of-archive marker이며, 이 marker의 `c_filesize`는 반드시 0이어야 합니다.

hard link 처리

directory가 아니면서 `c_nlink > 1`인 entry를 만나면 `(c_maj,c_min,c_ino)` tuple을 tuple buffer에서 찾습니다. tuple이 없으면 buffer에 추가하고 평소처럼 entry를 생성합니다. 이미 있으면 file의 두 번째 copy 대신 hard link를 만듭니다.

file contents의 두 번째 copy를 넣을 필요는 없지만 넣어도 됩니다. contents를 넣지 않으면 뒤에 data section이 없음을 나타내도록 `c_filesize`를 0으로 설정합니다. data가 있으면 앞서 생성된 file instance를 덮어쓰므로, data를 가진 instance는 sequence의 어느 위치에나 올 수 있습니다. GNU cpio는 data를 file의 마지막 instance에만 붙이는 것으로 알려져 있습니다.

symlink에서는 `c_filesize`가 0이면 안 됩니다. `TRAILER!!!` end-of-archive marker를 만나면 tuple buffer를 reset하므로 독립적으로 생성한 archive들을 서로 이어 붙일 수 있습니다.

서로 다른 source의 file data 결합

서로 다른 source의 file data를 `(c_maj,c_min,c_ino)` field 재생성 없이 결합하려면 두 방법 중 하나를 사용합니다.

• 서로 다른 file data source 사이에 `TRAILER!!!` end-of-archive marker를 둡니다.
• 모든 nondirectory entry에서 `c_nlink == 1`이 되도록 보장합니다.