userland.html 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318
  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>Userland | NebOS Architecture</title>
  7. <meta name="description" content="NebOS userland: ring-3 address space, ELF loading, the syscall ABI, the shell and PATH dispatch, the 42-command pack, GUI applications and the browser.">
  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">Filesystems</a>
  25. <a href="graphics.html">Graphics</a>
  26. <a href="network.html">Network</a>
  27. <a href="userland.html" aria-current="page">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">Userland</p>
  34. <h1>Commands are ELFs. The shell is a dispatcher.</h1>
  35. <p class="lede">
  36. Ring-3 programs are freestanding ELFs linked at <code>0x40000000</code>.
  37. The shell resolves a command name against builtins, the per-terminal
  38. PATH and the kernel command registry, then spawns it with one
  39. argument string. The command pack supplies 42 PATH commands by default.
  40. </p>
  41. <div class="meta">
  42. <span class="pill">int 0x80</span>
  43. <span class="pill">one string argument</span>
  44. <span class="pill">42 PATH commands</span>
  45. <span class="pill">8 TTYs · 8 windows</span>
  46. </div>
  47. </div>
  48. <nav class="toc" aria-label="On this page">
  49. <h2>On this page</h2>
  50. <ul>
  51. <li><a href="#model">Ring-3 model</a></li>
  52. <li><a href="#spawn">Spawn path</a></li>
  53. <li><a href="#syscalls">Syscall ABI</a></li>
  54. <li><a href="#shell">Shell &amp; PATH</a></li>
  55. <li><a href="#registry">Kernel commands</a></li>
  56. <li><a href="#pack">Command pack</a></li>
  57. <li><a href="#apps">GUI applications</a></li>
  58. <li><a href="#browser">Browser</a></li>
  59. <li><a href="#sources">Source map</a></li>
  60. </ul>
  61. </nav>
  62. <section id="model">
  63. <h2>Ring-3 model</h2>
  64. <p>
  65. A user process gets a page directory cloned from the kernel identity
  66. map, a 2 MB image/stack window at <code>0x40000000</code>, an optional
  67. 4 MB canvas at <code>0x50000000</code> and a growable heap at
  68. <code>0x60000000</code>. The kernel remains mapped because paging is
  69. identity-mapped; this is isolation in privilege level only, not a
  70. separate address space.
  71. </p>
  72. <ul>
  73. <li><strong>No libc.</strong> Commands include <span class="file">ucmd_lib.h</span> for syscall wrappers and string helpers.</li>
  74. <li><strong>One argument.</strong> The shell passes the raw remainder of the line as a C string at the top of the user stack; <code>_start(const char *arg)</code> needs no crt0.</li>
  75. <li><strong>Inherited context.</strong> Each process inherits the spawning terminal's cwd and TTY id; the file syscalls resolve relative paths against the PCB cwd.</li>
  76. <li><strong>Page-fault policy.</strong> A ring-3 fault kills the process and prints a short message; it does not halt the kernel.</li>
  77. </ul>
  78. <div class="note">
  79. <p><strong>Not a sandbox.</strong> Because physical and virtual addresses
  80. are identical and the kernel is mapped, a ring-3 bug can read or write
  81. any mapped kernel page. The privilege boundary protects against
  82. accidental corruption from ordinary code, not against malicious code.</p>
  83. </div>
  84. </section>
  85. <section id="spawn">
  86. <h2>Spawn path</h2>
  87. <figure class="figure">
  88. <svg viewBox="0 0 920 232" role="img" aria-labelledby="spawn-title spawn-desc">
  89. <title id="spawn-title">Command spawn path</title>
  90. <desc id="spawn-desc">A shell line is matched against builtins, then the PATH, then the kernel registry. A PATH hit loads the ELF through the VFS and creates a ring-3 process; a kernel registry hit spawns a kernel thread.</desc>
  91. <rect class="svg-box" x="20" y="24" width="160" height="58" rx="9"/>
  92. <text class="svg-text" x="38" y="49">shell line</text>
  93. <text class="svg-sub" x="38" y="69">word + remainder</text>
  94. <rect class="svg-box blue" x="216" y="24" width="160" height="58" rx="9"/>
  95. <text class="svg-text" x="234" y="49">builtins</text>
  96. <text class="svg-sub" x="234" y="69">cd · path · help · clear</text>
  97. <rect class="svg-box accent" x="412" y="24" width="180" height="58" rx="9"/>
  98. <text class="svg-text" x="430" y="49">PATH lookup</text>
  99. <text class="svg-sub" x="430" y="69">/ramfs/bin by default</text>
  100. <rect class="svg-box" x="628" y="24" width="270" height="58" rx="9"/>
  101. <text class="svg-text" x="646" y="49">kernel registry</text>
  102. <text class="svg-sub" x="646" y="69">privileged / inline commands</text>
  103. <path class="svg-line" d="M180 53h24"/>
  104. <path class="svg-line" d="M196 47l7 6-7 6"/>
  105. <path class="svg-line" d="M376 53h24"/>
  106. <path class="svg-line" d="M392 47l7 6-7 6"/>
  107. <path class="svg-line" d="M592 53h24"/>
  108. <path class="svg-line" d="M608 47l7 6-7 6"/>
  109. <rect class="svg-box green" x="216" y="146" width="376" height="58" rx="9"/>
  110. <text class="svg-text" x="236" y="171">VFS load → process_create_user</text>
  111. <text class="svg-sub" x="236" y="191">ELF segments · page directory · 8-page stack · arg</text>
  112. <rect class="svg-box amber" x="628" y="146" width="270" height="58" rx="9"/>
  113. <text class="svg-text" x="646" y="171">kernel process</text>
  114. <text class="svg-sub" x="646" y="191">ring 0 · pinned to the BSP</text>
  115. <path class="svg-line accent" d="M502 82v54"/>
  116. <path class="svg-line accent" d="M496 128l6 7 6-7"/>
  117. <path class="svg-line" d="M763 82v54"/>
  118. <path class="svg-line" d="M757 128l6 7 6-7"/>
  119. </svg>
  120. <figcaption>
  121. <strong>A packed command can shadow a kernel command.</strong>
  122. The PATH is searched before the kernel registry, so a new
  123. <code>bin/&lt;name&gt;</code> changes behaviour without editing the
  124. kernel. Builtins are handled inline, before either lookup.
  125. </figcaption>
  126. </figure>
  127. </section>
  128. <section id="syscalls">
  129. <h2>Syscall ABI</h2>
  130. <p>
  131. The gate is <code>int 0x80</code>. <code>eax</code> carries the
  132. number, <code>ebx</code>/<code>ecx</code>/<code>edx</code> the first
  133. three arguments, and the negative <code>SYS_E*</code> codes are
  134. stable. The wrappers in <span class="file">ucmd_lib.h</span> cover
  135. zero to three arguments.
  136. </p>
  137. <div class="table-wrap">
  138. <table>
  139. <thead>
  140. <tr><th>Group</th><th>Numbers</th><th>Purpose</th></tr>
  141. </thead>
  142. <tbody>
  143. <tr><td>Console &amp; time</td><td>1–4, 56, 69</td><td>putstr, ticks, sleep, exit, RTC time/date</td></tr>
  144. <tr><td>Files</td><td>5–11, 48, 98</td><td>whole-file read/write, list, unlink, mkdir/rmdir, mounts, cwd, stat</td></tr>
  145. <tr><td>System info</td><td>12–16, 49–51, 91–92, 102</td><td>memory, E820, mouse, storage, blkdev, procinfo, cursor, CPU temp, sensors, EC</td></tr>
  146. <tr><td>Network</td><td>17–47</td><td>NIC config/acquire, raw frames, DHCP/DNS, TCP client, ARP, cwd</td></tr>
  147. <tr><td>Window &amp; WM</td><td>55, 57–72, 80, 83–87</td><td>key poll, WM attach/info/map/present/create_term, window create/present/input/resize</td></tr>
  148. <tr><td>Process &amp; memory</td><td>73–79, 81, 88–90</td><td>TTY, spawn, alive, kill, chdir, scheduler info, heap alloc/grow/free</td></tr>
  149. <tr><td>TCP server</td><td>93–97, 99–101</td><td>listen, accept, server recv/send/close, peer, speed, MAC set</td></tr>
  150. </tbody>
  151. </table>
  152. </div>
  153. <p>
  154. The file service is whole-file, not stream-oriented. The network
  155. service has a single TCP connection and one NIC owner. There is no
  156. <code>fork</code>, <code>exec</code> or shared memory: a command
  157. either runs as its own process from an ELF or calls a kernel command.
  158. </p>
  159. </section>
  160. <section id="shell">
  161. <h2>Shell &amp; PATH</h2>
  162. <p>
  163. The windowed shell is <span class="file">ucmd_term.c</span>; the
  164. kernel-side <span class="file">terminal.c</span> holds the privileged
  165. command registry used through <code>SYS_SPAWN_KCMD</code>. There is
  166. no kernel terminal fallback; the WM spawns the first terminal once
  167. storage is ready. Each terminal has a current working directory and
  168. a PATH (default <code>/ramfs/bin</code>). Pressing Tab completes
  169. builtin and PATH names; <code>help</code> lists both.
  170. </p>
  171. <ul>
  172. <li><strong>Dispatch order.</strong> Builtins → PATH file → kernel command. A PATH hit loads the ELF through the VFS and spawns it as ring 3.</li>
  173. <li><strong>Builtins.</strong> <code>cd</code>, <code>path</code>, <code>help</code>, <code>clear</code>; the ring-3 shell also handles <code>ps</code> and <code>kill</code> inline. <code>bootlog</code> is a kernel command.</li>
  174. <li><strong>Arguments.</strong> The raw remainder of the line is passed verbatim; commands parse their own flags.</li>
  175. <li><strong>Working directory.</strong> The prompt shows <code>[dir] &gt;</code>; <code>cd</code> changes only the current terminal's cwd, and spawned commands inherit it.</li>
  176. <li><strong>Windows.</strong> A window receives keys through its window key queue (<code>SYS_WIN_KEY_WAIT</code>) or the generic <code>SYS_KEY_POLL</code>; closing the window kills its owner process.</li>
  177. </ul>
  178. </section>
  179. <section id="registry">
  180. <h2>Kernel commands</h2>
  181. <p>
  182. These commands must run in ring 0 or inline in the shell; they are not
  183. files in the pack. The split keeps privileged hardware access out of
  184. ring 3 while most user-facing tools remain replaceable ELFs.
  185. </p>
  186. <div class="table-wrap">
  187. <table>
  188. <thead>
  189. <tr><th>Group</th><th>Commands</th></tr>
  190. </thead>
  191. <tbody>
  192. <tr><td>Shell</td><td><code>cd</code> <code>path</code> <code>help</code> <code>clear</code> <code>bootlog</code></td></tr>
  193. <tr><td>Process / scheduler</td><td><code>ps</code> <code>sched</code> <code>renice</code> <code>kill</code> <code>idle</code> <code>cpufreq</code> <code>power</code></td></tr>
  194. <tr><td>Hardware / debug</td><td><code>display</code> <code>gfxbench</code> <code>lsusb</code> <code>lspci</code> <code>peek</code> <code>poke</code> <code>format</code> <code>dbg</code> <code>serial</code></td></tr>
  195. <tr><td>Network control</td><td><code>netdev</code></td></tr>
  196. <tr><td>Boot / power</td><td><code>reboot</code> <code>poweroff</code> <code>kexec</code></td></tr>
  197. </tbody>
  198. </table>
  199. </div>
  200. </section>
  201. <section id="pack">
  202. <h2>Command pack</h2>
  203. <p>
  204. The pack is built from the <code>UCMDS</code> list in the Makefile as
  205. <code>bin/&lt;name&gt;</code>, plus <code>hello</code> and the real
  206. <code>browser.app</code> and <code>gallery.app</code>. It is mounted
  207. read-only at <code>/ramfs</code>; the shell's default PATH points at
  208. <code>/ramfs/bin</code>.
  209. </p>
  210. <div class="grid">
  211. <div class="card">
  212. <h3>Files &amp; text</h3>
  213. <p><code>ls</code> <code>cat</code> <code>save</code> <code>rm</code> <code>mkdir</code> <code>rmdir</code> <code>edit</code> <code>files</code> <code>view</code></p>
  214. </div>
  215. <div class="card">
  216. <h3>System</h3>
  217. <p><code>cpuinfo</code> <code>meminfo</code> <code>storage</code> <code>top</code> <code>mouseinfo</code> <code>sensors</code> <code>spin</code> <code>clock</code> <code>colors</code></p>
  218. </div>
  219. <div class="card">
  220. <h3>Network</h3>
  221. <p><code>netinfo</code> <code>netip</code> <code>netdns</code> <code>host</code> <code>dhcp</code> <code>ping</code> <code>pong</code> <code>netsend</code> <code>netrecv</code> <code>netlog</code> <code>netconsole</code> <code>netregs</code> <code>netloop</code> <code>netreset</code> <code>net100</code> <code>netmac</code> <code>curl</code> <code>websrv</code></p>
  222. </div>
  223. <div class="card">
  224. <h3>GUI</h3>
  225. <p><code>wm</code> <code>term</code> <code>files</code> <code>view</code> <code>mines</code> <code>solitaire</code> <code>gallery</code> <code>browser</code> <code>clock</code> <code>colors</code></p>
  226. </div>
  227. </div>
  228. <p>
  229. The launchers <code>bin/browser</code> and <code>bin/gallery</code>
  230. forward their argument and cwd, and prefer a development copy under
  231. <code>/share</code> (<code>BROWSER</code> or <code>GALLERY</code>)
  232. before the pack copy and the FAT fallback on <code>root.img</code>.
  233. This lets <code>make browser-dev</code> and <code>make gallery-dev</code>
  234. update an app without rebuilding the pack.
  235. </p>
  236. </section>
  237. <section id="apps">
  238. <h2>GUI applications</h2>
  239. <ul>
  240. <li><strong>files</strong> — browser for the VFS; opens text in <code>edit</code>, images in <code>view</code>, HTML in <code>browser</code>. First user of ngui.</li>
  241. <li><strong>gallery</strong> — live widget and primitive showcase; the real app ships in the pack.</li>
  242. <li><strong>solitaire</strong> — Klondike with drag-and-drop, scoring and a win animation.</li>
  243. <li><strong>mines</strong> — second ngui canvas app; shares the toolkit and event model.</li>
  244. <li><strong>view</strong> — fit/1:1/zoom/pan image viewer, animated GIF playback.</li>
  245. <li><strong>edit</strong> — text editor that draws its own text with the 8x16 font.</li>
  246. <li><strong>clock</strong> / <strong>colors</strong> — small window canvas demos.</li>
  247. <li><strong>wm</strong> / <strong>term</strong> — the ring-3 window manager and terminal launcher used by the desktop.</li>
  248. </ul>
  249. </section>
  250. <section id="browser">
  251. <h2>Browser</h2>
  252. <p>
  253. The real browser is <code>bin/browser.app</code> in the pack. It links
  254. ngui, the image library, inflate, TLS and uhttp. It owns a 960×640
  255. window, a URL bar, history, a status bar and inline images. Network
  256. work runs in a headless <code>curl __fetch</code> helper that writes
  257. the body and metadata under <code>/share</code>, so the UI keeps
  258. drawing and scrolling.
  259. </p>
  260. <ul>
  261. <li><strong>HTML/CSS subset.</strong> External and inline stylesheets, tag/class/id and descendant/child selectors, colours, backgrounds, font size, weights, margins, padding, borders, alignment, percentage widths, basic floats and <code>@media</code> blocks evaluated at a fixed 1000 px viewport.</li>
  262. <li><strong>Not supported.</strong> JavaScript, forms, flex/grid, CSS variables, absolute/fixed positioning, standalone image documents, tables with column widths, video/audio.</li>
  263. <li><strong>Caps.</strong> 2 MB page body, 832 KB CSS, 6144 DOM nodes, 2304 rules, 16 images; images are downscaled to at most 1000 px wide and decoded into a 24 MB shared arena.</li>
  264. <li><strong>Fetching.</strong> Each network fetch starts a one-shot helper process and a fresh TCP/TLS connection; images load one per loop within the viewport plus 160 px.</li>
  265. </ul>
  266. <p>
  267. The browser's default canvas is dark, matching the ngui theme. Pages
  268. that set dark text but rely on a white default background can be hard
  269. to read; pages with their own full background and colour rules are
  270. unaffected. See <a href="graphics.html#images">Graphics → Image
  271. library</a> for the decoder limits.
  272. </p>
  273. </section>
  274. <section id="sources">
  275. <h2>Source map</h2>
  276. <ul class="filelist">
  277. <li><code>syscall.c</code>, <code>syscall_stub.S</code>, <code>syscall.h</code></li>
  278. <li><code>process.c</code> — ELF load and spawn</li>
  279. <li><code>elf.c</code> — ELF parser</li>
  280. <li><code>ucmd_term.c</code> — windowed shell, scrollback, PATH</li>
  281. <li><code>terminal.c</code> — privileged kernel command registry</li>
  282. <li><code>ucmd_lib.h</code> — user shim</li>
  283. <li><code>ucmd.ld</code> — ring-3 link address</li>
  284. <li><code>Makefile</code> — <code>UCMDS</code> and pack rules</li>
  285. <li><code>ucmd_*.c</code> — commands</li>
  286. <li><code>browser.c</code>, <code>browser_html.c</code>, <code>gallery.c</code></li>
  287. </ul>
  288. </section>
  289. </main>
  290. <footer class="site-footer">
  291. <div class="inner">
  292. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  293. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  294. </div>
  295. </footer>
  296. </body>
  297. </html>