dev: Add more linux pages

Add pages about kernel config, init scripts, startup options, and board porting.

Also add a new landing page.

dev/source/docs/ardupilot-on-linux-init-scripts.rst

@@ -0,0 +1,106 @@
+.. _ardupilot-on-linux-init-scripts:
+
+============================
+Linux Initialization Scripts
+============================
+
+
+Example Systemd Unit Files
+==========================
+
+Adjust as needed and place in /etc/defaults/ardupilot
+
+::
+
+    # ArduPilot configuration options
+
+    # Serial port configuration
+    # Uncomment and update as needed
+    # See "Startup Options" under "ArduPilot on Linux" in dev wiki for more information.
+    #SERIAL0=--serial0 tcp:192.168.1.26:12345:nowait
+    #SERIAL1=--serial1 /dev/ttyS0
+    #SERIAL2=
+    #SERIAL3=
+    #SERIAL4=
+    #SERIAL5=
+    #SERIAL6=
+    #SERIAL7=
+    #SERIAL8=
+    #SERIAL9=
+
+    # change log directory (Optional)
+    #LOG_DIRECTORY=--log-directory /var/APM/logs
+
+    # change terrain directory (Optional)
+    #TERRAIN_DIRECTORY=--terrain-directory /var/APM/terrain
+
+    # change storage path (Optional)
+    #STORAGE_DIRECTORY=--storage-directory /var/APM/storage
+
+    # Configure CPU affinity (Optional)
+    #CPU_AFFINITY=--cpu-affinity 1 #a single CPU, or range(1-3)
+
+This board-specific one-shot script should contain any system-level
+configuration required for running ardupilot. Adjust as needed, and
+place in /etc/systemd/system/ardupilot-sysconfig.service .
+
+::
+
+    [Unit]
+    Description=Configure system for realtime operation
+
+    [Service]
+    Type=oneshot
+
+    # Lock CPU governor to top speed for reduced jitter caused by clock tree changes
+    # For more information, https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt
+    ExecStart=/bin/sh -c "/bin/echo performance | tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor"
+
+This build-type specific script contains the startup options.
+Adjust as needed(and per-build), and place in /etc/systemd/system/arduplane.service
+
+::
+
+    [Unit]
+    Description=ArduPlane Service
+    After=ardupilot-sysconfig.service
+    Requires=ardupilot-sysconfig.service
+
+    # Do not attempt to run multiple ardupilot services at a time,
+    # as they will almost certainly conflict.
+    Conflicts=arducopter.service ardupilot.service ardurover.service
+
+    [Service]
+    #Run arduplane using environment configured in /etc/default/ardupilot
+    EnvironmentFile=/etc/default/ardupilot
+
+    #  See "Startup Options" under "ArduPilot on Linux" in dev wiki for more information.
+    #  Configure the serial ports according to board.
+    #  Configure cpu-affinity according to board or remove.
+    ExecStart=/usr/local/bin/arduplane \
+        $SERIAL0 \
+        $SERIAL1 \
+        $SERIAL2 \
+        $SERIAL3 \
+        $SERIAL4 \
+        $SERIAL5 \
+        $SERIAL6 \
+        $SERIAL7 \
+        $SERIAL8 \
+        $SERIAL9 \
+        $LOG_DIRECTORY \
+        $TERRAIN_DIRECTORY \
+        $STORAGE_DIRECTORY \
+        $CPU_AFFINITY
+
+    Restart=on-failure
+
+    [Install]
+    WantedBy=multi-user.target
+
+To start, ``sudo systemctl start arduplane``.
+To check on it, ``sudo systemctl status arduplane``.
+To restart, ``sudo systemctl restart arduplane``.
+To stop, ``sudo systemctl stop arduplane``.
+To enable service startup at boot, ``sudo systemctl enable arduplane``
+Note that only one build must be running at a time.

dev/source/docs/ardupilot-on-linux-kernel-configuration.rst

