doc.txt

etc/doc.txt

@@ -1 +1,143 @@
-Other files for the system disk go here...
+HOW USE MOP3
+
+1. Filesystem
+
+The filesystem is more akin to DOS or Windows. In MOP3 we use a path scheme,
+which looks like this: VOLUME:/path/to/file.txt. This stems from the fact
+that such VFS (Virtual File System) is much easier (and cleaner) to implement
+than Unix graph VFS.
+
+MOP3 by default exposes 2 volumes, "sys" and "temp". The system volume is akin
+to a "ramdisk" - it's a small filesystem, which provides the user with the most
+basic applications and the init app, used to start up the system, along with
+some CE scripts. Internally, "sys" is based on an LZ4-compressed .tar file.
+The temporary volume is a RAM-based FAT32 volume and acts like a "scratchpad"
+filesystem. Due to it being located in RAM, it will get cleaned on every
+reboot, so be careful and don't store stuff there!
+
+2. Applications
+
+This is an overview of MOP3 applications:
+
+2.1 init (first process)
+
+OPTIONS: None
+
+init is functions as the init process. It spawns the shell (CE) with the init
+script and then starts the interactive shell interpreter. Doesn't do anything
+else besides that.
+
+2.2 spin (scheduler stub)
+
+OPTIONS: None
+
+This is a very useless application - all it does is it spins in place. This
+acts as a stub process for the scheduler, when it has nothing else to schedule
+(no runnable processes).
+
+2.3 ce (shell)
+
+OPTIONS:
+  -p -printcmds (log executed commands; useful for running inside of scripts)
+  -s -script [script path] (run a script from a file)
+  -a -args [args string] (provide positional arguments to a script)
+
+CE or Command Executor is the shell application for MOP3. It can run other
+apps, work with the filesystem and even provides a basic text editor!
+More on CE later in the document.
+
+2.4 sdutil (storage device utility)
+
+OPTIONS:
+  -pd -part-dos (partition a device using DOS partitioning scheme)
+  -lpd -list-part-dos (list DOS partitions on a device)
+  -ff32 -format-fat32 (format a device to a FAT32 filesystem)
+  -ff16 -format-fat16 (format a device to a FAT16 filesystem)
+  -ils2 -install-limine-stage2 (install Limine stage 2 bootloader on a device)
+  -pr -part-rescan (rescan device's partitions; deletes old partitions)
+  -d -device [key] (device key to operate on)
+
+This application is used to manage storage devices.
+
+Warning: Partition rescan may break the system as it will delete old partition
+pseudo devices and create new ones. This will leave mounted volumes pointing to
+non-existed devices and cause big trouble! Be careful.
+
+Waring2: Installing Limine stage 2 bootloader is WIP, so it doesn't work for
+now ;(. Maybe one day...
+
+2.5 usb (USB utility / service)
+
+OPTIONS:
+  -p -poll (poll a USB controller device)
+  -d -device [key] (USB controller device key)
+
+This app polls the USB controller device for bus events. For many controllers,
+many instances of "usb" should be spawned.
+
+2.6 mailtest (mail subsystem testing app)
+
+OPTIONS:
+  -r -recv (start in receiver mode; will print data to the debug console)
+  -s -send (run in sender mode)
+  -p -payload [string] (give payload when ran as a sender)
+  -pg -procgroup [int] (target process group)
+
+2.7 devices (device management utility)
+
+OPTIONS:
+  -la -list-all (List all devices available to the system)
+
+2.8 volumes (volume managemnt utility)
+  -e -eject (Eject / remove a volume based on device key)
+  -d -device [key] (Device key)
+  -l -list (List all volumes)
+  -m -make (create a new volume)
+  -k -key (provide a new volume key)
+  -fs -filesystem (set filesystem)
+
+3. CE commands
+
+Here are all CE commands you can use both in scripts and interactively :)
+
+  help
+    prints help information
+
+  cat <file1> <file2>
+    Print contents of a file/files
+
+  ls <dir>
+    List contents of a directory
+
+  quit
+    Quit the shell
+
+  mkfile <file>
+    Create a file
+
+  rm  <path>
+    Remove file/directory at path
+
+  edit <file>
+    Run CE built-in editor in edit mode
+
+  view <file>
+    Run CE built-in editor in viewer mode
+
+  terminfo
+    Print graphical terminal stats
+
+  cls
+    Clear terminal
+
+  procinfo
+    Print process information in a table format
+
+  stall <ms>
+    Wait (blockingly) for <ms> milliseconds
+
+  copy <file A> <file B>
+    Copy file source to destination
+
+  echo <arg 1> <arg 2> <arg3> ...
+    Echo provided arguments; useful for printing inside of scripts