bsd

docs/freebsd_freebsd-src.md

@@ -0,0 +1,149 @@
+---
+curatedRepoId: freebsd-src-15.1
+owner: freebsd
+repo: freebsd-src
+revision: aadd58dddcbc78f4d5594827b46b5633552b15ce
+guideId: freebsd-kernel-guide
+name: FreeBSD Kernel In The Mind
+description: Understanding the FreeBSD kernel inside the full source tree
+defaultOpenIds:
+  - ch1
+  - ch2
+  - ch3
+  - ch4
+  - ch5
+---
+
+# FreeBSD Kernel In The Mind
+
+FreeBSD is best read as a whole operating system whose kernel lives under `sys/` but is built, configured, installed, and documented from the same source tree as userland. This guide follows the kernel-facing paths first, then connects them back to release and build structure.
+
+---
+id: ch1
+title: Chapter 1 — The Kernel Tree
+fileRecommendations:
+  readingOrder:
+    - path: README.md
+      description: Top-level source roadmap for the full FreeBSD tree
+      type: docs
+    - path: sys/README.md
+      description: Kernel source roadmap and directory overview
+      type: docs
+    - path: sys/conf/files
+      description: Kernel build manifest that maps source files into configurations
+      type: source
+    - path: sys/conf/options
+      description: Kernel option definitions used by config files and subsystem code
+      type: source
+    - path: sys/amd64/conf/GENERIC
+      description: Representative amd64 kernel configuration
+      type: source
+---
+
+The FreeBSD kernel is concentrated in `sys/`, but the tree is not a standalone library. Kernel configuration, boot loaders, release scripts, and userland tools live beside it. That shape matters: FreeBSD ships as a base system, so kernel interfaces and userland consumers evolve together.
+
+Start with `sys/README.md` and then read the configuration files. `sys/conf/files` tells you which compilation units belong to the kernel, while `sys/conf/options` records tunables that conditionally expose behavior across subsystems. A platform config such as `sys/amd64/conf/GENERIC` shows how those pieces become a bootable kernel.
+
+---
+id: ch2
+title: Chapter 2 — Boot And Kernel Entry
+fileRecommendations:
+  readingOrder:
+    - path: stand/man/loader.8
+      description: Loader manual covering the pre-kernel boot environment
+      type: docs
+    - path: sys/amd64/amd64/locore.S
+      description: Early amd64 assembly entry path
+      type: source
+    - path: sys/kern/init_main.c
+      description: Kernel initialization and the first process path
+      type: source
+    - path: sys/kern/kern_linker.c
+      description: Kernel linker and module loading support
+      type: source
+    - path: sys/sys/kernel.h
+      description: SYSINIT ordering and kernel initialization declarations
+      type: docs
+---
+
+FreeBSD boot begins outside `sys/`, in the loader code under `stand/`. The loader prepares the kernel image, modules, environment, and metadata. Once architecture entry code has control, kernel startup becomes a sequence of ordered initializers rather than one single main routine.
+
+`SYSINIT` is the central contract. Subsystems register initialization functions with ordering constraints, and `sys/kern/init_main.c` drives the transition from early kernel state to process creation. This makes the boot path extensible without forcing every subsystem into a hand-written call chain.
+
+---
+id: ch3
+title: Chapter 3 — Processes, Threads, And Scheduling
+fileRecommendations:
+  readingOrder:
+    - path: sys/sys/proc.h
+      description: Process and thread structures visible across the kernel
+      type: docs
+    - path: sys/kern/kern_proc.c
+      description: Process lookup, lifecycle support, and procfs-facing helpers
+      type: source
+    - path: sys/kern/kern_fork.c
+      description: fork() implementation and process creation
+      type: source
+    - path: sys/kern/kern_exit.c
+      description: Process exit and wait semantics
+      type: source
+    - path: sys/kern/sched_ule.c
+      description: ULE scheduler implementation
+      type: source
+---
+
+FreeBSD separates process identity from runnable execution. `struct proc` holds process-level state such as credentials, signal disposition, and relationships. `struct thread` is the schedulable unit. Reading `sys/sys/proc.h` first gives you the vocabulary used by fork, exec, sleep, wakeup, and scheduler code.
+
+The ULE scheduler in `sys/kern/sched_ule.c` is the default scheduling implementation for common configurations. It turns thread state into CPU placement decisions, balancing responsiveness, affinity, interactivity, and multiprocessor load.
+
+---
+id: ch4
+title: Chapter 4 — Memory And Filesystems
+fileRecommendations:
+  readingOrder:
+    - path: sys/vm/vm_map.c
+      description: Virtual address map management
+      type: source
+    - path: sys/vm/vm_fault.c
+      description: Page fault handling and object lookup
+      type: source
+    - path: sys/kern/vfs_subr.c
+      description: Shared VFS object and vnode support
+      type: source
+    - path: sys/kern/vfs_syscalls.c
+      description: Filesystem-facing syscall implementations
+      type: source
+    - path: sys/sys/vnode.h
+      description: Vnode structure and VFS contracts
+      type: docs
+---
+
+The VM and VFS subsystems are where FreeBSD's kernel becomes a resource manager. VM tracks address spaces, faults, objects, and page residency. VFS gives filesystems a common vnode interface so UFS, ZFS integration, pseudo-filesystems, and device-backed paths can participate in common syscalls.
+
+Read the fault path and vnode path together. A memory-mapped file crosses both systems: VM resolves address faults, while VFS supplies file-backed objects and coherency rules. The boundary is technical, but the runtime behavior is shared.
+
+---
+id: ch5
+title: Chapter 5 — Networking And Drivers
+fileRecommendations:
+  readingOrder:
+    - path: sys/net/if.c
+      description: Network interface lifecycle and common interface operations
+      type: source
+    - path: sys/netinet/tcp_subr.c
+      description: TCP subsystem support and initialization
+      type: source
+    - path: sys/dev/pci/pci.c
+      description: PCI bus enumeration and device attachment
+      type: source
+    - path: sys/kern/subr_bus.c
+      description: Newbus device model core
+      type: source
+    - path: sys/sys/bus.h
+      description: Device and driver method interfaces
+      type: docs
+---
+
+FreeBSD's driver model is built around newbus. Buses enumerate children, drivers probe and attach, and devices expose methods through shared kernel interfaces. `sys/kern/subr_bus.c` is the generic machinery; bus families such as PCI specialize the discovery and resource allocation path.
+
+Networking follows the same kernel style: common interfaces, protocol-specific state machines, and subsystem initialization glue. The interface layer in `sys/net/if.c` is the useful starting point because every protocol and driver eventually meets it.