@@ -0,0 +1,30 @@
+.. _ardupilot-on-linux-kernel-configuration:
+
+==========================
+Linux Kernel Configuration
+==========================
+
+Real-Time Patches
+=================
+For some builds, ArduPilot needs to run sensors, control loop, and output
+interfaces at high rates, with bounded latency to maintain stable
+operation. For this reason, it is suggested to run a real-time kernel.
+
+Builds like rover, sub, and tracker may be fine without it.
+
+Userspace access to hardware peripherals on 64-bit boards
+=========================================================
+The default kernel configuration for many 64-bit boards blocks
+even the root user from mmap()ing the peripheral device address space,
+allowing only the kernel to access it.
+
+For many boards, ArduPilot will need such access, so CONFIG_STRICT_DEVMEM
+or CONFIG_IO_STRICT_DEVMEM will need to be disabled.
+
+32-bit kernels are unaffected.
+
+Preventing CPU idle states
+==========================
+The kernel command line option ``cpuidle.off=1`` prevents CPU cores from
+entering idle states. This can be useful on CPUs where exiting idle
+states is slow.

dev/source/docs/ardupilot-on-linux-porting.rst

@@ -0,0 +1,135 @@
+.. _ardupilot-on-linux-porting:
+
+=========================================
+Porting to a new flight controller board
+=========================================
+
+This section is for topics related to running ArduPilot directly on Linux boards.
+See this :ref:`page for porting to boards running ChibiOS <porting>`.
+
+.. note:: Any firmware customization of ArduPilot code must abide by the terms of the GPL3.0+ open source code license. ArduPilot also reminds developers and manufacturers to adhere to the appropriate trademark and copyright laws when developing new autopilots
+
+.. image:: ../../../images/gpl3.png
+    :target: https://www.gnu.org/licenses/gpl-3.0.en.html
+
+Consider joining the `ArduPilot Discord Chat <https://ardupilot.org/discord>`__, to speak with other developers about this topic under the HAL-DEV, #Linux channel.
+
+Step 1 - getting started
+========================
+
+- Determine which microprocessor the new flight controllers uses. If it is used in a board we already support, for example BCM283x used in Raspberry Pi or TI Sitara/OMAP used in BeagleBones, then the port should be relatively straight forward.
+- Choose a new board name.
+- Reserve a new HAL_BOARD_SUBTYPE_LINUX_$(NEW_BOARD_NAME) in libraries/AP_HAL/AP_HAL_Boards.h
+- Ensure the spidev and i2cdev kernel modules are built if ArduPilot will be using them.
+
+.. tip:: Choose your board name carefully! Use 13 characters or less for your board name, otherwise it may be truncated when the board name is sent from the flight controller to a ground station such as Mission Planner.
+
+Step 2 - Toolchain Configuration
+================================
+
+In Tools/ardupilotwaf/boards.py:
+
+- Create a new class and select the appropriate toolchain, usually arm-linux-gnueabihf. For an example see "class pxfmini(linux) as an example"
+- Update CONFIG_HAL_BOARD_SUBTYPE with the newly reserved board subtype.
+
+In Tools/scripts/board_list.py:
+
+- Add new board name to self.boards[] list.
+
+Step 3 - configure and build examples and firmware for the board
+================================================================
+
+Follow the :ref:`Building the code <building-the-code>` instructions or take a shortcut and read the `BUILD.md <https://github.com/ArduPilot/ardupilot/blob/master/BUILD.md>`__ file which includes doing the following:
+
+- ``cd ardupilot`` (or wherever you have :ref:`cloned <git-clone>` ArduPilot to)
+- ``./waf configure --board new-board``
+- ``./waf copter``
+
+Work through any issues highlighted by '#error' messages in the codebase, which will require per-board configuration.
+
+This is also a good time to build any relevant :ref:`Library Example Sketches <learning-ardupilot-the-example-sketches>`.
+
+Step 4 - upload and run the examples and firmware
+=================================================
+
+If building natively, executables are already loaded on the target system, and can be executed directly.
+
+If using waf to upload (Linux, MacOSX only), see configuration commands in `BUILD.md <https://github.com/ArduPilot/ardupilot/blob/master/BUILD.md>`__ 
+to set up waf's --upload flag. Other options for cross-compiled builds include SCP or NFS.
+
+See :ref:`Startup options <ardupilot-on-linux-starting>` for command-line options, configuring at least one port for MavLink, and launching ArduPilot.
+
+Step 5 - peripheral functions and drivers
+=========================================
+
+Many boards will use the Linux userspace APIs for I2C, UART, and SPI and only need configuration and associated kernel modules.
+See your CPU, BSP, and board's documentation for pin muxing and device tree configuration. The following peripherals tend to be more complicated.
+
+SPI Support
+-----------
+To configure SPI-based devices, the Linux userspace SPI APIs are used, needing only the per-board configuration(bus ID, chip select ID, mode, rates) in SPIDeviceManager::_device[] in libraries/AP_HAL_Linux/SPIDevice.cpp.
+
+GPIO Support
+------------
+Most ArduPilot Linux boards use one of two methods for GPIO access: sysfs or mmap.
+
+For sysfs:
+
+- GPIO access through sysfs is deprecated.
+- Create new libraries/AP_HAL_Linux/GPIO_$(NEW_BOARD_NAME).cpp and .h, filled out with the needed _$(NEW_BOARD_NAME)_GPIO_MAX and pin_table.
+
+For libgpiod(Todo):
+
+- port ardupilot to support a libgpiod backend of pinMode(), read(), write().
+- Implement the per-board configuration
+
+For mmap():
+
+- See GPIO_BBB.cpp and GPIO_RPI.cpp as examples
+- Create new libraries/AP_HAL_Linux/GPIO_$(NEW_BOARD_NAME).cpp and .h
+- Locate the memory file, either /dev/mem or /dev/gpiomem, and open() it.
+- Locate the offset of the GPIO memory region in the file. If using /dev/mem, check the processor reference manual or Linux device-tree files. For /dev/gpiomem, use zero.
+- mmap() the GPIO registers into ArduPilot using the above offset.
+- Implement pinMode(), read(), write() functions using the memory mapped GPIO registers.
+
+.. tip:: CPUs with multiple GPIOs per bank with only a DATA or OUT register without SET and CLEAR registers may need to avoid the mmap backend, as read-modify-write accesses to a GPIO DATA register may not be threadsafe when the kernel or other userspace programs use GPIOs in the same bank.
+
+For either approach, edit libraries/AP_HAL_Linux/GPIO.h to include the appropriate GPIO_$(NEW_BOARD_NAME) header for the board.
+
+RCInput
+-------
+Several different RCInput mechanisms are supported by different boards, including PPM, SBUS, UART, and UDP.
+
+PPM input is handled per-CPU, usually with either a DMA or utility microcontroller like the PRU on TI chips.
+
+Examine the libraries/AP_HAL_Linux/RCInput_* files to see if a suitable one exists, or create one.
+
+Configure rcinDriver in libraries/AP_HAL_Linux/HAL_Linux_Class.cpp using CONFIG_HAL_BOARD_SUBTYPE.
+
+RCOutput
+--------
+Similar to RCInput, examine the libraries/AP_HAL_Linux/RCOutput_* files to see if a suitable one exists, or create one.
+
+For CPUs without corresponding hardware to generate RCOutput signals, additional hardware may be used, like NXP's PCA9685 for PWM generation.
+
+Configure the rcoutDriver in libraries/AP_HAL_Linux/HAL_Linux_Class.cpp using CONFIG_HAL_BOARD_SUBTYPE.
+
+Step 7 - bring up the sensors
+=============================
+
+Add sensor related configuration to libraries/AP_HAL/board/linux.h.
+
+Start with the baro first, then IMU, then compass and finally any other sensors
+the default sensor orientation should also be filled in along with other things.
+
+Upload the examples and firmware and test the sensors are working.
+
+Step 8 - configure parameter, log, and terrain storage
+======================================================
+
+Configure HAL_BOARD_LOG_DIRECTORY, HAL_BOARD_TERRAIN_DIRECTORY, HAL_BOARD_STORAGE_DIRECTORY in libraries/AP_HAL/board/linux.h.
+
+Next Steps
+==========
+
+If you have gotten this far, congratulations you have ported ArduPilot to a new board!  Please reach out to the other developers on the `ArduPilot Discord Chat <https://ardupilot.org/discord>`__ to announce your success.

