Commit 1b8490b223e5d0403bed51011cb240656e997a78
Commits[COMMIT BEGIN]commit 1b8490b223e5d0403bed51011cb240656e997a78 Author: 0x4248 <[email protected]> Date: Thu Mar 19 23:57:23 2026 +0000 linux-ref: add content diff --git a/doc/linux-ref/Makefile b/doc/linux-ref/Makefile index 049d138..b96e95c 100644 --- a/doc/linux-ref/Makefile +++ b/doc/linux-ref/Makefile @@ -1,122 +1,65 @@ -PANDOC ?= pandoc -SRC_DIR ?= docs -BUILD_DIR ?= build -TITLE ?= 4248's Linux Reference Manual -#PDF_ENGINE ?= $(shell for e in tectonic xelatex lualatex pdflatex weasyprint prince; do \ -# command -v $$e >/dev/null 2>&1 && { echo $$e; break; }; done) - -PDF_ENGINE = xelatex -CSS := $(SRC_DIR)/assets/style.css -FRONT_MATTER := $(SRC_DIR)/index.md -CHAPTERS := $(sort $(shell find $(SRC_DIR)/chapters -type f -name '*.md')) -BOOK_SOURCES := $(FRONT_MATTER) $(CHAPTERS) - -# Per-chapter HTML: docs/chapters/XX-name.md -> build/html/chapters/XX-name.html -CHAPTER_HTMLS := $(patsubst $(SRC_DIR)/chapters/%.md,$(BUILD_DIR)/html/chapters/%.html,$(CHAPTERS)) - -HTML_INDEX := $(BUILD_DIR)/html/index.html -PDF_OUT := $(BUILD_DIR)/pdf/manual.pdf - -.PHONY: help all docs htmldocs pdfdocs cleandocs clean check-pandoc check-pdf-engine listdocs - -# ── Help ───────────────────────────────────────────────────────────────────── -help: - @echo "Targets:" - @echo " make htmldocs - Build per-chapter HTML manual" - @echo " make pdfdocs - Build PDF manual (new page per chapter)" - @echo " override engine: make pdfdocs PDF_ENGINE=xelatex" - @echo " make docs - Build both" - @echo " make listdocs - Show input source files" - @echo " make cleandocs - Remove generated output" - -all: docs -docs: htmldocs pdfdocs - -# ── Dependency checks ───────────────────────────────────────────────────────── -check-pandoc: - @command -v $(PANDOC) >/dev/null 2>&1 || { \ - echo "error: pandoc is not installed"; exit 1; \ - } - -check-pdf-engine: - @test -n "$(PDF_ENGINE)" || { \ - echo "error: no PDF engine found"; \ - echo "install one of: tectonic, xelatex, lualatex, pdflatex, weasyprint, prince"; \ - echo "or specify: make pdfdocs PDF_ENGINE=xelatex"; \ - exit 1; \ - } - @command -v $(PDF_ENGINE) >/dev/null 2>&1 || { \ - echo "error: PDF engine '$(PDF_ENGINE)' is not installed"; \ - echo "specify another: make pdfdocs PDF_ENGINE=xelatex"; \ - exit 1; \ - } - -listdocs: - @printf '%s\n' $(BOOK_SOURCES) - -# ── HTML: one file per chapter ──────────────────────────────────────────────── -# -# Each chapter is built as a self-contained HTML file (CSS embedded inline) -# so the output in build/html/chapters/ is portable with no external deps. - -$(BUILD_DIR)/html/chapters/%.html: $(SRC_DIR)/chapters/%.md $(CSS) | check-pandoc - @mkdir -p $(dir $@) - $(PANDOC) $< \ - --standalone \ - --embed-resources \ - --toc \ - --number-sections \ - --metadata title="$(TITLE)" \ - --css=$(CSS) \ - -o $@ - -# Index page: intro content + auto-generated chapter listing -$(HTML_INDEX): $(FRONT_MATTER) $(CHAPTERS) $(CSS) | check-pandoc - @mkdir -p $(dir $@) - @{ \ - cat $(FRONT_MATTER); \ - echo ""; \ - echo "## Chapters"; \ - for f in $(CHAPTERS); do \ - rel=$${f#$(SRC_DIR)/chapters/}; \ - base=$${rel%.md}; \ - title=$$(grep -m1 '^# ' $$f | sed 's/^# //'); \ - echo "- [$$title](chapters/$$base.html)"; \ +PANDOC ?= pandoc +BUILDDIR = build +CSS = docs/_static/whitepaper.css +TITLE = The 0x4248 Linux Reference Manual +SUBTITLE = For x86-64 Systems +HTMLDIR = $(BUILDDIR)/html + +CHAPTERS = $(sort $(shell find docs/chapters -name '*.md')) + +CHAPTER_HTMLS = $(patsubst docs/chapters/%.md,$(HTMLDIR)/chapters/%.html,$(CHAPTERS)) +HTML_INDEX = $(HTMLDIR)/index.html + +.PHONY: html pdf docs pdfdocs clean + +html: $(HTML_INDEX) $(CHAPTER_HTMLS) + +pdf: $(BUILDDIR)/manual.pdf + +$(BUILDDIR): + mkdir -p $(BUILDDIR) + +$(HTMLDIR): + mkdir -p $(HTMLDIR) + +$(HTMLDIR)/chapters/%.html: docs/chapters/%.md | $(HTMLDIR) + mkdir -p $(dir $@) + $(PANDOC) --standalone --embed-resources --metadata title='$(TITLE)' --metadata subtitle='$(SUBTITLE)' --css=$(CSS) -o $@ $< + +$(HTML_INDEX): $(CHAPTERS) $(CHAPTER_HTMLS) | $(HTMLDIR) + { \ + echo '# $(TITLE)'; \ + echo ''; \ + echo '## Contents'; \ + echo ''; \ + for file in $(CHAPTERS); do \ + rel=$${file#docs/chapters/}; \ + link=$${rel%.md}.html; \ + title=$$(grep -m1 '^# ' $$file | sed 's/^# //'); \ + if [ -z "$$title" ]; then title=$$rel; fi; \ + echo "- [$$title](chapters/$$link)"; \ done; \ - } | $(PANDOC) \ - --standalone \ - --embed-resources \ - --metadata title="$(TITLE)" \ - --css=$(CSS) \ - -o $@ - -htmldocs: $(HTML_INDEX) $(CHAPTER_HTMLS) - @echo "HTML built: $(BUILD_DIR)/html/" + } | $(PANDOC) --standalone --embed-resources --metadata title='$(TITLE)' --metadata subtitle='$(SUBTITLE)' --css=$(CSS) -o $@ -# ── PDF: new page per chapter ───────────────────────────────────────────────── -# -# --top-level-division=chapter maps each top-level # heading to a LaTeX -# \chapter{}, which starts a new page in the 'report' document class. - -$(PDF_OUT): $(BOOK_SOURCES) | check-pandoc check-pdf-engine - @mkdir -p $(dir $@) - $(PANDOC) $(BOOK_SOURCES) \ - --toc \ - --number-sections \ - --top-level-division=chapter \ - --metadata title="$(TITLE)" \ +$(BUILDDIR)/manual.pdf: $(CHAPTERS) | $(BUILDDIR) + $(PANDOC) --toc --top-level-division=chapter \ -V documentclass=report \ + -V papersize=a4 \ + -V fontsize=11pt \ -V geometry:margin=1in \ - -V colorlinks=true \ - -V linkcolor=blue \ - --pdf-engine=$(PDF_ENGINE) \ - -o $@ - -pdfdocs: $(PDF_OUT) - @echo "PDF built: $(PDF_OUT)" - -# ── Cleanup ─────────────────────────────────────────────────────────────────── -cleandocs: - rm -rf $(BUILD_DIR)/html $(BUILD_DIR)/pdf - -clean: cleandocs + -V fontfamily=tgtermes \ + --metadata title='$(TITLE)' \ + --metadata subtitle='$(SUBTITLE)' \ + -o $(BUILDDIR)/_content.pdf $(CHAPTERS) + @if [ -f cover.pdf ]; then \ + pdfunite cover.pdf $(BUILDDIR)/_content.pdf $@ && rm $(BUILDDIR)/_content.pdf; \ + else \ + mv $(BUILDDIR)/_content.pdf $@; \ + fi + +docs: html + +pdfdocs: pdf + +clean: + rm -rf $(BUILDDIR) diff --git a/doc/linux-ref/README.md b/doc/linux-ref/README.md deleted file mode 100644 index 66ee78a..0000000 --- a/doc/linux-ref/README.md +++ /dev/null @@ -1,41 +0,0 @@ -# 4248's Linux Reference Manual - -Minimal Pandoc generator with Linux-kernel-style Make targets: - -- `make htmldocs` -- `make pdfdocs` - -## Prerequisites - -- `pandoc` -- For PDF output: Pandoc uses a PDF engine backend (auto-detected: `tectonic`, `xelatex`, `lualatex`, `pdflatex`, `wkhtmltopdf`, `weasyprint`, or `prince`) - -## Layout - -- `docs/index.md` front matter and introduction -- `docs/chapters/**/*.md` chapter files (recursively discovered, built in lexicographic order) -- `build/html/index.html` generated HTML -- `build/pdf/manual.pdf` generated PDF - -## Usage - -```bash -make htmldocs -make pdfdocs -make pdfdocs PDF_ENGINE=xelatex -make docs # both -make cleandocs -``` - -If your preferred engine is installed, you can force it via `PDF_ENGINE`. - -## Add new chapters - -Create files under `docs/chapters/` with numeric prefixes for stable ordering, for example: - -- `docs/chapters/02-processes-and-scheduling.md` -- `docs/chapters/03-memory-management.md` -- `docs/chapters/bash/10-bash-overview.md` -- `docs/chapters/bash/20-expansions.md` - -The `Makefile` auto-discovers these files recursively and preserves subfolders in HTML output, for example `build/html/chapters/bash/10-bash-overview.html`. diff --git a/doc/linux-ref/docs/_static/whitepaper.css b/doc/linux-ref/docs/_static/whitepaper.css new file mode 100644 index 0000000..1729450 --- /dev/null +++ b/doc/linux-ref/docs/_static/whitepaper.css @@ -0,0 +1,35 @@ +body { + font-family: "Times New Roman", Times, serif; + line-height: 1.65; + background: #ffffff; + color: #111111; +} + +div.body { + max-width: 48rem; +} + +h1, h2, h3, h4, h5, h6 { + font-family: "Times New Roman", Times, serif; + font-weight: 600; +} + +h1 { + break-before: page; + page-break-before: always; +} + +h1:first-of-type { + break-before: auto; + page-break-before: auto; +} + +p { + text-align: justify; +} + +code, +pre, +tt { + font-family: "Liberation Mono", "DejaVu Sans Mono", monospace; +} diff --git a/doc/linux-ref/docs/assets/style.css b/doc/linux-ref/docs/assets/style.css deleted file mode 100644 index 003eee0..0000000 --- a/doc/linux-ref/docs/assets/style.css +++ /dev/null @@ -1,23 +0,0 @@ -body { - font-family: serif; - font-size: 11pt; - background: #fff; - color: #111; - max-width: 860px; - margin: 0 auto; - padding: 3rem 2rem; - line-height: 1.6; -} - -h1, h2, h3, h4, h5, h6 { - font-family: serif; - font-weight: bold; - color: #000; - margin-top: 2.2rem; - margin-bottom: 0.5rem; - line-height: 1.3; -} -h1 { font-size: 2rem; border-bottom: 2px solid #b9b9b9; padding-bottom: 0.3em; text-align: center; } -h2 { font-size: 1.35rem; border-bottom: 1px solid #999; padding-bottom: 0.2em; } -h3 { font-size: 1.1rem; } -h4, h5, h6 { font-size: 1rem; } diff --git a/doc/linux-ref/docs/chapters/00-frontmatter/01-intro.md b/doc/linux-ref/docs/chapters/00-frontmatter/01-intro.md new file mode 100644 index 0000000..bd9e4c3 --- /dev/null +++ b/doc/linux-ref/docs/chapters/00-frontmatter/01-intro.md @@ -0,0 +1,66 @@ +# Introduction + +Welcome to the 0x4248 Linux Reference Manual. This manual is a very technical +Linux Reference for practitioners working close to kernel internals, user-space +interfaces, and Linux system behavior. + +**This is NOT a beginner's manual.** + +If you are new to Linux, I strongly +recommend starting with a more beginner-friendly resource, such as the +[Linux Journey](https://linuxjourney.com/) or +[The Linux Command Line](http://linuxcommand.org/tlcl.php). Although this manual + is not intended for beginners, there may be some beginner-friendly sections, +but this is mostly scarce and more of a quick reminder for practitioners. + +## Architecture + +This manual will primarialy focus on IBM-PC compatible computers using the +x86-64 architecture, as this is the most common architecture for Linux. +This manual may also go into older systems; such as i386, i486, and i686; and +may rarely cover ARM, SPARC, PowerPC. + +### System I am using for examples in this manual + +I will be using a standard QEMU x86-64 virtual machine with Arch Linux. Arch +Linux is good for this because it very minimal and allows easy configuration and +customization. Unlike Ubuntu and Mint with its many pre-installed packages and +services. + +I am also doing this in a virtual machine because it allows me to revert changes +easily. + +### HTML + +If you are reading this manual online, you are likely reading the HTML version. +The HTML is split into multiple files, with one file per chapter. +This allows for faster loading for people on slower lines such as dial-up or +mobile telephone data connections. Check the `contents.html` file for the full +list of chapters. + +I have also made it so the HTML version does not require JavaScript or intense +CSS to work, users using netscape navigator 4.0, Internet Explorer 5.0, and +even Lynx should be able to read this manual without much issue. + +### PDF + +PDF is a single file format almost exactly like the print version. + +### Print + +Print versions of this manual may be available for purchase for a low cost. + +**Why?** + +This manual is CC BY-SA licensed, which means you are free to share and adapt +the material for any purpose, even commercially, as long as you give appropriate +credit, provide a link to the license, and indicate if changes were made. + +Therefore, print versions are at a low cost to cover printing, shipping, and +contributions to help develop the manual further. + +### Updates and Errata +This manual is also a continuously evolving work in progress. I will be adding +more content over time, and if you have purchased this manual in print it may be +outdated by the time you receive it. However, you can always access the latest +version of the manual online. diff --git a/doc/linux-ref/docs/chapters/00-frontmatter/02-license.md b/doc/linux-ref/docs/chapters/00-frontmatter/02-license.md new file mode 100644 index 0000000..7b9a295 --- /dev/null +++ b/doc/linux-ref/docs/chapters/00-frontmatter/02-license.md @@ -0,0 +1,27 @@ +# License + +The 0x4248 Linux Reference Manual is licensed under the Creative Commons +Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0). + +Adaptation of the manual for commercial purposes is allowed under this license, +as long as you give appropriate credit, provide a link to the license, and +indicate if changes were made. + +## Copyright + +Copyright (c) 2024 by 0x4248. CC BY-SA 4.0 License applies to all content in +this manual, including text, images, and other media. + +## Credits + +### Authors and Contributors + +- 0x4248 (Main Author and Maintainer) + +### Acknowledgments + +- [Linux Kernel Documentation](https://www.kernel.org/doc/html/latest/) +- [Arch Wiki](https://wiki.archlinux.org/) +- [Linux From Scratch](http://www.linuxfromscratch.org/) +- [syscall.sh](https://syscall.sh/) +- [man7.org](https://man7.org/) \ No newline at end of file diff --git a/doc/linux-ref/docs/chapters/01-kernel/01-the_kernel.md b/doc/linux-ref/docs/chapters/01-kernel/01-the_kernel.md new file mode 100644 index 0000000..ce2077e --- /dev/null +++ b/doc/linux-ref/docs/chapters/01-kernel/01-the_kernel.md @@ -0,0 +1,60 @@ +# The Linux Kernel + +This section will cover the Linux Kernel. In this chapter, we will look at +the Linux kernel branches, how to build, and an overview of common issues and +topics related to the kernel. Then we will look at other topics such as the +kernel's boot process and its command line parameters. + +## The /boot Directory + +If you open this directory, you should see three important files: + +- `vmlinuz-<version>`: This is the compressed Linux kernel image. +- `initramfs-<version>.img`: This is the initial RAM filesystem image. +- `initrd.img-<version>`: This is the initial RAM disk image. This is a legacy + format that is mostly unused now, but some older systems may still use it. + +Here is what my `/boot/` directory looks like: + +```bash +[root@arch boot]# ls -l +total 24916 +drwxr-xr-x 6 root root 4096 Mar 19 19:50 grub +-rwxr-xr-x 1 root root 9038759 Mar 19 19:50 initramfs-linux.img +-rwxr-xr-x 1 root root 16466432 Mar 19 19:50 vmlinuz-linux +[root@arch boot]# +``` + +### Vmlinuz + +**V**irtual **M**emory **LINU**x g**Z**ip. This is the compressed Linux kernel +image. When the system boots, the bootloader loads this image into memory and +decompresses it to start the operating system. + +### RAM Disks + +A RAM disk is a virtual disk that resides in the system's RAM. It is used during +the boot process to provide a temporary root filesystem before the actual root +filesystem is mounted. This allows the kernel to load necessary drivers and +modules. This is because things like controller drivers for disks and other +devices may not work without the RAM disk. + +#### Types of RAM Disks + +- **initramfs**: This is the modern format for the initial RAM filesystem. It is + a compressed cpio archive that is loaded into memory and used as the initial + root filesystem during boot. +- **initrd**: This is the older format for the initial RAM disk. + +Linux supports these compressions on the kernel and initramfs images: +- gzip +- bzip2 +- xz +- lzma +- lzop +- lz4 +- zstd + +**Note**: The kernel cant load the initramfs if it is compressed with a +compression algorithm that the kernel has not been compiled with support for. +Ensure you enable support for the compression algorithm using `menuconfig`. \ No newline at end of file diff --git a/doc/linux-ref/docs/index.md b/doc/linux-ref/docs/index.md deleted file mode 100644 index 90d629f..0000000 --- a/doc/linux-ref/docs/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: 4248's Linux Reference Manual -subtitle: Systems and Kernel-Oriented Linux Documentation -author: "0x4248" -date: 2026-03-18 ---- - -# About This Manual - -This manual is a technical Linux reference aimed at practitioners working close to the kernel, user space internals, and system interfaces. - -It is not a beginner tutorial. It is a reference-oriented corpus for answering questions such as: - -- What does this device file represent? -- Which syscall or procfs node backs this behavior? -- Which subsystem owns this interface? - -# Reading Strategy - -Use this document as: - -- a jump table for subsystem-specific deep dives, -- a glossary-backed source of Linux interface details, -- and a cross-reference between user space artifacts and kernel internals.[COMMIT END](C) 2025 0x4248 (C) 2025 4248 Media and 4248 Systems, All part of 0x4248 See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.