docs/ghostbsd_ghostbsd-src.md

@@ -0,0 +1,119 @@
+---
+curatedRepoId: ghostbsd-src
+owner: ghostbsd
+repo: ghostbsd-src
+revision: b3f9cf4fa7f35fa8b084353e0dff0aa4799fc542
+guideId: ghostbsd-kernel-guide
+name: GhostBSD Kernel In The Mind
+description: Understanding GhostBSD as a FreeBSD-derived desktop source tree
+defaultOpenIds:
+  - ch1
+  - ch2
+  - ch3
+  - ch4
+---
+
+# GhostBSD Kernel In The Mind
+
+GhostBSD is a FreeBSD-derived operating system with desktop-oriented defaults. Its kernel reading path starts in the same places as FreeBSD, but the interesting question is how a downstream system carries source changes, device defaults, and integration choices.
+
+---
+id: ch1
+title: Chapter 1 — A Downstream BSD Tree
+fileRecommendations:
+  readingOrder:
+    - path: README.md
+      description: Top-level FreeBSD-derived source tree roadmap
+      type: docs
+    - path: sys/README.md
+      description: Kernel source directory guide
+      type: docs
+    - path: sys/conf/files
+      description: Kernel build file manifest
+      type: source
+    - path: sys/conf/options
+      description: Kernel option definitions
+      type: source
+    - path: sys/amd64/conf/GENERIC
+      description: Representative amd64 kernel configuration
+      type: source
+---
+
+GhostBSD keeps the recognizable FreeBSD source layout. That means `sys/` remains the center for kernel work, while `stand/`, `sbin/`, `etc/`, and the rest of userland provide the base-system context around it.
+
+For kernel exploration, start by treating it as a FreeBSD tree and then look for downstream policy. Configuration defaults, device enablement, and desktop-facing integration points usually tell you more about GhostBSD than low-level rewrites do.
+
+---
+id: ch2
+title: Chapter 2 — Boot And Init
+fileRecommendations:
+  readingOrder:
+    - path: stand/man/loader.8
+      description: Loader manual covering the pre-kernel boot environment
+      type: docs
+    - path: sys/kern/init_main.c
+      description: Kernel initialization sequence
+      type: source
+    - path: sys/sys/kernel.h
+      description: SYSINIT declarations and ordering
+      type: docs
+    - path: sbin/sysctl/sysctl.conf
+      description: Base sysctl defaults carried by the GhostBSD source tree
+      type: source
+---
+
+The boot path is still FreeBSD-shaped: loader first, architecture entry next, then ordered kernel initialization. `SYSINIT` keeps initialization distributed while preserving dependency order.
+
+GhostBSD-specific behavior often appears as configuration rather than a new kernel architecture. `sbin/sysctl/sysctl.conf` is a compact example: it records system defaults that affect runtime kernel behavior without changing subsystem code.
+
+---
+id: ch3
+title: Chapter 3 — Kernel Services
+fileRecommendations:
+  readingOrder:
+    - path: sys/sys/proc.h
+      description: Process and thread structures
+      type: docs
+    - path: sys/kern/kern_fork.c
+      description: Process creation path
+      type: source
+    - path: sys/kern/sched_ule.c
+      description: ULE scheduler implementation
+      type: source
+    - path: sys/vm/vm_fault.c
+      description: Page fault handling
+      type: source
+    - path: sys/kern/vfs_subr.c
+      description: VFS shared vnode machinery
+      type: source
+---
+
+The core kernel services are inherited from the same BSD design: processes and threads, virtual memory, scheduling, and VFS. Read these files as the stable substrate GhostBSD relies on rather than as a separate desktop layer.
+
+The important downstream reading habit is comparison. When a desktop distribution changes defaults, enables hardware support, or packages a different experience, the kernel core may remain close to upstream while the operating system behavior changes substantially.
+
+---
+id: ch4
+title: Chapter 4 — Devices And Desktop Hardware
+fileRecommendations:
+  readingOrder:
+    - path: sys/kern/subr_bus.c
+      description: Device model core
+      type: source
+    - path: sys/sys/bus.h
+      description: Driver and bus method interfaces
+      type: docs
+    - path: sys/dev/pci/pci.c
+      description: PCI bus enumeration
+      type: source
+    - path: sys/dev/usb/usb_hid.c
+      description: USB HID support
+      type: source
+    - path: sbin/sysctl/sysctl.conf
+      description: Runtime setting enabling the newer USB HID path
+      type: source
+---
+
+Desktop operating systems live or die on hardware behavior. GhostBSD's kernel tree exposes the same newbus and driver structure as FreeBSD, but downstream defaults can decide which support paths are active for users.
+
+The USB HID setting in `sbin/sysctl/sysctl.conf` is a good example of distribution-level kernel policy. It does not replace the driver stack; it chooses a runtime posture for modern input devices.

