filesystems.html 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470
  1. <!doctype html>
  2. <html lang="en">
  3. <head>
  4. <meta charset="utf-8">
  5. <meta name="viewport" content="width=device-width, initial-scale=1">
  6. <title>Storage &amp; Filesystems | NebOS Architecture</title>
  7. <meta name="description" content="NebOS filesystems: the VFS fs_ops layer, FAT12/16/32, the command-pack ramfs pipeline, the writable /share and persistent /data filesystems, and the WebDAV view of the VFS.">
  8. <link rel="icon" href="favicon.svg" type="image/svg+xml">
  9. <link rel="stylesheet" href="style.css">
  10. </head>
  11. <body>
  12. <a class="skip" href="#main">Skip to content</a>
  13. <header class="site-header">
  14. <a class="brand" href="index.html">
  15. <span class="brand-mark" aria-hidden="true"></span>
  16. <span>NebOS <span class="brand-sub">Architecture</span></span>
  17. </a>
  18. <nav class="site-nav" aria-label="Architecture sections">
  19. <a href="index.html">Overview</a>
  20. <a href="boot.html">Boot</a>
  21. <a href="memory.html">Memory</a>
  22. <a href="cpu.html">CPU</a>
  23. <a href="drivers.html">Drivers</a>
  24. <a href="filesystems.html" aria-current="page">Filesystems</a>
  25. <a href="graphics.html">Graphics</a>
  26. <a href="network.html">Network</a>
  27. <a href="userland.html">Userland</a>
  28. <a href="development.html">Development</a>
  29. </nav>
  30. </header>
  31. <main id="main" class="page">
  32. <div class="page-head">
  33. <p class="kicker">Storage &amp; filesystems</p>
  34. <h1>One VFS, three very different backends.</h1>
  35. <p class="lede">
  36. The kernel keeps filesystem policy thin: a mount table and an
  37. <code>fs_ops</code> vtable. FAT provides persistent read/write storage,
  38. the command-pack ramfs is a read-only system image, and
  39. <code>/share</code> is a writable RAM filesystem for network uploads;
  40. an installed disk adds a persistent FAT data volume at
  41. <code>/data</code>.
  42. </p>
  43. <div class="meta">
  44. <span class="pill">FAT12/16/32</span>
  45. <span class="pill">read-only ramfs</span>
  46. <span class="pill">/share · 16 MB</span>
  47. <span class="pill">/data · persistent</span>
  48. <span class="pill">WebDAV</span>
  49. </div>
  50. </div>
  51. <nav class="toc" aria-label="On this page">
  52. <h2>On this page</h2>
  53. <ul>
  54. <li><a href="#vfs">VFS layer</a></li>
  55. <li><a href="#fat">FAT</a></li>
  56. <li><a href="#ramfs">ramfs &amp; the command pack</a></li>
  57. <li><a href="#share">/share</a></li>
  58. <li><a href="#data">/data</a></li>
  59. <li><a href="#disks">Storage manager &amp; mount policies</a></li>
  60. <li><a href="#sysfs">File service ABI</a></li>
  61. <li><a href="#webdav">WebDAV</a></li>
  62. <li><a href="#capacity">Capacity chart</a></li>
  63. <li><a href="#limits">Limits</a></li>
  64. <li><a href="#sources">Source map</a></li>
  65. </ul>
  66. </nav>
  67. <section id="vfs">
  68. <h2>VFS layer</h2>
  69. <p>
  70. <span class="file">vfs.c</span> mounts every detected FAT device under
  71. <code>/</code>, keeps the two memory filesystems available throughout
  72. the boot scan, and dispatches file operations through
  73. <code>struct fs_ops</code>. The shell, the file service and the
  74. WebDAV server never call <code>fat_*</code> directly.
  75. </p>
  76. <figure class="figure">
  77. <svg viewBox="0 0 920 330" role="img" aria-labelledby="vfs-title vfs-desc">
  78. <title id="vfs-title">VFS and filesystem backends</title>
  79. <desc id="vfs-desc">The shell, sys_fs and WebDAV use the VFS mount table, which dispatches to FAT, ramfs or share through fs_ops. FAT sits on the block-device registry.</desc>
  80. <rect class="svg-box blue" x="30" y="30" width="200" height="60" rx="9"/>
  81. <text class="svg-text" x="50" y="56">shell / commands</text>
  82. <text class="svg-sub" x="50" y="76">ls, cat, save, files</text>
  83. <rect class="svg-box blue" x="255" y="30" width="200" height="60" rx="9"/>
  84. <text class="svg-text" x="275" y="56">sys_fs · WebDAV</text>
  85. <text class="svg-sub" x="275" y="76">ring-3 file service</text>
  86. <rect class="svg-box accent" x="485" y="30" width="200" height="60" rx="9"/>
  87. <text class="svg-text" x="505" y="56">vfs.c</text>
  88. <text class="svg-sub" x="505" y="76">mount table · fs_ops</text>
  89. <path class="svg-line blue" d="M230 60h18"/>
  90. <path class="svg-line blue" d="M240 54l7 6-7 6"/>
  91. <path class="svg-line blue" d="M455 60h23"/>
  92. <path class="svg-line blue" d="M470 54l7 6-7 6"/>
  93. <rect class="svg-box green" x="712" y="30" width="180" height="60" rx="9"/>
  94. <text class="svg-text" x="732" y="56">directory cache</text>
  95. <text class="svg-sub" x="732" y="76">last 64 FAT entries</text>
  96. <path class="svg-line accent" d="M685 60h20"/>
  97. <path class="svg-line accent" d="M697 54l7 6-7 6"/>
  98. <rect class="svg-box" x="30" y="150" width="200" height="64" rx="9"/>
  99. <text class="svg-text" x="50" y="176">FAT12/16/32</text>
  100. <text class="svg-sub" x="50" y="196">read + write · 8.3 names</text>
  101. <rect class="svg-box" x="255" y="150" width="200" height="64" rx="9"/>
  102. <text class="svg-text" x="275" y="176">ramfs</text>
  103. <text class="svg-sub" x="275" y="196">read-only · command pack</text>
  104. <rect class="svg-box" x="485" y="150" width="200" height="64" rx="9"/>
  105. <text class="svg-text" x="505" y="176">/share</text>
  106. <text class="svg-sub" x="505" y="196">writable · RAM only</text>
  107. <rect class="svg-box" x="30" y="252" width="200" height="58" rx="9"/>
  108. <text class="svg-text" x="50" y="277">block devices</text>
  109. <text class="svg-sub" x="50" y="297">floppy · ide · sata</text>
  110. <path class="svg-line" d="M585 90v28"/>
  111. <path class="svg-line" d="M130 118h455"/>
  112. <path class="svg-line" d="M130 118v24"/>
  113. <path class="svg-line" d="M355 118v24"/>
  114. <path class="svg-line" d="M585 118v24"/>
  115. <path class="svg-line" d="M124 143l6 7 6-7"/>
  116. <path class="svg-line" d="M349 143l6 7 6-7"/>
  117. <path class="svg-line" d="M579 143l6 7 6-7"/>
  118. <path class="svg-line" d="M130 214v26"/>
  119. <path class="svg-line" d="M124 240l6 7 6-7"/>
  120. </svg>
  121. <figcaption>
  122. <strong>Same operations, different storage.</strong> Each backend
  123. implements read, load/release, stat, write, unlink, mkdir, rmdir and
  124. index-based directory listing. Paths passed to the backend are
  125. relative to the mount; the VFS has already normalised them.
  126. </figcaption>
  127. </figure>
  128. <p>
  129. <code>vfs_resolve()</code> drops <code>.</code> components, collapses
  130. and trims slashes, and resolves <code>..</code> against the mount.
  131. The shell's working directory is per-process and inherited across
  132. commands, so relative paths keep working after <code>cd</code>.
  133. </p>
  134. </section>
  135. <section id="fat">
  136. <h2>FAT</h2>
  137. <p>
  138. <span class="file">fat.c</span> supports FAT12, FAT16 and FAT32 on
  139. any registered block device. It reads the BPB, validates the media
  140. byte and mounts partitions as separate entries such as
  141. <code>ide0p1</code>, <code>sata0p2</code> or <code>usb0p1</code>.
  142. USB mass-storage devices are registered by
  143. <span class="file">usbmsc.c</span> and mount exactly like an
  144. internal disk; the <code>install</code> command is separate and
  145. clones raw image sectors without parsing FAT.
  146. </p>
  147. <ul>
  148. <li><strong>Read/write.</strong> Read, write, delete, mkdir and rmdir are implemented; FAT32 allocation uses an FSInfo-seeded free-cluster hint.</li>
  149. <li><strong>8.3 names.</strong> The on-disk name is the canonical one. The shell and <code>files</code> display the space-padded form; a long name cannot be created.</li>
  150. <li><strong>Directory cache.</strong> The last FAT directory's first 64 entries are cached in <code>vfs.c</code>, so WebDAV's index sequence is one walk instead of N. Any write invalidates the cache.</li>
  151. <li><strong>Serialization.</strong> A file operation runs in a non-preemptible section because the FAT driver has static state and the floppy needs IRQ 6; <code>vfs_scan_busy</code>/<code>format_busy</code> make it sleep first while a mount scan or a format owns the disks. A format releases the BKL for its raw-sector loop, and only disk-backed mounts wait for it, so <code>/ramfs</code> and <code>/share</code> stay usable. A rescan (the <code>bootscan</code> thread or the <code>storage</code> command) re-adds <code>/ramfs</code>/<code>/share</code> first and is skipped by their operations too (<code>vfs_mount_is_ram</code>); it runs preemptible, and the floppy/ATA/AHCI/SDHCI wait loops (including the SDHCI command and CMD1 power-up polls) call <code>vfs_scan_poll</code>/<code>vfs_scan_relax</code>, which sleep (dropping the BKL) once a wait passes 2 ms and only for the scan's owning process. A USB disk read by the rescan claims the USB bus (<code>usb_bus_claim()</code>), so its host-controller waits yield too; <code>storage</code> no longer freezes the WM. The floppy probe is skipped for a drive whose CMOS type (register <code>0x10</code>) is 0.</li>
  152. <li><strong>Mount scan.</strong> <code>mount_device()</code> recognises the NebOS MBR layout (<code>mbr_is_nebos_layout()</code>: active type-0x06 P1 at LBA 63 of 1024 sectors, P2 at LBA 1088) and skips P1 without reading it, so the boot stick costs only its MBR read. A valid MBR whose partitions are all non-FAT is not probed as a superfloppy, and an unreadable partition boot sector is skipped rather than mounted as FAT. The boot scan calls <code>vfs_mount_all(1)</code>, which logs USB devices as <code>deferred</code>; <code>vfs_mount_usb()</code> appends them after the bootscan window has closed, so a card reader that NAKs its first read for seconds cannot delay the other mounts or the desktop. The background pass is best-effort: one 5 s first read without the reset/retry chain (<code>usbmsc_set_probe_only</code>). The <code>storage</code> command's rescan still does the full scan (<code>vfs_mount_all(0)</code>) with the normal 15 s first-read deadline and retries.</li>
  153. </ul>
  154. <p>
  155. <span class="file">fatdetect.c</span> and <span class="file">fatformat.c</span>
  156. back the <code>format</code> command. A disk can be formatted in
  157. binary units (<code>format ide0 100mb</code>, <code>1gb</code>) or
  158. whole-disk; the Chromebook eMMC is <code>format mmc0</code>.
  159. </p>
  160. <div class="warn">
  161. <p><strong>FAT32 limits.</strong> The FSInfo free-count is not updated,
  162. and a completely full FAT32 directory is not grown: new cluster
  163. allocation for directories is not implemented.</p>
  164. </div>
  165. </section>
  166. <section id="ramfs">
  167. <h2>ramfs &amp; the command pack</h2>
  168. <p>
  169. The system root is a compressed command pack, not a disk image. Every
  170. ring-3 command is a static ELF linked at <code>0x40000000</code>,
  171. packed as <code>bin/&lt;name&gt;</code>, gzipped and wrapped in a
  172. one-sector <code>NBROOT1</code> header. At boot the path loads the
  173. pack into RAM and <span class="file">ramfs.c</span> inflates it into a
  174. private page-allocated copy mounted read-only at <code>/ramfs</code>.
  175. The whole-buffer helpers in <span class="file">inflate.c</span>
  176. (<code>inflate_gzip_mem</code> and friends, also used by the image
  177. decoders) decode with 10-bit Huffman lookup tables straight into the
  178. output buffer and checksum once at the end, about five times faster
  179. than the bit-at-a-time streaming decoder that HTTP bodies still use.
  180. </p>
  181. <figure class="figure">
  182. <svg viewBox="0 0 920 312" role="img" aria-labelledby="pack-title pack-desc">
  183. <title id="pack-title">Command pack build and boot pipeline</title>
  184. <desc id="pack-desc">ucmd ELFs are packed by mkpack, gzipped, wrapped by mkrootfs, loaded by the boot path into RAM, then inflated by ramfs_init and mounted at /ramfs.</desc>
  185. <rect class="svg-box" x="20" y="26" width="150" height="64" rx="9"/>
  186. <text class="svg-text" x="40" y="52">ucmd_*.c</text>
  187. <text class="svg-sub" x="40" y="72">42 UCMDS + 3 app ELFs</text>
  188. <rect class="svg-box" x="196" y="26" width="150" height="64" rx="9"/>
  189. <text class="svg-text" x="216" y="52">mkpack</text>
  190. <text class="svg-sub" x="216" y="72">NBPAK1 · bin/name</text>
  191. <rect class="svg-box" x="372" y="26" width="150" height="64" rx="9"/>
  192. <text class="svg-text" x="392" y="52">gzip -12</text>
  193. <text class="svg-sub" x="392" y="72">cmds_pack_gz.bin</text>
  194. <rect class="svg-box" x="548" y="26" width="150" height="64" rx="9"/>
  195. <text class="svg-text" x="568" y="52">mkrootfs</text>
  196. <text class="svg-sub" x="568" y="72">NBROOT1 header</text>
  197. <rect class="svg-box green" x="724" y="26" width="174" height="64" rx="9"/>
  198. <text class="svg-text" x="744" y="52">boot path</text>
  199. <text class="svg-sub" x="744" y="72">pack_addr / pack_size</text>
  200. <path class="svg-line" d="M170 58h16"/>
  201. <path class="svg-line" d="M180 52l7 6-7 6"/>
  202. <path class="svg-line" d="M346 58h16"/>
  203. <path class="svg-line" d="M356 52l7 6-7 6"/>
  204. <path class="svg-line" d="M522 58h16"/>
  205. <path class="svg-line" d="M532 52l7 6-7 6"/>
  206. <path class="svg-line green" d="M698 58h16"/>
  207. <path class="svg-line green" d="M708 52l7 6-7 6"/>
  208. <rect class="svg-box" x="390" y="150" width="170" height="64" rx="9"/>
  209. <text class="svg-text" x="410" y="176">ramfs_init</text>
  210. <text class="svg-sub" x="410" y="196">inflate + validate</text>
  211. <rect class="svg-box accent" x="620" y="150" width="200" height="64" rx="9"/>
  212. <text class="svg-text" x="640" y="176">/ramfs</text>
  213. <text class="svg-sub" x="640" y="196">read-only · bin/command</text>
  214. <path class="svg-line green" d="M810 90v40h-335v20"/>
  215. <path class="svg-line green" d="M469 142l6 7 6-7"/>
  216. <path class="svg-line" d="M560 182h52"/>
  217. <path class="svg-line" d="M606 176l7 6-7 6"/>
  218. <text class="svg-tiny" x="20" y="272">Runtime replacement: KXNP packs replace /ramfs in place.</text>
  219. <text class="svg-tiny" x="20" y="290">Existing processes keep their loaded ELFs.</text>
  220. </svg>
  221. <figcaption>
  222. <strong>The pack is the root filesystem.</strong> The kernel no
  223. longer embeds it, so command growth does not move <code>_end</code>.
  224. The high-memory legacy loader caps the compressed pack at 1 MB;
  225. the 8 MB rootfs partition and ramfs cap remain the larger limits.
  226. </figcaption>
  227. </figure>
  228. <div class="table-wrap">
  229. <table>
  230. <thead>
  231. <tr><th>Container</th><th>Format</th><th>Purpose</th></tr>
  232. </thead>
  233. <tbody>
  234. <tr><td><code>cmds.pack</code></td><td><code>NBPAK1</code></td><td>Raw command archive: <code>bin/&lt;name&gt;</code> entries.</td></tr>
  235. <tr><td><code>cmds_pack_gz.bin</code></td><td>gzip</td><td>Compressed pack; <code>libdeflate-gzip -12</code> when available.</td></tr>
  236. <tr><td><code>rootfs.bin</code></td><td><code>NBROOT1</code> + gzip</td><td>Floppy append (header + pack).</td></tr>
  237. <tr><td><code>cmds.img</code></td><td><code>NBROOT1</code> padded to 8 MB</td><td>USB rootfs partition image.</td></tr>
  238. <tr><td><code>rootfs-full.bin</code></td><td><code>NBROOT1</code> + full gzip</td><td>Network persistent-install payload.</td></tr>
  239. <tr><td><code>/share</code></td><td>RAM entries</td><td>Writable upload target; not part of the pack.</td></tr>
  240. <tr><td><code>/data</code></td><td>FAT32/16, label <code>NEBOSDATA</code></td><td>Partition 4 on the installed disk; persistent user files.</td></tr>
  241. </tbody>
  242. </table>
  243. </div>
  244. <p>
  245. The pack build is part of the normal Makefile. Add a
  246. <code>user/apps/&lt;name&gt;/ucmd_&lt;name&gt;.c</code> and its name to
  247. <code>UCMDS</code> and the pack,
  248. the mount and the PATH listing pick it up automatically. Runtime
  249. replacement uses <code>make cmds-dev</code> or
  250. <code>make net-cmds</code> and validates the pack before swapping it.
  251. </p>
  252. </section>
  253. <section id="share">
  254. <h2>/share</h2>
  255. <p>
  256. <span class="file">share.c</span> is a writable, page-backed in-memory
  257. filesystem for network uploads. It matters on boards with no writable
  258. disk, or when the only writable medium is a floppy. Entries are full
  259. relative paths plus explicit directory entries, so empty directories
  260. work; names are plain strings up to 63 bytes.
  261. </p>
  262. <ul>
  263. <li><strong>Limits.</strong> 64 entries and 16 MB total, allocated as pages and freed on replace/delete.</li>
  264. <li><strong>Volatile.</strong> A reboot or kexec starts empty.</li>
  265. <li><strong>Mount point.</strong> <code>/share</code>, listed by <code>ls /</code> and visible in <code>files</code>.</li>
  266. <li><strong>Writable by anyone on the LAN.</strong> The WebDAV server has no authentication.</li>
  267. </ul>
  268. </section>
  269. <section id="data">
  270. <h2>/data</h2>
  271. <p>
  272. The installer creates a fourth partition after the 8 MB ESP and
  273. formats it as FAT with the label <code>NEBOSDATA</code>. It fills
  274. the rest of the disk and is mounted at <code>/data</code>; the VFS
  275. recognises the label in the FAT boot sector, not the device name, so
  276. the path is stable on <code>mmc0</code>, <code>sata0</code> or
  277. <code>ide0</code>.
  278. </p>
  279. <ul>
  280. <li><strong>Persistent.</strong> A reinstall or <code>install &lt;target&gt; self</code> replaces the OS partitions (P1 kernel, P2 rootfs pack, P3 ESP) and keeps P4. <code>net-install</code> writes only P1/P2.</li>
  281. <li><strong>First install is destructive.</strong> Creating P4 formats the rest of the target disk; an existing <code>NEBOSDATA</code> volume is detected and left untouched.</li>
  282. <li><strong>8.3 names.</strong> The FAT driver creates and reads short names only; long names need VFAT LFN write support.</li>
  283. <li><strong>WiFi credentials.</strong> A successful WiFi connect adds the network to a most-recently-used list of up to 16 SSID/passphrase records in <code>WIFI.CFG</code>; the boot-time <code>wifi autoconnect</code> helper scans and joins the strongest saved network it finds. <code>wifi saved</code> lists them and <code>wifi forget [ssid]</code> removes one. The file is plaintext and 8.3, like the rest of the volume.</li>
  284. <li><strong>Chat session.</strong> The Chat client stores its server and session cookie in <code>CHAT.CFG</code> when this volume is mounted; without it the client falls back to the RAM-only <code>/share/chat.cfg</code>. The cookie is a bearer credential, and the password is never stored.</li>
  285. <li><strong>Fixed start.</strong> P4 starts at LBA 34816. A BIOS-only install leaves the space between P2 and P4 unpartitioned, and a later disk clone does not resize P4.</li>
  286. <li><strong>Mount settings.</strong> The <code>disks</code> app saves the mount policies in <code>MOUNTS.CFG</code>; the boot scan applies them (see below).</li>
  287. <li><strong>No fsck.</strong> Like the other FAT mounts, the volume has no journal, repair tool or permissions; it is writable by every process.</li>
  288. </ul>
  289. </section>
  290. <section id="disks">
  291. <h2>Storage manager &amp; mount policies</h2>
  292. <p>
  293. <code>disks</code> (<span class="file">ucmd_disks.c</span>, also the
  294. start menu's <em>Disks</em> entry and the <em>Disks</em> button in
  295. <code>files</code>) is the ngui front end to
  296. storage; <code>storage</code> stays the text view. It lists every
  297. present block device (<code>SYS_BLKDEV</code>), reads sector 0 and
  298. each partition's first sector through <code>SYS_BLK_READ</code>
  299. (119) to show the MBR, the NebOS boot partition, the rootfs, FAT
  300. types and labels, and shows all mounts with their source volume.
  301. Floppies are never read raw (no media means seconds of retries).
  302. </p>
  303. <ul>
  304. <li><strong>Mount policies.</strong> <code>SYS_MOUNT_CTL</code> (120) sets or reads a <code>struct sys_mount_policy</code>: a mount name, <code>SYS_MOUNT_RO</code> and <code>SYS_MOUNT_NOAUTO</code>, keyed by the volume's default name (<code>ide0p1</code>, or <code>usb0</code>/<code>floppy1</code> for a whole-device volume). <span class="file">vfs.c</span> keeps up to 16 in RAM; <code>mount_one()</code> honours them on every scan and a set remounts the device at once. Names are 1–15 of <code>[a-z0-9_-]</code>; <code>ramfs</code>/<code>share</code> are refused and a name already in use falls back to the default.</li>
  305. <li><strong>Read-only.</strong> Write, unlink, mkdir and rmdir on a mount with <code>ro</code> set return <code>SYS_EROFS</code> before reaching the backend (this also covers the ramfs).</li>
  306. <li><strong>Persistence.</strong> The app writes the table to <code>MOUNTS.CFG</code> on the <code>NEBOSDATA</code> volume (<code>"NBMNT1\n\0"</code> then the records); the <code>bootscan</code> thread reads <code>/data/MOUNTS.CFG</code> after <code>vfs_mount_all()</code> and applies it. Without <code>/data</code> the settings last until reboot. The data volume itself cannot be edited, since it stores the file.</li>
  307. <li><strong>Format and install.</strong> The app confirms in its own dialog, then runs <code>format -y &lt;dev&gt; [size]</code> or <code>install -y &lt;dev&gt; [self]</code> through <code>SYS_SPAWN_KCMD</code> on a private tty and shows the output; <code>-y</code> skips the commands' raw-keyboard y/n prompt. An installed disk offers <em>Update</em> (<code>self</code>) and <em>Reinstall</em> (clone), a blank one <em>Install</em>.</li>
  308. </ul>
  309. </section>
  310. <section id="sysfs">
  311. <h2>File service ABI</h2>
  312. <p>
  313. Ring-3 commands use <code>SYS_READ_FILE</code>,
  314. <code>SYS_WRITE_FILE</code>, <code>SYS_LIST_DIR</code>,
  315. <code>SYS_LIST_MOUNTS</code>, <code>SYS_UNLINK</code>,
  316. <code>SYS_MKDIR</code>, <code>SYS_RMDIR</code>,
  317. <code>SYS_FS_STAT</code> and <code>SYS_GETCWD</code>; the storage
  318. manager adds <code>SYS_BLK_READ</code> and
  319. <code>SYS_MOUNT_CTL</code>. <code>struct sys_mount</code> carries the
  320. source device and the volume key.
  321. <span class="file">sys_fs.c</span> validates the path, resolves it
  322. against the caller's cwd, calls the VFS and maps backend errors to
  323. the stable <code>SYS_E*</code> values.
  324. </p>
  325. <p>
  326. The file service reads whole files, not streams. The shell loads an
  327. ELF through <code>vfs_load_file</code> and spawns it; FAT ELFs are
  328. loaded through <code>kmalloc</code> under <code>sys_fs_enter/exit</code>,
  329. since the floppy needs IRQ 6.
  330. </p>
  331. <p>
  332. Directory entries carry a 64-byte display name plus <code>raw_83</code>,
  333. so FAT's space-padded names and the string-named memory filesystems
  334. share one ABI.
  335. </p>
  336. </section>
  337. <section id="webdav">
  338. <h2>WebDAV</h2>
  339. <p>
  340. <span class="file">websrv</span> is a ring-3 HTTP/1.1 + WebDAV server
  341. built on the kernel TCP listener. It serves the VFS:
  342. <code>/</code> lists mounts, <code>/ramfs</code> is read-only, FAT
  343. mounts accept only names that round-trip to 8.3, and
  344. <code>/share</code> and <code>/data</code> are the writable
  345. targets (RAM and persistent respectively).
  346. </p>
  347. <ul>
  348. <li><strong>Concurrency.</strong> One active connection plus a small backlog (three backlog/closing slots in the current TCP server). Parallel clients queue with a zero window until the active request finishes.</li>
  349. <li><strong>Bodies.</strong> Whole-file buffering, 4 MB normally and 1 MB when the heap cannot provide the larger buffer. A larger PUT gets 413.</li>
  350. <li><strong>Methods.</strong> GET, PUT, DELETE, MKCOL, PROPFIND and MOVE to the extent described; directory <code>MOVE</code> is 501 and <code>PROPPATCH</code> is answered 200 without persisting.</li>
  351. <li><strong>No auth.</strong> This is a trusted-LAN service; <code>/share</code> is writable by anyone who can reach it.</li>
  352. </ul>
  353. <p>
  354. The WebDAV server still takes the raw NIC lease, so it is mutually
  355. exclusive with packet-level commands and with TCP client connections
  356. (<code>curl</code> and the browser workers). Starting
  357. <code>websrv</code> while another raw owner exists fails; TCP clients
  358. fail to connect while it owns the receiver.
  359. </p>
  360. </section>
  361. <section id="capacity">
  362. <h2>Capacity chart</h2>
  363. <figure class="figure">
  364. <div class="bars" role="img" aria-label="Capacity limits: /share 16 MB, ramfs decompressed pack 8 MB, USB rootfs image 8 MB, current legacy compressed pack about 1.3 MB. Bar widths are relative to 16 MB.">
  365. <div class="bar-row">
  366. <span class="bar-label">/share</span>
  367. <div class="bar-track"><span class="bar-fill green" style="--w:100%"></span></div>
  368. <span class="bar-value">16 MB</span>
  369. </div>
  370. <div class="bar-row">
  371. <span class="bar-label">ramfs (inflated)</span>
  372. <div class="bar-track"><span class="bar-fill" style="--w:50%"></span></div>
  373. <span class="bar-value">8 MB</span>
  374. </div>
  375. <div class="bar-row">
  376. <span class="bar-label">rootfs image</span>
  377. <div class="bar-track"><span class="bar-fill blue" style="--w:50%"></span></div>
  378. <span class="bar-value">8 MB</span>
  379. </div>
  380. <div class="bar-row">
  381. <span class="bar-label">legacy pack</span>
  382. <div class="bar-track"><span class="bar-fill" style="--w:8.1%"></span></div>
  383. <span class="bar-value">~1.3 MB</span>
  384. </div>
  385. </div>
  386. <figcaption>
  387. <strong>Different limits for different paths.</strong> The legacy
  388. boot stage's compressed-pack cap is much smaller than the 8 MB
  389. ramfs cap; UEFI and kexec avoid the low-gap bottleneck.
  390. </figcaption>
  391. </figure>
  392. </section>
  393. <section id="limits">
  394. <h2>Limits</h2>
  395. <ul>
  396. <li><strong>Whole-file service.</strong> Commands read a complete file into memory; there is no stream API for general files.</li>
  397. <li><strong>FAT names.</strong> No long filename creation or lookup. WebDAV refuses names that cannot be represented exactly in 8.3.</li>
  398. <li><strong>ramfs is read-only.</strong> Writes return <code>SYS_EROFS</code>; use <code>/share</code> for volatile data and <code>/data</code> for persistent files.</li>
  399. <li><strong>Pack volatile at runtime.</strong> Runtime pack replacement is RAM only; a cold boot uses the flashed rootfs.</li>
  400. <li><strong>Directory listing cache.</strong> Only the first 64 entries of the last FAT directory are cached; a very large directory still costs a walk.</li>
  401. </ul>
  402. </section>
  403. <section id="sources">
  404. <h2>Source map</h2>
  405. <ul class="filelist">
  406. <li><code>kernel/vfs.c</code>, <code>kernel/vfs.h</code> — mounts and dispatch</li>
  407. <li><code>kernel/fat.c</code>, <code>kernel/fat.h</code> — FAT12/16/32</li>
  408. <li><code>kernel/ramfs.c</code>, <code>kernel/ramfs.h</code> — pack inflate</li>
  409. <li><code>kernel/share.c</code>, <code>kernel/share.h</code> — /share</li>
  410. <li><code>kernel/sys_fs.c</code> — ring-3 file service, raw sector read, mount policies and <code>MOUNTS.CFG</code> loader</li>
  411. <li><code>user/apps/disks/ucmd_disks.c</code> — storage manager app</li>
  412. <li><code>tools/mkpack.c</code>, <code>tools/mkrootfs.c</code>, <code>include/rootfs.h</code></li>
  413. <li><code>common/inflate.c</code> — DEFLATE/gzip</li>
  414. <li><code>user/apps/websrv/ucmd_websrv.c</code> — HTTP/WebDAV</li>
  415. <li><code>kernel/fatdetect.c</code>, <code>kernel/fatformat.c</code> — format</li>
  416. <li><code>kernel/usbmsc.c</code>, <code>kernel/usbmsc.h</code> — USB mass-storage block devices</li>
  417. <li><code>kernel/install.c</code>, <code>kernel/install.h</code> — clone, self-update and net-install writer</li>
  418. <li><code>include/rootfs.h</code> — installed image geometry and NBROOT1 header</li>
  419. </ul>
  420. </section>
  421. </main>
  422. <footer class="site-footer">
  423. <div class="inner">
  424. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  425. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  426. </div>
  427. </footer>
  428. </body>
  429. </html>