[docs] Add sphinx documentation
Add a first pass at documentation with sphinx.
This commit is contained in:
Justin C. Miller
1
.gitignore
vendored
1
.gitignore
vendored
@@ -16,3 +16,4 @@ compile_commands.json
|
||||
buddy_allocs.txt
|
||||
frame_allocs.txt
|
||||
heap_allocs.txt
|
||||
/docs/_build
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
# An ``event`` is a simple synchronization object. It contains up to 64 signals
|
||||
# that threads can wait for and signal in parallel.
|
||||
|
||||
object event : object {
|
||||
uid f441e03da5516b1a
|
||||
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# The base type of all kernel-exposed objects
|
||||
# All kernel-exposed objects inherit from the base ``object`` type, so the
|
||||
# ``object`` syscalls can be used with any object's handle.
|
||||
|
||||
object object [virtual] {
|
||||
uid 667f61fb2cd57bb4
|
||||
cname kobject
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
import "objects/object.def"
|
||||
|
||||
# Processes are a collection of handles and a virtual memory
|
||||
# space inside which threads are run.
|
||||
# A ``process`` object represents a process running on the system, and allows
|
||||
# control over the threads, handles, and virtual memory space of that process.
|
||||
|
||||
object process : object {
|
||||
uid 0c69ee0b7502ba31
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
# The system object represents a handle to kernel functionality
|
||||
# needed by drivers and other priviledged services
|
||||
# The singular ``system`` object represents a handle to kernel functionality
|
||||
# needed by drivers and other priviledged services.
|
||||
|
||||
object system : object {
|
||||
uid fa72506a2cf71a30
|
||||
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
# A ``thread`` object represents a thread of execution within a process running
|
||||
# on the system. The actual thread does not need to be currently running to
|
||||
# hold a handle to it.
|
||||
|
||||
object thread : object {
|
||||
uid 11f23e593d5761bd
|
||||
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
import "objects/process.def"
|
||||
|
||||
# A ``vma`` object represents a single virtual memory area, which may be shared
|
||||
# between several processes. A process having a handle to a ``vma`` does not
|
||||
# necessarily mean that it is mapped into that process' virtual memory space.
|
||||
|
||||
object vma : object {
|
||||
uid d6a12b63b3ed3937
|
||||
cname vm_area
|
||||
|
||||
22
docs/Makefile
Normal file
22
docs/Makefile
Normal file
@@ -0,0 +1,22 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
ROOTDIR = $(SOURCEDIR)/..
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
PYTHONPATH=$(ROOTDIR)/scripts cog -r -D definitions_path=$(ROOTDIR)/definitions -c syscall_interface.rst
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
254
docs/_static/custom.css
vendored
Normal file
254
docs/_static/custom.css
vendored
Normal file
@@ -0,0 +1,254 @@
|
||||
/* custom.css - jsix version */
|
||||
|
||||
:root {
|
||||
--background-color: #181820;
|
||||
--link-color: #7070e0;
|
||||
--link-hover-color: #9090ff;
|
||||
--text-color: #3d3d3d;
|
||||
--text-literal-color: #d26a98;
|
||||
}
|
||||
.wy-nav-side {
|
||||
background: var(--background-color);
|
||||
}
|
||||
|
||||
@media screen and (min-width: 1100px) {
|
||||
.wy-nav-content-wrap {
|
||||
background: var(--background-color);
|
||||
}
|
||||
}
|
||||
|
||||
a {
|
||||
color: var(--link-color);
|
||||
}
|
||||
|
||||
a:hover {
|
||||
color: var(--link-hover-color);
|
||||
}
|
||||
|
||||
a:visited {
|
||||
color: var(--link-color);
|
||||
}
|
||||
|
||||
.rst-content {
|
||||
color: var(--text-color);
|
||||
}
|
||||
|
||||
.rst-content code.literal {
|
||||
color: var(--text-literal-color);
|
||||
}
|
||||
|
||||
.rst-content tt.literal {
|
||||
color: var(--text-literal-color);
|
||||
}
|
||||
|
||||
.rst-content .note {
|
||||
color: #003274;
|
||||
background: #ccddf3;
|
||||
padding: 1rem;
|
||||
margin-bottom: 1rem;
|
||||
}
|
||||
|
||||
.rst-content .note .admonition-title {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.rst-content .warning {
|
||||
color: #605000;
|
||||
background: #fcf4cc;
|
||||
padding: 1rem;
|
||||
margin-bottom: 1rem;
|
||||
}
|
||||
|
||||
.rst-content .warning .admonition-title {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.rst-content .highlight {
|
||||
background: #f5f5f5;
|
||||
}
|
||||
|
||||
.wy-side-scroll {
|
||||
background-color: var(--background-color);
|
||||
}
|
||||
|
||||
.wy-side-nav-search {
|
||||
background-color: var(--background-color);
|
||||
}
|
||||
|
||||
.wy-side-nav-search input[type="text"] {
|
||||
width: 100%;
|
||||
border-radius: 0px;
|
||||
padding: 6px 12px;
|
||||
border-color: var(--background-color);
|
||||
}
|
||||
|
||||
.wy-menu-vertical a {
|
||||
font-size: 100%;
|
||||
color: #d9d9d9;
|
||||
padding-top: 0.6rem;
|
||||
padding-bottom: 0.6rem;
|
||||
background-color: inherit;
|
||||
}
|
||||
|
||||
.wy-menu-vertical a:hover {
|
||||
background-color: unset;
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.current > a {
|
||||
background-color: var(--background-color);
|
||||
color: white;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.current > a span.toctree-expand {
|
||||
display: block;
|
||||
font-size: inherit;
|
||||
line-height: inherit;
|
||||
color: inherit;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.current > a span.toctree-expand:before {
|
||||
display: block;
|
||||
font-size: inherit;
|
||||
line-height: inherit;
|
||||
color: inherit;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.current > a span.toctree-expand:hover {
|
||||
color: white;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.current > a:hover {
|
||||
background-color: var(--background-color);
|
||||
color: white;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.current > a:hover span.toctree-expand {
|
||||
color: white;
|
||||
}
|
||||
|
||||
.wy-menu-vertical .toctree-l1 {
|
||||
opacity: 0.5;
|
||||
}
|
||||
|
||||
.wy-menu-vertical .toctree-l1:hover {
|
||||
opacity: 1;
|
||||
background-color: inherit;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l1.current {
|
||||
opacity: 1;
|
||||
background-color: inherit;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l1.current > a {
|
||||
border: 0px;
|
||||
}
|
||||
|
||||
.wy-menu-vertical .toctree-l2:hover {
|
||||
background-color: #566673;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l2.current > a {
|
||||
background-color: #566673;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a {
|
||||
background-color: #e4e7ea;
|
||||
color: #838383;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a:hover {
|
||||
color: var(--text-color);
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a:hover span.toctree-expand {
|
||||
color: var(--text-color);
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l2.current li.toctree-l3.current > a {
|
||||
color: var(--text-color);
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l2 a {
|
||||
border: 0px;
|
||||
background-color: #566673;
|
||||
color: #d9d9d9;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l2 a span.toctree-expand {
|
||||
display: block;
|
||||
font-size: inherit;
|
||||
line-height: inherit;
|
||||
color: inherit;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l2 a span.toctree-expand:before {
|
||||
display: block;
|
||||
font-size: inherit;
|
||||
line-height: inherit;
|
||||
color: inherit;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l2 a span.toctree-expand:hover {
|
||||
color: white;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l2 a:hover {
|
||||
color: white;
|
||||
background-color: #566673;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l2 a:hover span.toctree-expand {
|
||||
color: white;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l3.current > a {
|
||||
background-color: #e4e7ea;
|
||||
color: #838383;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a {
|
||||
background-color: #e4e7ea;
|
||||
color: #838383;
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.toctree-l3.current li.toctree-l4.current > a {
|
||||
color: var(--text-color);
|
||||
}
|
||||
|
||||
.wy-nav-top {
|
||||
background-color: var(--background-color);
|
||||
}
|
||||
|
||||
.btn {
|
||||
display: inline-block;
|
||||
font-weight: 400;
|
||||
line-height: 1.5;
|
||||
color: var(--text-color);
|
||||
text-align: center;
|
||||
text-decoration: none;
|
||||
vertical-align: middle;
|
||||
cursor: pointer;
|
||||
-webkit-user-select: none;
|
||||
-ms-user-select: none;
|
||||
user-select: none;
|
||||
background-color: transparent;
|
||||
border: 1px solid transparent;
|
||||
padding: 0.375rem 0.75rem;
|
||||
font-size: 1rem;
|
||||
border-radius: 0;
|
||||
transition: color 0.15s ease-in-out, background-color 0.15s ease-in-out, border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out;
|
||||
box-shadow: unset;
|
||||
}
|
||||
|
||||
.btn-neutral {
|
||||
background: unset !important;
|
||||
color: #838383 !important;
|
||||
}
|
||||
|
||||
.btn-neutral:active {
|
||||
padding: 0.375rem 0.75rem;
|
||||
box-shadow: unset;
|
||||
}
|
||||
50
docs/conf.py
Normal file
50
docs/conf.py
Normal file
@@ -0,0 +1,50 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# For the full list of built-in configuration values, see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
|
||||
project = 'jsix'
|
||||
copyright = '2024, Justin C. Miller'
|
||||
author = 'Justin C. Miller'
|
||||
release = '0.8'
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||||
|
||||
extensions = ['sphinx.ext.todo']
|
||||
primary_domain = 'cpp'
|
||||
todo_include_todos = True
|
||||
|
||||
templates_path = ['_templates']
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||||
|
||||
html_theme = 'renku'
|
||||
html_title = 'jsix'
|
||||
html_logo = 'jsix_transparent.svg'
|
||||
html_static_path = ['_static']
|
||||
html_css_files = ['custom.css']
|
||||
html_theme_options = {
|
||||
"description": "The jsix description",
|
||||
"github_repo": "https://github.com/justinian/jsix",
|
||||
"logo_only": True,
|
||||
"footer_icons": [
|
||||
{
|
||||
"name": "GitHub",
|
||||
"url": "https://github.com/justinian/jsix",
|
||||
"html": """
|
||||
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
|
||||
<path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
|
||||
</svg>
|
||||
""",
|
||||
"class": "",
|
||||
},
|
||||
],
|
||||
}
|
||||
80
docs/index.rst
Normal file
80
docs/index.rst
Normal file
@@ -0,0 +1,80 @@
|
||||
.. jsix documentation master file
|
||||
.. |amd64| replace:: :abbr:`amd64 (aka x86_64)`
|
||||
|
||||
The jsix Operating System
|
||||
=========================
|
||||
Introduction
|
||||
------------
|
||||
|
||||
**jsix** is a custom multi-core x64 operating system being built from scratch,
|
||||
supporting modern [#]_ Intel or AMD CPUs, and UEFI firmware. It was initially
|
||||
created out of a desire to explore UEFI and to explore what's possible with a
|
||||
microkernel architecture on modern 64-bit architectures.
|
||||
|
||||
Most of jsix is written in C++ (C++17, using `LLVM <https://llvm.org>`_), but
|
||||
you'll also find some assembly (in `NASM <https://nasm.us>`_ syntax) and Python
|
||||
for development tooling.
|
||||
|
||||
jsix can be found `on GitHub <https://github.com/justinian/jsix>`_, and is
|
||||
released under the terms of the `MPL 2.0 <https://mozilla.org/MPL/2.0/>`_.
|
||||
|
||||
.. admonition:: A note on the name
|
||||
|
||||
This kernel was originally named Popcorn, but I have since discovered that
|
||||
the Popcorn Linux project is also developing a kernel with that name,
|
||||
started around the same time as this project. So I've renamed this kernel
|
||||
jsix as an homage to L4, xv6, and my wonderful wife.
|
||||
|
||||
The name jsix is always styled *jsix* or ``j6``, never capitalized.
|
||||
|
||||
.. [#] jsix aims to support amd64 (x86_64) CPUs released in the last 10 years.
|
||||
|
||||
Current Features
|
||||
----------------
|
||||
|
||||
The jsix kernel is quite far along now, but the userland systems are still lacking.
|
||||
|
||||
- Platform: |amd64|
|
||||
- UEFI bootloader
|
||||
- Multi-core & multi-tasking microkernel
|
||||
|
||||
- Work-stealing SMP scheduler
|
||||
- Pluggable panic handler modules
|
||||
|
||||
- Capability-style object-oriented syscall API
|
||||
|
||||
- Custom IDL for specifying and documenting syscalls
|
||||
|
||||
- Virtual memory based on sharable Virtual Memory Area objects (VMAs)
|
||||
- Kernel API library (libj6), also provides features built on kernel primitives:
|
||||
|
||||
- Channels (async stream IPC) built on shared memory and futexes
|
||||
- Ring buffers via doubly-mapped pages
|
||||
|
||||
- Custom libc
|
||||
- Runtime dynamic linker
|
||||
- Init service
|
||||
|
||||
- Built-in VFS service for the initrd
|
||||
- ELF loader
|
||||
- Service-lookup protocol service
|
||||
|
||||
- Userland UART driver
|
||||
- Userland UEFI framebuffer driver
|
||||
- Userland kernel log output service
|
||||
- Userland unit test runner
|
||||
- Build configuration system (bonnibel)
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Site Contents:
|
||||
|
||||
index
|
||||
syscall_interface
|
||||
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`search`
|
||||
|
||||
|
||||
12
docs/jsix_transparent.svg
Normal file
12
docs/jsix_transparent.svg
Normal file
@@ -0,0 +1,12 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!-- Generator: Gravit.io -->
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="isolation:isolate" viewBox="176.562 356.069 211.11 113" width="211.11pt" height="113pt">
|
||||
<g>
|
||||
<g>
|
||||
<g>
|
||||
<path d=" M 212.981 372.36 L 219.564 376.16 L 226.147 379.961 L 226.147 387.563 L 226.147 395.164 L 219.564 398.965 L 212.981 402.766 L 206.398 398.965 L 199.815 395.164 L 199.815 387.563 L 199.815 379.961 L 206.398 376.16 L 212.981 372.36 L 212.981 372.36 L 212.981 372.36 Z M 256.292 397.366 L 262.875 401.166 L 269.458 404.967 L 269.458 412.569 L 269.458 420.17 L 262.875 423.971 L 256.292 427.772 L 249.709 423.971 L 243.126 420.17 L 243.126 412.569 L 243.126 404.967 L 249.709 401.166 L 256.292 397.366 L 256.292 397.366 Z M 183.622 387.283 L 205.52 374.64 L 227.418 361.997 L 249.316 374.64 L 271.214 387.283 L 271.214 412.569 L 271.214 437.854 L 249.316 450.497 L 227.418 463.14 L 205.52 450.497 L 183.622 437.854 L 183.622 412.569 L 183.622 387.283 L 183.622 387.283 L 183.622 387.283 Z M 241.855 372.36 L 248.438 376.16 L 255.021 379.961 L 255.021 387.563 L 255.021 395.164 L 248.438 398.965 L 241.855 402.766 L 235.272 398.965 L 228.689 395.164 L 228.689 387.563 L 228.689 379.961 L 235.272 376.16 L 241.855 372.36 Z " fill-rule="evenodd" fill="rgb(49,79,128)"/>
|
||||
<path d=" M 298.642 379.579 L 291.621 379.579 L 291.621 372.558 L 298.642 372.558 L 298.642 379.579 Z M 285.214 446.718 L 285.214 441.452 L 287.32 441.452 L 287.32 441.452 Q 289.339 441.452 290.524 440.092 L 290.524 440.092 L 290.524 440.092 Q 291.708 438.731 291.708 436.625 L 291.708 436.625 L 291.708 387.039 L 298.729 387.039 L 298.729 436.011 L 298.729 436.011 Q 298.729 440.925 295.921 443.822 L 295.921 443.822 L 295.921 443.822 Q 293.113 446.718 288.286 446.718 L 288.286 446.718 L 285.214 446.718 Z M 306.628 432.676 L 306.628 427.41 L 314.088 427.41 L 314.088 427.41 Q 317.862 427.41 319.573 425.347 L 319.573 425.347 L 319.573 425.347 Q 321.285 423.285 321.285 419.95 L 321.285 419.95 L 321.285 419.95 Q 321.285 417.317 319.705 415.474 L 319.705 415.474 L 319.705 415.474 Q 318.125 413.631 314.966 411.174 L 314.966 411.174 L 314.966 411.174 Q 312.245 408.98 310.621 407.356 L 310.621 407.356 L 310.621 407.356 Q 308.998 405.732 307.813 403.319 L 307.813 403.319 L 307.813 403.319 Q 306.628 400.905 306.628 397.746 L 306.628 397.746 L 306.628 397.746 Q 306.628 393.095 309.744 390.067 L 309.744 390.067 L 309.744 390.067 Q 312.859 387.039 318.125 387.039 L 318.125 387.039 L 325.76 387.039 L 325.76 392.305 L 319.441 392.305 L 319.441 392.305 Q 313.21 392.305 313.21 398.185 L 313.21 398.185 L 313.21 398.185 Q 313.21 400.467 314.615 402.134 L 314.615 402.134 L 314.615 402.134 Q 316.019 403.802 319.003 406.083 L 319.003 406.083 L 319.003 406.083 Q 321.723 408.19 323.479 409.901 L 323.479 409.901 L 323.479 409.901 Q 325.234 411.613 326.463 414.202 L 326.463 414.202 L 326.463 414.202 Q 327.691 416.791 327.691 420.301 L 327.691 420.301 L 327.691 420.301 Q 327.691 426.532 324.4 429.604 L 324.4 429.604 L 324.4 429.604 Q 321.109 432.676 315.141 432.676 L 315.141 432.676 L 306.628 432.676 Z M 342.611 379.579 L 335.59 379.579 L 335.59 372.558 L 342.611 372.558 L 342.611 379.579 Z M 342.611 432.676 L 335.59 432.676 L 335.59 387.039 L 342.611 387.039 L 342.611 432.676 Z M 356.126 432.676 L 348.754 432.676 L 361.392 409.77 L 349.632 387.039 L 356.39 387.039 L 364.639 403.187 L 372.977 387.039 L 379.735 387.039 L 367.974 409.77 L 380.612 432.676 L 373.24 432.676 L 364.639 416.001 L 356.126 432.676 Z " fill="rgb(49,79,128)"/>
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 3.6 KiB |
7
docs/modd.conf
Normal file
7
docs/modd.conf
Normal file
@@ -0,0 +1,7 @@
|
||||
** !_build/** ../definitions/**.def {
|
||||
prep: rm -rf _build; make html
|
||||
}
|
||||
|
||||
_build/html/** {
|
||||
daemon: devd -m _build/html
|
||||
}
|
||||
436
docs/syscall_interface.rst
Normal file
436
docs/syscall_interface.rst
Normal file
@@ -0,0 +1,436 @@
|
||||
.. jsix syscall interface.
|
||||
.. Automatically update from the definition files using cog!
|
||||
|
||||
.. [[[cog code generation
|
||||
.. from textwrap import indent
|
||||
.. from definitions.context import Context
|
||||
..
|
||||
.. ctx = Context(definitions_path)
|
||||
.. ctx.parse("syscalls.def")
|
||||
.. syscalls = ctx.interfaces["syscalls"]
|
||||
..
|
||||
.. def caplist(caps):
|
||||
.. return ', '.join([f"``{c}``" for c in caps])
|
||||
.. ]]]
|
||||
.. [[[end]]] (checksum: d41d8cd98f00b204e9800998ecf8427e)
|
||||
|
||||
The jsix syscall interface
|
||||
==========================
|
||||
|
||||
The jsix kernel's syscall design is based around object handles. Object handles
|
||||
are also a collections capabilities, encoding certain rights over the object
|
||||
they reference.
|
||||
|
||||
Very few syscalls in jsix can be made without some handle, and most of them are
|
||||
requests to the kernel to create a given kind of object. This is analogous to
|
||||
methods on an object in an object-oriented programming language.
|
||||
|
||||
.. [[[cog code generation
|
||||
.. cog.outl()
|
||||
.. for obj in syscalls.exposes:
|
||||
.. cog.outl(f"``{obj.name}`` syscalls")
|
||||
.. cog.outl(f"-------------------------")
|
||||
.. desc = obj.desc or "Undocumented"
|
||||
.. cog.outl(desc)
|
||||
.. cog.outl()
|
||||
.. cog.outl(f":capabilites: {caplist(obj.caps)}")
|
||||
.. cog.outl()
|
||||
.. for method in obj.methods:
|
||||
.. args = []
|
||||
.. if method.constructor:
|
||||
.. args.append("j6_handle_t *self")
|
||||
.. elif not method.static:
|
||||
.. args.append("j6_handle_t self")
|
||||
..
|
||||
.. for param in method.params:
|
||||
.. for type, suffix in param.type.c_names(param.options):
|
||||
.. args.append(f"{type} {param.name}{suffix}")
|
||||
..
|
||||
.. cog.outl(f".. cpp:function:: j6_result_t j6_{obj.name}_{method.name} ({', '.join(args)})")
|
||||
.. cog.outl()
|
||||
.. desc = method.desc or "Undocumented"
|
||||
.. cog.outl(indent(desc, " "))
|
||||
.. cog.outl()
|
||||
.. if "cap" in method.options:
|
||||
.. cog.outl(f" :capabilities: {caplist(method.options['cap'])}")
|
||||
.. cog.outl()
|
||||
.. if method.constructor:
|
||||
.. cog.outl(f" :param self: *[out]* Handle to the new {obj.name} object")
|
||||
.. elif not method.static:
|
||||
.. cog.outl(f" :param self: Handle to the {obj.name} object")
|
||||
.. for param in method.params:
|
||||
.. opts = param.options and f"*[{', '.join(param.options)}]*" or ""
|
||||
.. desc = param.desc or 'Undocumented'
|
||||
.. cog.outl(f" :param {param.name}: {opts} {desc}")
|
||||
.. cog.outl()
|
||||
.. ]]]
|
||||
|
||||
``object`` syscalls
|
||||
-------------------------
|
||||
All kernel-exposed objects inherit from the base ``object`` type, so the
|
||||
``object`` syscalls can be used with any object's handle.
|
||||
|
||||
:capabilites: ``clone``
|
||||
|
||||
.. cpp:function:: j6_result_t j6_object_koid (j6_handle_t self, uint64_t * koid)
|
||||
|
||||
Get the internal kernel object id of an object
|
||||
|
||||
:param self: Handle to the object object
|
||||
:param koid: *[out]* Undocumented
|
||||
|
||||
``event`` syscalls
|
||||
-------------------------
|
||||
An ``event`` is a simple synchronization object. It contains up to 64 signals
|
||||
that threads can wait for and signal in parallel.
|
||||
|
||||
:capabilites: ``signal``, ``wait``
|
||||
|
||||
.. cpp:function:: j6_result_t j6_event_create (j6_handle_t *self)
|
||||
|
||||
Undocumented
|
||||
|
||||
:param self: *[out]* Handle to the new event object
|
||||
|
||||
.. cpp:function:: j6_result_t j6_event_signal (j6_handle_t self, uint64_t signals)
|
||||
|
||||
Signal events on this object
|
||||
|
||||
:capabilities: ``signal``
|
||||
|
||||
:param self: Handle to the event object
|
||||
:param signals: A bitset of which events to signal
|
||||
|
||||
.. cpp:function:: j6_result_t j6_event_wait (j6_handle_t self, uint64_t * signals, uint64_t timeout)
|
||||
|
||||
Wait for signaled events on this object
|
||||
|
||||
:capabilities: ``wait``
|
||||
|
||||
:param self: Handle to the event object
|
||||
:param signals: *[out]* A bitset of which events were signaled
|
||||
:param timeout: Wait timeout in nanoseconds
|
||||
|
||||
``mailbox`` syscalls
|
||||
-------------------------
|
||||
Mailboxes are objects that enable synchronous IPC via arbitrary
|
||||
message-passing of tagged data and/or handles. Not as efficient
|
||||
as shared memory channels, but more flexible.
|
||||
|
||||
:capabilites: ``send``, ``receive``, ``close``
|
||||
|
||||
.. cpp:function:: j6_result_t j6_mailbox_create (j6_handle_t *self)
|
||||
|
||||
Undocumented
|
||||
|
||||
:param self: *[out]* Handle to the new mailbox object
|
||||
|
||||
.. cpp:function:: j6_result_t j6_mailbox_close (j6_handle_t self)
|
||||
|
||||
Undocumented
|
||||
|
||||
:capabilities: ``close``
|
||||
|
||||
:param self: Handle to the mailbox object
|
||||
|
||||
.. cpp:function:: j6_result_t j6_mailbox_call (j6_handle_t self, uint64_t * tag, void * data, size_t * data_len, size_t data_in_len, j6_handle_t * handles, size_t * handles_count)
|
||||
|
||||
Send a message to the reciever, and block until a response is
|
||||
sent. Note that getting this response does not require the
|
||||
receive capability.
|
||||
|
||||
:capabilities: ``send``
|
||||
|
||||
:param self: Handle to the mailbox object
|
||||
:param tag: *[inout]* Undocumented
|
||||
:param data: *[optional, inout]* Undocumented
|
||||
:param data_in_len: number of bytes in data used for input
|
||||
:param handles: *[optional, inout, handle, list]* Undocumented
|
||||
|
||||
.. cpp:function:: j6_result_t j6_mailbox_respond (j6_handle_t self, uint64_t * tag, void * data, size_t * data_len, size_t data_in_len, j6_handle_t * handles, size_t * handles_count, uint64_t * reply_tag, uint64_t flags)
|
||||
|
||||
Respond to a message sent using call, and wait for another
|
||||
message to arrive. Note that this does not require the send
|
||||
capability. A reply tag of 0 skips the reply and goes directly
|
||||
to waiting for a new message.
|
||||
|
||||
:capabilities: ``receive``
|
||||
|
||||
:param self: Handle to the mailbox object
|
||||
:param tag: *[inout]* Undocumented
|
||||
:param data: *[optional, inout]* Undocumented
|
||||
:param data_in_len: number of bytes in data used for input
|
||||
:param handles: *[optional, inout, handle, list]* Undocumented
|
||||
:param reply_tag: *[inout]* Undocumented
|
||||
:param flags: Undocumented
|
||||
|
||||
``process`` syscalls
|
||||
-------------------------
|
||||
A ``process`` object represents a process running on the system, and allows
|
||||
control over the threads, handles, and virtual memory space of that process.
|
||||
|
||||
:capabilites: ``kill``, ``create_thread``
|
||||
|
||||
.. cpp:function:: j6_result_t j6_process_create (j6_handle_t *self)
|
||||
|
||||
Create a new empty process
|
||||
|
||||
:param self: *[out]* Handle to the new process object
|
||||
|
||||
.. cpp:function:: j6_result_t j6_process_kill (j6_handle_t self)
|
||||
|
||||
Stop all threads and exit the given process
|
||||
|
||||
:capabilities: ``kill``
|
||||
|
||||
:param self: Handle to the process object
|
||||
|
||||
.. cpp:function:: j6_result_t j6_process_exit (int32_t result)
|
||||
|
||||
Stop all threads and exit the current process
|
||||
|
||||
:param result: The result to retrun to the parent process
|
||||
|
||||
.. cpp:function:: j6_result_t j6_process_give_handle (j6_handle_t self, j6_handle_t target)
|
||||
|
||||
Give the given process a handle that points to the same
|
||||
object as the specified handle.
|
||||
|
||||
:param self: Handle to the process object
|
||||
:param target: *[handle]* A handle in the caller process to send
|
||||
|
||||
``system`` syscalls
|
||||
-------------------------
|
||||
The singular ``system`` object represents a handle to kernel functionality
|
||||
needed by drivers and other priviledged services.
|
||||
|
||||
:capabilites: ``get_log``, ``bind_irq``, ``map_phys``, ``change_iopl``
|
||||
|
||||
.. cpp:function:: j6_result_t j6_system_get_log (j6_handle_t self, uint64_t seen, void * buffer, size_t * buffer_len)
|
||||
|
||||
Get the next log line from the kernel log
|
||||
|
||||
:capabilities: ``get_log``
|
||||
|
||||
:param self: Handle to the system object
|
||||
:param seen: Last seen log id
|
||||
:param buffer: *[out, zero_ok]* Buffer for the log message data structure
|
||||
|
||||
.. cpp:function:: j6_result_t j6_system_bind_irq (j6_handle_t self, j6_handle_t dest, unsigned irq, unsigned signal)
|
||||
|
||||
Ask the kernel to send this process messages whenever
|
||||
the given IRQ fires
|
||||
|
||||
:capabilities: ``bind_irq``
|
||||
|
||||
:param self: Handle to the system object
|
||||
:param dest: Event object that will receive messages
|
||||
:param irq: IRQ number to bind
|
||||
:param signal: Signal number on the event to bind to
|
||||
|
||||
.. cpp:function:: j6_result_t j6_system_map_phys (j6_handle_t self, j6_handle_t * area, uintptr_t phys, size_t size, uint32_t flags)
|
||||
|
||||
Create a VMA and map an area of physical memory into it,
|
||||
also mapping that VMA into the current process
|
||||
|
||||
:capabilities: ``map_phys``
|
||||
|
||||
:param self: Handle to the system object
|
||||
:param area: *[out]* Receives a handle to the VMA created
|
||||
:param phys: The physical address of the area
|
||||
:param size: Size of the area, in bytes
|
||||
:param flags: Flags to apply to the created VMA
|
||||
|
||||
.. cpp:function:: j6_result_t j6_system_request_iopl (j6_handle_t self, unsigned iopl)
|
||||
|
||||
Request the kernel change the IOPL for this process. The only values
|
||||
that make sense are 0 and 3.
|
||||
|
||||
:capabilities: ``change_iopl``
|
||||
|
||||
:param self: Handle to the system object
|
||||
:param iopl: The IOPL to set for this process
|
||||
|
||||
``thread`` syscalls
|
||||
-------------------------
|
||||
A ``thread`` object represents a thread of execution within a process running
|
||||
on the system. The actual thread does not need to be currently running to
|
||||
hold a handle to it.
|
||||
|
||||
:capabilites: ``kill``, ``join``
|
||||
|
||||
.. cpp:function:: j6_result_t j6_thread_create (j6_handle_t *self, j6_handle_t process, uintptr_t stack_top, uintptr_t entrypoint, uint64_t arg0, uint64_t arg1)
|
||||
|
||||
Undocumented
|
||||
|
||||
:param self: *[out]* Handle to the new thread object
|
||||
:param process: *[optional, cap]* Undocumented
|
||||
:param stack_top: Undocumented
|
||||
:param entrypoint: Undocumented
|
||||
:param arg0: Undocumented
|
||||
:param arg1: Undocumented
|
||||
|
||||
.. cpp:function:: j6_result_t j6_thread_kill (j6_handle_t self)
|
||||
|
||||
Undocumented
|
||||
|
||||
:capabilities: ``kill``
|
||||
|
||||
:param self: Handle to the thread object
|
||||
|
||||
.. cpp:function:: j6_result_t j6_thread_join (j6_handle_t self)
|
||||
|
||||
Undocumented
|
||||
|
||||
:capabilities: ``join``
|
||||
|
||||
:param self: Handle to the thread object
|
||||
|
||||
.. cpp:function:: j6_result_t j6_thread_exit ()
|
||||
|
||||
Undocumented
|
||||
|
||||
|
||||
.. cpp:function:: j6_result_t j6_thread_sleep (uint64_t duration)
|
||||
|
||||
Undocumented
|
||||
|
||||
:param duration: Undocumented
|
||||
|
||||
``vma`` syscalls
|
||||
-------------------------
|
||||
A ``vma`` object represents a single virtual memory area, which may be shared
|
||||
between several processes. A process having a handle to a ``vma`` does not
|
||||
necessarily mean that it is mapped into that process' virtual memory space.
|
||||
|
||||
:capabilites: ``map``, ``unmap``, ``resize``
|
||||
|
||||
.. cpp:function:: j6_result_t j6_vma_create (j6_handle_t *self, size_t size, uint32_t flags)
|
||||
|
||||
Undocumented
|
||||
|
||||
:param self: *[out]* Handle to the new vma object
|
||||
:param size: Undocumented
|
||||
:param flags: Undocumented
|
||||
|
||||
.. cpp:function:: j6_result_t j6_vma_create_map (j6_handle_t *self, size_t size, uintptr_t * address, uint32_t flags)
|
||||
|
||||
Undocumented
|
||||
|
||||
:capabilities: ``map``
|
||||
|
||||
:param self: *[out]* Handle to the new vma object
|
||||
:param size: Undocumented
|
||||
:param address: *[inout]* Undocumented
|
||||
:param flags: Undocumented
|
||||
|
||||
.. cpp:function:: j6_result_t j6_vma_map (j6_handle_t self, j6_handle_t process, uintptr_t * address, uint32_t flags)
|
||||
|
||||
Undocumented
|
||||
|
||||
:capabilities: ``map``
|
||||
|
||||
:param self: Handle to the vma object
|
||||
:param process: *[optional]* Undocumented
|
||||
:param address: *[inout]* Undocumented
|
||||
:param flags: Undocumented
|
||||
|
||||
.. cpp:function:: j6_result_t j6_vma_unmap (j6_handle_t self, j6_handle_t process)
|
||||
|
||||
Undocumented
|
||||
|
||||
:capabilities: ``unmap``
|
||||
|
||||
:param self: Handle to the vma object
|
||||
:param process: *[optional]* Undocumented
|
||||
|
||||
.. cpp:function:: j6_result_t j6_vma_resize (j6_handle_t self, size_t * size)
|
||||
|
||||
Undocumented
|
||||
|
||||
:capabilities: ``resize``
|
||||
|
||||
:param self: Handle to the vma object
|
||||
:param size: *[inout]* New size for the VMA, or 0 to query the current size without changing
|
||||
|
||||
.. [[[end]]] (checksum: fe448e541c009a1bcf8bdc44f4760e32)
|
||||
|
||||
Non-object syscalls
|
||||
-------------------
|
||||
|
||||
The following are the system calls that aren't constructors for objects, and
|
||||
either do not require an object handle, or operate generically on handles.
|
||||
|
||||
.. [[[cog code generation
|
||||
.. cog.outl()
|
||||
.. for func in syscalls.functions:
|
||||
.. args = []
|
||||
.. for param in func.params:
|
||||
.. for type, suffix in param.type.c_names(param.options):
|
||||
.. args.append(f"{type} {param.name}{suffix}")
|
||||
..
|
||||
.. cog.outl(f".. cpp:function:: j6_result_t j6_{func.name} ({', '.join(args)})")
|
||||
.. cog.outl()
|
||||
.. desc = func.desc or "Undocumented"
|
||||
.. cog.outl(indent(desc, " "))
|
||||
.. cog.outl()
|
||||
.. for param in func.params:
|
||||
.. opts = param.options and f"*[{', '.join(param.options)}]*" or ""
|
||||
.. desc = param.desc or 'Undocumented'
|
||||
.. cog.outl(f" :param {param.name}: {opts} {desc}")
|
||||
.. cog.outl()
|
||||
.. ]]]
|
||||
|
||||
.. cpp:function:: j6_result_t j6_noop ()
|
||||
|
||||
Simple no-op syscall for testing
|
||||
|
||||
|
||||
.. cpp:function:: j6_result_t j6_log (uint8_t area, uint8_t severity, const char * message)
|
||||
|
||||
Write a message to the kernel log
|
||||
|
||||
:param area: Undocumented
|
||||
:param severity: Undocumented
|
||||
:param message: Undocumented
|
||||
|
||||
.. cpp:function:: j6_result_t j6_handle_list (struct j6_handle_descriptor * handles, size_t * handles_size)
|
||||
|
||||
Get a list of handles owned by this process. If the
|
||||
supplied list is not big enough, will set the size
|
||||
needed in `size` and return j6_err_insufficient
|
||||
|
||||
:param handles: *[list, inout, zero_ok]* A list of handles to be filled
|
||||
|
||||
.. cpp:function:: j6_result_t j6_handle_clone (j6_handle_t orig, j6_handle_t * clone, uint32_t mask)
|
||||
|
||||
Create a clone of an existing handle, possibly with
|
||||
some capabilities masked out.
|
||||
|
||||
:param orig: *[handle, cap]* The handle to clone
|
||||
:param clone: *[out]* The new handle
|
||||
:param mask: The capability bitmask
|
||||
|
||||
.. cpp:function:: j6_result_t j6_futex_wait (const uint32_t * address, uint32_t current, uint64_t timeout)
|
||||
|
||||
Block waiting on a futex
|
||||
|
||||
:param address: Address of the futex value
|
||||
:param current: Current value of the futex
|
||||
:param timeout: Wait timeout in nanoseconds
|
||||
|
||||
.. cpp:function:: j6_result_t j6_futex_wake (const uint32_t * address, uint64_t count)
|
||||
|
||||
Wake threads waiting on a futex
|
||||
|
||||
:param address: Address of the futex value
|
||||
:param count: Number of threads to wake, or 0 for all
|
||||
|
||||
.. cpp:function:: j6_result_t j6_test_finish (uint32_t exit_code)
|
||||
|
||||
Testing mode only: Have the kernel finish and exit QEMU with the given exit code
|
||||
|
||||
:param exit_code: Undocumented
|
||||
|
||||
.. [[[end]]] (checksum: b8b12e99a4a00c99b3859f05000a7bfd)
|
||||
|
||||
@@ -7,3 +7,5 @@ pure-cdb == 4
|
||||
pyzstd == 0.15
|
||||
pyelftools
|
||||
iced-x86
|
||||
sphinx
|
||||
renku-sphinx-theme
|
||||
|
||||
Reference in New Issue
Block a user