dev/source/docs/ardupilot-on-linux-starting.rst

@@ -0,0 +1,59 @@
+.. _ardupilot-on-linux-starting:
+
+===============
+Startup Options
+===============
+
+Run a build with -\-help to see the latest command-line options.
+
+-\-serial#
+==========
+
+This command line argument, with # replaced by a number, is used to connect the an ArduPilot serial port to a serial device or network protocol.
+May also use old-style(-A, -B, ...).
+
+For each ArduPilot serial port, specify either a device file or a short string to configured the network protocol below.
+The user account running ardupilot should be added to the dialout group to access serial ports.
+
+Serial Ports: /dev/deviceFile
+	- -\-serial0 /dev/ttyAMA0
+	- -\-serial1 /dev/ttyS0
+TCP networking: tcp:<IP address>:<PortNumber>
+	- -\-serial2 tcp:11.0.0.2:5678
+	- -\-serial3 tcp:192.168.2.15:1243:wait
+	- -\-serial4 udp:11.0.0.2:14550
+UDP networking: udp:<IP address>:<PortNumber>
+	- -\-serial5 udp:11.0.0.255:14550:bcast
+	- -\-serial6 udpin:0.0.0.0:14550
+
+Additional UDP/TCP options:
+	- wait: wait for connection(TCP)
+	- bcast: use broadcast address(UDP)
+
+-\-log-directory
+================
+Directory used for logging. May also use -l.
+
+Default is the per-board HAL_BOARD_LOG_DIRECTORY.
+
+-\-terrain-directory
+====================
+Directory used for terrain. May also use -t.
+
+Default is the per-board HAL_BOARD_TERRAIN_DIRECTORY.
+
+-\-storage-directory
+====================
+Directory used for storage. May also use -s.
+
+Default is the per-board HAL_BOARD_STORAGE_DIRECTORY.
+
+-\-module-directory
+===================
+Directory used for modules. May also use -M.
+
+Default is the per-board AP_MODULE_DEFAULT_DIRECTORY.
+
+-\-cpu-affinity
+===============
+CPUs to bind ArduPilot. May also use -c. May specify a single cpu(1), multiple cpus(1,3), or a range(1-3)

dev/source/docs/ardupilot-on-linux.rst

@@ -0,0 +1,17 @@
+.. _ardupilot-on-linux:
+
+==================
+ArduPilot on Linux
+==================
+
+This section is for topics related to running ArduPilot directly on Linux boards.
+
+.. toctree::
+    :maxdepth: 1
+
+    Debugging with GDB <debugging-with-gdb>
+    LTTng tracing <using-linux-trace-toolkit-ng-lttng-to-trace-ardupilot-in-realtime>
+    Daemon init scripts<ardupilot-on-linux-init-scripts>
+    Kernel configuration<ardupilot-on-linux-kernel-configuration>
+    Startup options<ardupilot-on-linux-starting>
+    Porting to a new Flight Controller<ardupilot-on-linux-porting>

dev/source/index.rst

@@ -142,6 +142,7 @@ Table of Contents
     Learning the code <docs/learning-the-ardupilot-codebase>
     Simulation & Testing <docs/simulation-2>
     Debugging <docs/debugging>
+    ArduPilot On Linux <docs/ardupilot-on-linux>
     Support Proxy <docs/support_proxy>
     Contributing Code <docs/contributing>
     MAVLink Interface <docs/mavlink-commands>