docs/nextbsd-redux_nextbsd-kernel.md

@@ -0,0 +1,101 @@
+---
+curatedRepoId: nextbsd-kernel
+owner: nextbsd-redux
+repo: nextbsd-kernel
+revision: dcfa0cda0600d7ecce6216adcc7d8b31982ef702
+guideId: nextbsd-kernel-guide
+name: NextBSD Kernel In The Mind
+description: Understanding NextBSD as a kernel patch and configuration layer
+defaultOpenIds:
+  - ch1
+  - ch2
+  - ch3
+  - ch4
+---
+
+# NextBSD Kernel In The Mind
+
+NextBSD's kernel repository is not a full forked `src` tree. It is a disciplined patch, overlay, configuration, and CI layer on top of a FreeBSD kernel source base. Read it as a record of intentional differences.
+
+---
+id: ch1
+title: Chapter 1 — Patch Layer, Not Fork
+fileRecommendations:
+  readingOrder:
+    - path: README.md
+      description: Repository purpose, layout, and build workflow
+      type: docs
+    - path: patches/README.md
+      description: Patch workflow and contribution rules
+      type: docs
+    - path: patches/series
+      description: Ordered patch list applied to the FreeBSD kernel base
+      type: source
+    - path: config/NEXTBSD
+      description: Kernel configuration used for NextBSD builds
+      type: source
+---
+
+The most important design choice is that NextBSD records kernel changes as patches and overlays rather than carrying a full rewritten source import. `patches/series` is therefore the table of contents for kernel behavior changes.
+
+This style makes the delta legible. Each patch can explain the upstream context, the local policy, and the risk of divergence. `config/NEXTBSD` then shows how the resulting kernel is built into a named configuration.
+
+---
+id: ch2
+title: Chapter 2 — Configuration As Identity
+fileRecommendations:
+  readingOrder:
+    - path: config/NEXTBSD
+      description: Kernel configuration and identity
+      type: source
+    - path: README.md
+      description: Build trigger and artifact overview
+      type: docs
+    - path: ci
+      description: Continuous-integration support directory
+      type: source
+---
+
+Kernel identity is partly source code and partly configuration. The `NEXTBSD` config includes the upstream kernel shape but gives the build its own identity and policy surface.
+
+The CI files matter because this repository builds against a prepared FreeBSD source base. That turns kernel maintenance into a repeatable overlay operation: update the base, apply the patch series, build the configured kernel, then publish artifacts for downstream image assembly.
+
+---
+id: ch3
+title: Chapter 3 — Kernel Policy Patches
+fileRecommendations:
+  readingOrder:
+    - path: patches/0008-NextBSD-enable-unprivileged-mounts-vfs-usermount-1.patch
+      description: NextBSD policy patch for unprivileged mounts
+      type: source
+    - path: patches/0009-NextBSD-default-elf64-fallback_brand-to-ELFOSABI_LINU.patch
+      description: NextBSD policy patch for ELF64 Linux fallback branding
+      type: source
+    - path: patches/series
+      description: Ordering context for policy patches
+      type: source
+---
+
+Some NextBSD kernel changes are not new subsystems; they are policy decisions made persistent in the kernel because the rest of the operating system is intentionally not stock FreeBSD.
+
+The unprivileged mount and ELF branding patches show this clearly. Both are small in code size but large in operating-system behavior. They encode defaults that would otherwise live in FreeBSD rc scripts, sysctl configuration, or local administrator setup.
+
+---
+id: ch4
+title: Chapter 4 — Overlays And Integration
+fileRecommendations:
+  readingOrder:
+    - path: src-overlay
+      description: Source overlay directory applied on top of the base
+      type: source
+    - path: patches/series
+      description: Patch ordering before overlays and build
+      type: source
+    - path: README.md
+      description: Relationship between kernel build, object artifact, and module builds
+      type: docs
+---
+
+The overlay directory is the other half of the patch story. Patches modify existing base files; overlays can add or replace source paths as part of the kernel build input.
+
+For exploration, keep three layers separate in your head: the upstream FreeBSD source base, the ordered patch series, and the overlay/config/build workflow. NextBSD kernel behavior is the result of all three, not any single file.