Merge branch 'devkit-clean-up' into 'master'

Tidy up new devkit information

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

Development_Environment.rst

@@ -3,6 +3,11 @@
 Setting up a Development Environment
 ====================================
 
+This chapter describes how to set up an development environment for the
+Librem 5 phone that enables you to create, test, package and deploy
+applications. Development and testing can be performed using either the phone
+itself, a development kit or with an emulator that runs on a workstation.
+
 .. toctree::
    :maxdepth: 2
 

Development_Environment/Boards.rst

@@ -4,7 +4,8 @@ Development Kits
 ================
 
 The development boards for the Librem 5 are built around the
-`EmCraft i.MX 8M SoM`_, a development platform based on the i.MX8 CPU.
+`EmCraft i.MX 8M SoM`_, a development platform based on the i.MX8 CPU. There
+is a list of :ref:`imx8_devkit_known_issues` with the development boards.
 
 It is possible to develop software for the Librem 5 without a development kit.
 If you are developing applications that do not rely on specific features of the
@@ -17,8 +18,9 @@ commands and some application setup that is not board specific.
 .. toctree::
    :maxdepth: 2
 
-   Boards/First-Steps
    Boards/imx8
+   Boards/Known_Issues
+   Boards/Troubleshooting
    Boards/dev-kit/modem
    Boards/mini-tutorials
    Boards/Legacy/index

Development_Environment/Boards/Known_Issues.rst

+.. _imx8_devkit_known_issues:
+
+Known Issues
+============
+
+.. note:: This section is incomplete and is being revised.
+
+This page will contain a list of issues that were known at the time of the
+kit's release, providing links to issue trackers where relevant.
+
+Known issues with the operating system and applications under development for
+the Librem 5 can be found in the lists of issues for the `OS Issues`_ and
+`Apps Issues`_ repositories.
+
+Status of Subsystems
+--------------------
+
+The following table shows the status of the subsystems on the development
+board, indicating the level to which the hardware has been validated and
+whether user space software is in place to drive it.
+
+.. csv-table:: Status of subsystems
+   :header: "Subystem", "Validated", "Integrated"
+
+   "Charge Controller", "Yes", ""
+   "USB-C", "Yes", ""
+   "Serial Downloader", "Yes", ""
+   "eMMC boot", "Yes", ""
+   "SoM - with 3GB RAM, 32GB eMMC", "Yes", ""
+   "UART Debug", "Yes", ""
+   "Powering from 18650 battery", "Yes", ""
+   "Charge controller's thermistor", "Yes", ""
+   "Ethernet", "Yes", ""
+   "Audio Codec", "Yes", ""
+   "Mini-HDMI", "Yes", ""
+   "WWAN module", "Yes", ""
+   "WWAN antenna", "Yes", ""
+   "SIM card (able to make a call)", "Yes", ""
+   "WWAN kill via GPIO3_IO04 (420 in Linux) & HKS", "Yes", ""
+   "GNSS (aka GPS)", "Yes", ""
+   "USB Hub and micro-SD", "Yes", ""
+   "USB Host", "Yes", ""
+   "USB Peripheral", "Yes", ""
+   "RedPine WiFi/BT M.2 module", "Yes", ""
+   "RTC", "Yes", ""
+   "Haptic motor", "Yes", ""
+   "buttons (power button, reset button, volume up, volume down)", "Yes", ""
+   "User LED", "Yes", ""
+   "Power indicator LEDs", "Yes", ""
+   "HP_DET", "Yes", ""
+   "Display's LED backlight", "Yes", ""
+   "SPI NOR Flash", "Yes", ""
+   "Speaker", "Yes", ""
+   "Headphone jack", "Yes", ""
+   "Smart card reader", "Yes", ""
+   "Touch controller", "Yes", ""
+   "JTAG", "Yes", ""
+   "IMU", "Partially", ""
+   "Proximity/Ambient light sensor", "Partially", ""
+   "WLAN/BT antennae", "Partially", ""
+   "On-board microphone", "Partially", ""
+   "Headset microphone", "Partially", ""
+   "HKSs", "Partially", ""
+   "MIPI DSI LCD panel", "Partially", ""
+   "USB-C role switching", "No", ""
+   "Microphone select IC", "No", ""
+   "Bluetooth (UART4)", "No", ""
+   "Camera", "No", ""
+   "USB OTG", "No", ""
+   "WWAN I2S interface", "No", ""
+   "Bluetooth I2S interface", "No", ""
+
+.. _`Apps Issues`: https://source.puri.sm/Librem5/Apps_Issues
+.. _`OS Issues`: https://source.puri.sm/Librem5/OS-issues

