Merge branch 'update-software-reference' into 'master'

Update Phosh instructions, add storage device info

See merge request Librem5/developer.puri.sm!364

Software_Reference.rst

-
 .. index:: Software Reference
-
 .. _software_reference:
 
 Software Reference
@@ -9,11 +7,18 @@ Software Reference
 This chapter provides information about the software components used in the
 Librem 5 stack and includes links to useful external resources.
 
-The Librem 5 will be an i.MX8 phone running PureOS, a Debian derivative. The
-kernel will be the 5.3 mainline kernel with some additional drivers. For the
-graphical environment, it makes use of Phoc_, a Wayland-based compositor,
-together with a bespoke shell named :ref:`Phosh`. The graphical environment is based
-on the GNOME platform with a variety of modifications.
+.. toctree::
+   :maxdepth: 1
+
+   Software_Reference/Linux_Kernel
+   Software_Reference/Environments
+   Software_Reference/Wayland
+   Software_Reference/Storage_Devices
+
+Summary
+-------
+
+The Librem 5 is an i.MX8 phone running PureOS, a Debian derivative. The kernel is the 5.3 mainline kernel with some additional drivers. For the graphical environment, it makes use of Phoc_, a Wayland-based compositor, together with a bespoke shell named :ref:`Phosh`. The graphical environment is based on the GNOME platform with a variety of modifications.
 
 Below you can find a diagram on the overall software architecture stack.
 
@@ -22,10 +27,4 @@ Below you can find a diagram on the overall software architecture stack.
    :height: 500px
    :align: center
 
-.. toctree::
-
-   Software_Reference/Linux_Kernel
-   Software_Reference/Environments
-   Software_Reference/Wayland
-
 .. include:: /links.txt

Software_Reference/Environments/Phosh.rst

-
 .. _phosh:
 
 Phosh
 =====
 
 The Phone's shell Phosh is based on GNOME_ technologies (GTK, GSettings, DBus)
-and uses a custom Wayland compositor.
+and uses a custom Wayland compositor called Phoc_.
 
 .. image:: Phosh/images/phosh.jpg
    :scale: 50%

Software_Reference/Environments/Phosh/Install.rst

@@ -4,7 +4,8 @@ Installation
 ============
 
 Phosh runs on the development images by default. If you want to hack on it, you
-need to build it from source, obtained from the `Phosh repository`_.
+need to build it from source, obtained from the `Phosh repository`_. You will
+also need to install the Phoc_ compositor.
 
 .. index:: Building phosh
 
@@ -15,29 +16,17 @@ To install Phosh, follow the instructions in the `README`_ file from the
 repository. If you want to run it from the source tree you can omit the
 ``ninja -C _build install`` step.
 
-.. index:: Building rootston
-
-Building rootston
------------------
-
-To make it work better with *phosh* we currently use some patches on top of
-*wlroots*' reference Wayland compositor *rootston*. While *phosh* works with
-upstream *rootston* some of the features like rotation are only available with
-our fork at the moment. To build it, clone the repository first. Please
-checkout wlroots next to phosh::
+Running Phosh
+-------------
 
-    git clone https://source.puri.sm/Librem5/wlroots.git
-    cd wlroots
-    meson . _build
-    ninja -C _build
+Assuming that Phoc was built in a directory alongside the Phosh directory, you
+can start Phoc from a virtual terminal using the config file shipped with
+Phosh:
 
-Running phosh
--------------
-Now you can start *rootston* from a virtual terminal using the config file
-shipped by *phosh*::
+.. code:: bash
 
     cd phosh
-    ../wlroots/rootston/rootston -C ./rootston.ini -E _build/run
+    ../phoc/_build/run -E '_build/run -U' -C ./data/rootston.ini
 
 .. _README: https://source.puri.sm/Librem5/phosh/blob/master/README.md
 .. include:: /links.txt

Software_Reference/Storage_Devices.rst

+.. _software_reference_storage:
+
+Storage Devices
+===============
+
+The Librem 5 is supplied with one form of solid state storage built-in (eMMC) and supports additional storage using a microSD card.
+
+.. contents::
+   :local:
+
+This document provides a brief overview of how these devices appear to the system software.
+
+eMMC
+----
+
+The phone is shipped with 32 GB eMMC (embedded MultiMediaCard memory) that contains the operating system and space for the user's files and installed applications.
+
+This is visible in the root file system as ``/dev/mmcblk0``. Files that begin with the ``mmcblk0`` prefix, such as ``mmcblk0p1`` and ``mmcblk0p2`` represent the partitions of this storage.
+
+microSD
+-------
+
+.. note:: It is recommended that you switch off the phone before removing and reinserting the SIM tray.
+
+The phone accepts a microSD card in the outer slot of the SIM tray. This can be used to provide additional storage capacity, especially for user data.
+
+When a suitable microSD card is installed, it appears at ``/dev/sda`` in the root file system. Partitions of the card appears as numbered files with the same prefix, such as ``/dev/sda1`` and ``/dev/sda2``.

Software_Reference/Wayland.rst

-.. _wayland:
+.. _software_reference_wayland:
 
 Wayland
 =======
 
+The :ref:`phosh` environment on the Librem 5 communicates with the phoc_ compositor using the `Wayland`_ protocol.
+
 When working on the compositor these links might be useful:
 
 * `Wayland architecture <https://wayland.freedesktop.org/architecture.html>`_
 * `Wayland protocol <https://wayland.freedesktop.org/docs/html/ch04.html>`_
+
+.. include:: /links.txt

links.txt

@@ -163,6 +163,7 @@
 .. _`Using GtkApplication`: https://developer.gnome.org/GtkApplication/
 .. _`Using GSettings`: https://developer.gnome.org/GSettings/
 .. _`Virtboard`: https://source.puri.sm/Librem5/virtboard/blob/master/README.md
+.. _`Wayland`: https://wayland.freedesktop.org/
 .. _`XDG Base Directory Specification`: http://www.freedesktop.org/Standards/basedir-spec
 
 .. _`FH34SRJ-6S-0.5SH(50) (Touch)`: https://www.hirose.com/product/download/?distributor=digikey&type=2d&lang=en&num=FH34SRJ-6S-0.5SH(50)