~anjan/sxmo-docs-stable

ref: 1c1d3612692ce5568285f1be3b88d2798aef35e6 sxmo-docs-stable/SYSTEMGUIDE.md -rw-r--r-- 20.9 KiB
1c1d3612 — Anjandev Momi add man.sr.ht documentation links to header 6 months ago

#Sxmo: Simple X Mobile - System Guide

Project Overview | Documentation | Documentation (Development Version) | Install Guide | User Guide | Contributing | Images | Demo Video

This document describes various aspects of how Sxmo runs and is configured.

Start-up Process

Event Handling

Notifications

#Start-up Process

#U-boot

The default PinePhone boot priority is first the SD card and then the eMMC so inserting your own SD card with your preferred release will result in the phone booting your image.

#postmarketOS initramfs

After the kernel is booted, the init.sh script in initial RAM disk runs. This performs various low-level startup and setup tasks, mostly relating to partitions and filesystems. This largely relies on the busybox binary present in the initial RAM disk. When completed the script exec's a switch_root to the root filesystem and starts /sbin/init which is just a symlink to BusyBox.

#BusyBox init

When called as init, busybox will use /etc/inittab for its configuration, if present. Note, busybox has its own interpretation of inittab syntax. The /etc/inittab included in the filesystem specifies the following:

  • Run /sbin/getty on /dev/tty[1-6] for virtual consoles, and on the /tty/S0 for the serial console.
  • Run sysvinit actions first, waiting for completion
    • /sbin/openrc sysinit
    • /sbin/openrc boot
  • Run wait actions next, waiting for completion
    • /sbin/openrc default -- this is the "actual" init.
  • If ctrl-alt-delete is pressed, run /sbin/reboot
  • When shutdown is initiated, run /sbin/openrc shutdown.

#OpenRC init

OpenRC init system is a dependency-based init system that manages system init scripts and the associated services.

Named runlevels in OpenRC are stored in directories under /etc/runlevels. When called with a runlevel as an argument, /sbin/openrc loads the init scripts in the runlevel's directory, and then run them in alphabetical order, unless a script has dependency information, in which case the order is changed to provide a valid start-up sequence.

#X Display Manager - xdm

Details on xdm and the login widget configuration can be found in the xdm man page.

  • /usr/sbin/xdm runs with the arguments specified by the variable $xdm_opts, which is set in /etc/conf.d/xdm. Currently, the $xdm_opts variable is empty.
  • The /usr/lib/X11/Xsetup_0 script runs to assist in setting up the screen the user sees along with the xlogin widget.
    • If present, the file /usr/lib/X11/xdm/wallpaper.jpg will be set as the background for the login screen.
    • If present, the file /usr/lib/X11/xdm/welcome.ogg will be played as the startup sound.
  • The xlogin widget is displayed based on the configuration in /etc/X11/xdm/Xresources, including colors, fonts, dimensions, and optional logo.
  • After the user logs in, the /usr/lib/X11/Xstartup script runs, which registers the user's session using sessreg.
  • Then xdm runs the /usr/lib/X11/Xsession script, which simply hands off control to /usr/sbin/sxmo_xinit.sh.

When the user logs out, xdm will run /usr/lib/X11/Xreset which currently only deregisters the user. Then the X server is reset and Xsetup_0 is run again.)

#sxmo_xinit.sh

This script, located at /usr/sbin/sxmo_xinit.sh, sets up the basic interface for Sxmo:

  • sources /usr/bin/sxmo_common.sh to set common environment/shell variables

    • sets NOTIFDIR, CACHEDIR, LOGDIR, KEYBOARD, and icon variables (loading from "$XDG_CONFIG_HOME/sxmo/hooks/icons") as necessary.

  • envvars() - this function sets up environment variables by:

    • sourcing /etc/profile - system-wide variables - This just sources /etc/profile.d/*.sh
    • sourcing ~/.profile - per-user variables - not present by default
    • manual setting of variables not already set

  • setupxdgdir()

    • creates $XDG_RUNTIME_DIR and $XDG_CACHE_HOME (see basedir specification)
    • sets permissions and ownership on the above directories

  • xdefaults() - performs basic X startup/setup

  • daemons()

    • kills conky (desktop date and time)
    • if the config file present, start conky with $XDG_CONFIG_HOME/sxmo/conky.conf
    • if the per-use config file is not present, start conky with the system config file /usr/share/sxmo/appcfg/conky.conf
    • start autocutsel for both CLIPBOARD (default) and PRIMARY
    • run sxmo_statusbar.sh
      • kills any existing sxmo_statusbar.sh instance
      • updates any current call time
      • displays wireless and modem (cell) indicators as appropriate
      • displays battery percentage and audio volume
      • displays current time

  • startdwm()

#Event Handling

Various processes are started when certain events occur, rather than always being run at startup or login. Some of the most significant ones are listed below:

#Key and Button Presses - dwm

The keys and button presses which dwm responds to are specified at compile-time in the config.h for sxmo-dwm. See the userguide for a description.

#Screen Gestures - lisgd

The built-in responses to screen gestures that are specified at compile-time in config.h for lisgd, are overridden by command-line specifications in sxmo_lisgdstart.sh. See the userguide for a description.

#System Events - udev

A variety of system activities trigger udev events which are matched by rules in /etc/udev/rules.d/ and /usr/lib/udev/rules.d.

#Notifications

#Notification Format

Notifications to the user are created by calling /usr/bin/sxmo_notificationwrite.sh with the appropriate arguments. These arguments are:

  • The filepath of the notification to write (or "random" to generate a random id)
    • If "random" is specified, then the notification file will be created in $NOTIFDIR as specified in /usr/bin/sxmo_common.sh.
  • Action that the notification invokes upon selecting/tapping the notification window
    • select/tapping on the notification will trigger removal of the notification, as well as the associated action.
  • The file to watch for deactivation (which occurs if anything at all happens to the file).
    • This file, if specified, should be one which will be affected by the user dealing with the interaction, in order to trigger removal of the notification. In the absence of a file, a string representing a non-existent file can be provided (e.g. "none")
    • e.g. if a SMS text is removed, the watch file should be the one containing the SMS message, so when the user reads/deletes/saves the message, the notification will be removed.
  • The text displayed in the notification

The last 3 arguments are written out by sxmo_notificationwrite.sh, with one per line (though the message text can be multi-line, I think.) into the notification file specified by the first argument.

#Notification Handling

When created, notifications in $NOTIFDIR will be processed by /usr/bin/sxmo_notificationmonitor.sh.

When started, sxmo_notificationmonitor.sh will scan and display any notifications in the directory specified in $NOTIFDIR, then will begin monitoring that directory for any new notification files.

If a new notification is detected, the following actions are taken by the handlenewnotiffile() function:

  1. Checks the validity of notification file ( files must be at least 3 lines long )
  2. The notificationhook() function passes the notification file to the user-defined notification script in "$XDG_CONFIG_HOME"/sxmo/hooks/notification, if present; otherwise, it makes the phone vibrate.
  3. The notification message is displayed using dunstify.
  4. If the displayed notification is clicked/tapped, then the action specified in the notification file is run.
  5. If the specified notification watch file exists, it is watched by inotifywait and upon the report of any event, the notification file is removed.

#Notification Browsing

Pending notifications can be viewed by running /usr/bin/sxmo_notificationsmenu.sh either from a terminal or from the system menu. This script displays the notification times (hh:mm) and the associated messages using dmenu. If selected, the action specified in the notification file is performed and the notification is removed.