Development_Environment/Boards/First-Steps.rst → Development_Environment/Boards/Legacy/First-Steps.rst

-.. _first-steps:
+.. _imx6_first_steps:
 
 First Steps
 ===========
 
-The development board (whether a physical one or an emulated one) will give you a place to see the effects of the active Librem 5 development. The software running on this board will become the software running on the Librem 5 phone but you don't have to wait for your Librem 5 phone to interact with it!
+The development board (whether a physical one or an emulated one) will give you
+a place to see the effects of the active Librem 5 development. The software
+running on this board will become the software running on the Librem 5 phone
+but you don't have to wait for your Librem 5 phone to interact with it!
 
-Regardless of which development board you are using, here are some first steps you will take when booting the system.
+If you are using the i.MX6 development board, here are some first steps you
+will take when booting the system.
 
 .. _make-bootable-drive:
 

Development_Environment/Boards/Legacy/index.rst

@@ -8,4 +8,5 @@ generally available or are considered to be obsolete for current development.
 
 .. toctree::
 
+   First-Steps
    imx6

Development_Environment/Boards/Troubleshooting.rst

+.. _imx8_devkit_troubleshooting:
+
+Troubleshooting
+===============
+
+This page provides information for developers who need to investigate a problem
+with a development kit and want to diagnose it. It contains some useful
+starting points for investigation and instructions for performing tasks that
+may be needed to help with testing.
+
+.. contents::
+
+Installing the SOM
+------------------
+
+If the SOM is not installed or has been removed, follow these instructions to
+install it.
+
+1. Power board without SOM via USB-C.
+2. Check the voltages.
+
+.. figure:: images/voltage-points.png
+   :scale: 50%
+   :alt: The voltage points to measure
+
+   The voltage points to measure (click to enlarge)
+
++------------------+-----------------+
+| Point            | Voltage         |
++==================+=================+
+| VBUS             | 5.2V            |
++------------------+-----------------+
+| VBAT             | 4.2V            |
++------------------+-----------------+
+| VBAT\ :sub:`REG` | 4.2V            |
++------------------+-----------------+
+| 5V\ :sub:`SOM`   | 5.0V            |
++------------------+-----------------+
+| 3V3              | 3.3V            |
++------------------+-----------------+
+| 3V3\ :sub:`P`    | ~0(without SOM) |
++------------------+-----------------+
+
+Each voltage is measured against ground (green circle in above image).
+
+3. Plug in the SOM.
+
+
+Attaching a USB to Serial Adapter
+---------------------------------
+
+.. _attach-usb-to-serial-adapter-1:
+
+1. Solder in the UART debug plug
+2. Attach USB to Serial Adapter
+
+.. figure:: images/uart-pinout.png
+   :scale: 50%
+   :alt: UART pinout (click to enlarge)
+
+   UART pinout
+
++-----+-------+
+| PIN | Color |
++=====+=======+
+| 1   | black |
++-----+-------+
+| 2   | n/c   |
++-----+-------+
+| 3   | n/c   |
++-----+-------+
+| 4   | green |
++-----+-------+
+| 5   | white |
++-----+-------+
+| 6   | n/c   |
++-----+-------+
+
+PIN 1 is the one closest to the volume button while PIN 6 is the one
+closest to the power button.
+
+
+Booting via nfsroot
+-------------------
+
+The SOM comes with a pre-flashed u-boot so you can connect the
+USB-to-UART-Debug cable and boot the device. Breaking into uboot you can
+boot using a nfsroot filesystem via
+
+::
+
+   setenv nfsrootboot "setenv bootargs ${args_common} debug root=/dev/nfs ip=:::::eth0:dhcp nfsrootdebug nfsroot=<nfsserverip>:<nfsrootpath>,v3,tcp; dhcp ${loadaddr} Image-librem5-devkit; dhcp ${fdt_addr} librem5-devkit.dtb; booti ${loadaddr} - ${fdt_addr}"
+   setenv bootcmd run nfsrootboot
+   saveenv
+   boot
+
+You need to fill in **nfsrootpath** and **nfsserverip** above. At
+**nfsrootpath** there needs to be a armhf or arm64 root filesystem which
+you can e.g. create via Debian's deboostrap.
+
+For that to work the **BOOT MODE** switch needs to be set to **eMMC**
+(instead of **USB**).
+
+
+Installing a Minimal Linux on the eMMC
+--------------------------------------
+
+You can use ``dd`` to copy a pre-built image onto the eMMC or you can just use
+``debootstrap`` to create one from scratch. This can be useful if you don't
+want that many services starting up by default:
+
+.. code:: bash
+
+   e2fsck /dev/mmcblk0p2
+   mount /dev/mmcblk0p2 /mnt
+   debootstrap --arch=arm64 buster /mnt
+
+Back in u-boot we can switch to using the rootfs on the eMMC then (we're
+still pulling kernel and device tree via tftp though:
+
+::
+
+   setenv emmcboot "setenv bootargs ${args_common} debug root=/dev/mmcblk0p2; dhcp ${loadaddr} Image-librem5-devkit; dhcp ${fdt_addr} librem5-devkit.dtb; booti ${loadaddr} - ${fdt_addr}"
+
+
+Flashing u-boot
+---------------
+
+From u-boot using tftp
+~~~~~~~~~~~~~~~~~~~~~~
+
+You must have a tftp server setup for this:
+
+::
+
+   setenv ipaddr <tftp server ip>
+   setenv serverip <target ip addr>
+   tftp 0x43000000 u-boot-devkit-recovery.imx
+   mmc write 0x43000000 0x42 0x800
+
+From the kernel command line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Download the u-boot binary ``u-boot-devkit-recovery.imx``:
+
+::
+
+   dd if=u-boot-devkit-recovery.imx of=/dev/mmcblk0 bs=1024 seek=33
+
+
+Reflashing the RS9116
+---------------------
+
+By default no rsi\ :sub:`\*` modules get loaded. The modules without
+firmware are in
+"/lib/modules/<kernel:sub:`ver`>/drivers/net/wireless/rsi" . The
+create\ :sub:`initramfs` script above adds the rsi firmware and reflash
+modules in "/usr/src".
+
+There is a convenience script "flash:sub:`rsi`.sh" that wiil perform the
+necessary steps. What the script does is it backs up the rsi modules in
+/lib/modules, copies the firmware into lib firmware and the modprobes
+the rsi flashing modules. It replaces the original modules when it's
+done.
+
+Run the script on the target to reflash.::
+
+   root@pureos-test:~# flash_rsi.sh
+
+
+Creating a Test initramfs
+-------------------------
+
+Download the latest image and kernel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Download the latest kernel and RS9116 out of tree modules.::
+
+   ./scripts/fetch_latest.sh -k
+
+Extract the kernel
+~~~~~~~~~~~~~~~~~~
+
+The kernel needs to be extracted from the deb for the SDP boot.::
+
+   ./scripts/extract_kernel.sh
+
+Build the test filesystem tarball
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This will create a minimal debian rootfs tarball to be used to create an
+initramfs. If you need additional packages you can add them to the
+packages variable in the script.::
+
+   ./scripts/create_tarball.sh
+
+Create the initramfs
+~~~~~~~~~~~~~~~~~~~~
+
+This will take the tarball created above and customize it to be able to
+flash the RS9116 module and also adds some test scripts.::
+
+   ./scripts/create_initramfs.sh -t build/test_rootfs.tgz -o files/test_initramfs.img
+
+You can include a locally generated kernel, modules and devicetree as
+well.::
+
+   ./scripts/create_initramfs.sh -t build/test_rootfs.tgz -o files/test_initramfs.img -i <path to kernel>
+
+Boot the initramfs
+~~~~~~~~~~~~~~~~~~
+
+The initramfs can be booted on a board with an empty eMMC for testing
+and RS9116 flashing. Ensure the boot mode switch is switched to USB
+boot. Run the command below and then plug in the USB C port of the
+devkit.::
+
+   sudo uuu uuu_scripts/test_librem5.lst
+
+RS9116 normal operation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To use the RS9116 without flashing just load the modules by hand.::
+
+   root@pureos-test:~# modprobe rsi_sdio

Development_Environment/Boards/imx8.rst

 .. _imx8_devkit:
 
-i.MX8 Development Board
-=======================
+Librem 5 Development Kit
+========================
 
 .. note:: This page is incomplete and is being revised.
 
-Installing the SOM
-------------------
+The scripts mentioned on this page can be obtained from the `librem5-devkit-tools`_
+repository.
 
-.. If the SOM is not yet installed
+If you experience problems with the development kit, you may find it useful to
+consult the :ref:`imx8_devkit_troubleshooting` guide.
 
-Power board without SOM via USB-C
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _`librem5-devkit-tools`: https://source.puri.sm/Librem5/librem5-devkit-tools
 
-Check the voltages
-~~~~~~~~~~~~~~~~~~
+.. Sections to add:
+   What's in the box
+   plugging in via USB-C (power adaptor vs. hub),
+   connecting via ssh, connecting HDMI, mouse, keyboard
+   900mA supply
+   Host mode, hub, no serial out
+   Device mode, serial
+   USB 2 to USB 3 hub to USB-C devkit
+   FTDI cables USB-to-serial
 
-.. figure:: images/voltage-points.png
-   :scale: 50%
-   :alt: The voltage points to measure
+.. contents::
 
-   The voltage points to measure (click to enlarge)
-
-+------------------+-----------------+
-| Point            | Voltage         |
-+==================+=================+
-| VBUS             | 5.2V            |
-+------------------+-----------------+
-| VBAT             | 4.2V            |
-+------------------+-----------------+
-| VBAT\ :sub:`REG` | 4.2V            |
-+------------------+-----------------+
-| 5V\ :sub:`SOM`   | 5.0V            |
-+------------------+-----------------+
-| 3V3              | 3.3V            |
-+------------------+-----------------+
-| 3V3\ :sub:`P`    | ~0(without SOM) |
-+------------------+-----------------+
-
-Each voltage is measured against ground (green circle in above image).
+Connecting the Board to a Power Supply
+--------------------------------------
 
-Plugin the SOM
-~~~~~~~~~~~~~~
+In the default configuration, as shipped, USB in is peripheral mode and a
+"wall wart" AC adaptor is used for power.
 
-Attach USB to serial adapter
-----------------------------
+Alternate Configuration #1 - USB C Console
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Solder in the UART debug plug
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ 1. Attach the development board to a USB C or USB 3 port on the host that is
+    capable of providing 900mA of current.
 
-.. _attach-usb-to-serial-adapter-1:
+ 2. ~30 seconds after boot a new device will appear at ``/dev/ttyACM0`` -- this
+    is a serial console to the development board.
 
-Attach USB to serial Adapter
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If your PC cannot provide the necessary power you may need a USB 3 powered hub
+between the host and the development board.
 
-.. figure:: images/uart-pinout.png
-   :scale: 50%
-   :alt: UART pinout (click to enlarge)
+Alternate Configuration #2 - USB C Host
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   UART pinout
+In this configuration, USB host mode is used to allow keyboard, mouse and flash
+memory sticks to be connected to the development board.
 
-+-----+-------+
-| PIN | Color |
-+=====+=======+
-| 1   | black |
-+-----+-------+
-| 2   | n/c   |
-+-----+-------+
-| 3   | n/c   |
-+-----+-------+
-| 4   | green |
-+-----+-------+
-| 5   | white |
-+-----+-------+
-| 6   | n/c   |
-+-----+-------+
+ 1. On the target, backup the device tree and copy in the USB host version::
 
-PIN 1 is the one closest to the volume button while PIN 6 is the one
-closest to the power button.
+      cp /boot/dtbs/librem5-evk.dtb /boot/dtbs/librem5-evk.dtb.bak
+      cp /boot/dtbs/librem5-evk-usbhost.dtb /boot/dtbs/librem5-evk.dtb
+   
+ 2. Attach a USB C hub to the development board.
+ 3. Attach power to the USB C hub.
+ 4. Plug in USB devices and they should appear in the output of the ``dmesg``
+    and ``lsusb`` tools.
 
 Power on/off
 ------------
 
-If the user holds the power button for ~2 seconds then a power
-down/reboot dialog would pop up; a quick press & release would turn the
-display on/off. If the button is held for ~5 seconds the SoC triggers an
-event to shut down, pressing it again for ~2 seconds will turn it back
-on. The button is also attached to the charge controller's QON# pin,
-which when held for ~15 seconds is able to put the dev kit into a
-"shipping mode" where the charge controller is completely off, or
-holding it for ~18 seconds will cause it to perform a complete power
-cycle.
-
-Booting via nfsroot
--------------------
-
-The SOM comes with a pre-flashed u-boot so you can connect the
-USB-to-UART-Debug cable and boot the device. Breaking into uboot you can
-boot using a nfsroot filesystem via
-
-::
-
-   setenv nfsrootboot "setenv bootargs ${args_common} debug root=/dev/nfs ip=:::::eth0:dhcp nfsrootdebug nfsroot=<nfsserverip>:<nfsrootpath>,v3,tcp; dhcp ${loadaddr} Image-librem5-devkit; dhcp ${fdt_addr} librem5-devkit.dtb; booti ${loadaddr} - ${fdt_addr}"
-   setenv bootcmd run nfsrootboot
-   saveenv
-   boot
-
-You need to fill in **nfsrootpath** and **nfsserverip** above. At
-**nfsrootpath** there needs to be a armhf or arm64 root filesystem which
-you can e.g. create via Debian's deboostrap.
+On a development kit with an operating system installed, if the user holds the
+power button for ~2 seconds then a power down/reboot dialog should pop up; a
+quick press and release should turn the display on/off.
 
-For that to work the **BOOT MODE** switch needs to be set to **eMMC**
-(instead of **USB**).
+If the button is held for ~5 seconds the SoC triggers an event to shut down;
+pressing it again for ~2 seconds will turn it back on.
 
-Installing a minimal Linux on the eMMC
---------------------------------------
-
-You can use ``dd`` to copy a pre-built image onto the eMMC or you can just use
-``debootstrap`` to create one from scratch. This can be useful if you don't
-want that many services starting up by default:
-
-.. code:: bash
-
-   e2fsck /dev/mmcblk0p2
-   mount /dev/mmcblk0p2 /mnt
-   debootstrap --arch=arm64 buster /mnt
-
-Back in u-boot we can switch to using the rootfs on the eMMC then (we're
-still pulling kernel and device tree via tftp though:
-
-::
-
-   setenv emmcboot "setenv bootargs ${args_common} debug root=/dev/mmcblk0p2; dhcp ${loadaddr} Image-librem5-devkit; dhcp ${fdt_addr} librem5-devkit.dtb; booti ${loadaddr} - ${fdt_addr}"
+The button is also attached to the charge controller's QON# pin, which when
+held for ~15 seconds is able to put the dev kit into a "shipping mode" where
+the charge controller is completely off, or holding it for ~18 seconds will
+cause it to perform a complete power cycle.
 
 Install uuu
 -----------
 
-By hand
+.. There is apparently a Debian package for this.
+
+By Hand
 ~~~~~~~
 
-The NXP mfgtool uuu is required to boot a board that has no bootloader
-or is otherwise "bricked". Either download, build and install uuu :
+The NXP mfgtool ``uuu`` is required to boot a board that has no bootloader
+or is otherwise "bricked". Either download, build and install ``uuu``:
 
 ::
 
@@ -150,21 +93,60 @@ or is otherwise "bricked". Either download, build and install uuu :
    make
    sudo make install
 
-Using the convenient script
+Using the Convenient Script
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Alternatively, you can use this script from the `librem5-devkit-tools`_
+repository to build and install ``uuu``:
+
 ::
 
    scripts/build_uuu.sh -i
 
+Udev Rules
+----------
+
+If you want to run ``uuu`` as non-root add the following udev rules
+
+.. code:: bash
+
+   cat <<EOF > /etc/udev/rules.d/99_librem5_devkit.rules
+   SUBSYSTEM!="usb", GOTO="librem5_devkit_rules_end"
+   # Devkit USB flash
+   ATTR{idVendor}=="1fc9", ATTR{idProduct}=="012b", GROUP+="plugdev", TAG+="uaccess"
+   ATTR{idVendor}=="0525", ATTR{idProduct}=="a4a5", GROUP+="plugdev", TAG+="uaccess"
+   ATTR{idVendor}=="0525", ATTR{idProduct}=="b4a4", GROUP+="plugdev", TAG+="uaccess"
+   LABEL="librem5_devkit_rules_end"
+   EOF
+   sudo udevadm control -R
+   sudo adduser <youruser> plugdev
+   newgrp plugdev
+
+Make sure you replug the serial cable in case you have plugged it in
+already. With the above rules you can skip the ``sudo`` in front of the
+``uuu`` invocations below.
+
+.. _imx8_devkit_flash_test_image:
+
+Flash the Test Image
+--------------------
+
+The eMMC that gets flashed is ``files/devkit-test.img``. Put the "Boot
+Mode" switch in the USB position.
+
+**This will erase everything on your eMMC:**
+
+::
+
+   scripts/get_image.sh
+   sudo uuu uuu_scripts/flash_librem5-devkiti-test.lst
+
 Download Target Binaries
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can manually download or build the required binaries. There is also
 a convenience script to download pre-built binaries from the Purism
-servers.
-
-::
+servers.::
 
    scripts/fetch_latest.sh -xk
 
@@ -187,27 +169,6 @@ You can also just boot to u-boot without flashing anything:
 
    sudo uuu uuu_scripts/u-boot_librem5-devkit.lst
 
-From u-boot using tftp
-~~~~~~~~~~~~~~~~~~~~~~
-