doc: boards: pollux: revise debug instructions

Revise and simplify build and debug instructions by documenting the regular
Zephyr way with west.

Signed-off-by: Jonas Remmert <j.remmert@phytec.de>

boards/phytec/mimx8mp_phyboard_pollux/doc/index.rst

@@ -47,8 +47,7 @@ Board features:
    :height: 405px
    :alt: PhyBOARD Pollux
 
-More information about the board can be found at the
+More information about the board can be found at the `PHYTEC website`_.
-`PHYTEC website`_.
 
 Supported Features
 ==================
@@ -78,10 +77,8 @@ The default configuration can be found in the defconfig file:
 :zephyr_file:`boards/phytec/mimx8mp_phyboard_pollux/mimx8mp_phyboard_pollux_mimx8ml8_m7_defconfig`.
 
 It's recommended to disable peripherals used by the M7-Core on the host running
-on the Linux host.
+on the Linux host. Other hardware features are not currently supported with
-
+Zephyr on the M7-Core.
-Other hardware features are not currently supported with Zephyr on the
-M7-Core.
 
 Connections and IOs
 ===================
@@ -102,21 +99,16 @@ UART
 +-----------------+----------+----------------------------+
 
 .. note::
-  Please note, that the, to UART3 connected, Wifi/BLE Module isn't working with
+  The WiFi/BLE Module connected to UART3 isn't working with Zephyr yet. UART3
-  Zephyr yet. UART3 can also be used through pin 31(RX) and 33(TX) of the
+  can also be used through pin 31(RX) and 33(TX) of connector X6.
-  X6 Connector.
 
 GPIO
 ----
 
 The pinmuxing for the GPIOs is the standard pinmuxing of the mimx8mp devicetree
-created by NXP. You can find it here:
+created by NXP and can be found at
-
+:zephyr_file:`dts/arm/nxp/nxp_imx8ml_m7.dtsi`. The Pinout of the PhyBOARD Polis
-:zephyr_file:`dts/arm/nxp/nxp_imx8ml_m7.dtsi`.
+can be found at the `PHYTEC website`_.
-
-The Pinout of the PhyBOARD Polis can be found here:
-
-`PHYTEC website`_
 
 Programming and Debugging
 *************************
@@ -124,8 +116,6 @@ Programming and Debugging
 The i.MX8MP does not have a separate flash for the M7-Core. Because of this
 the A53-Core has to load the program for the M7-Core to the right memory
 address, set the PC and start the processor.
-This can only by done with u-boot at the moment. We are working on our BSP to
-enable remoteproc support.
 
 The M7 can use up to 3 different RAMs (currently, only two configurations are
 supported: ITCM and DDR). These are the memory mapping for A53 and M7:
@@ -151,20 +141,17 @@ At compilation time you have to choose which memory region will be used. This
 configuration is done in the devicetree and the defconfig / the config of your
 program.
 
-**By default Zephyr will use the TCM memory region.** You can configure it like
+**By default Zephyr will use the TCM memory region.** You can configure it
-this for the DDR region:
+to use the DDR region. In the devicetree overwrite you can select both options.
-
-In the devicetree overwrite the following nodes like this:
 
 .. code-block:: DTS
 
    chosen {
       /* TCM */
       zephyr,flash = &itcm;
-	   zephyr,sram = &dtcm;
+      zephyr,sram = &dtcm;
    };
 
-change it to
 
 .. code-block:: DTS
 
@@ -175,55 +162,45 @@ change it to
    };
 
 
-In your prj.conf overwrite the configuration like this for the **DDR** memory
+And in the prj.conf the configuration to the **DDR** memory region:
-region:
 
 .. code-block:: cfg
 
    CONFIG_CODE_DDR=y
    CONFIG_CODE_ITCM=n
 
+Connecting to the Serial Console
+================================
 
-Starting the M7-Core via U-Boot
+A serial console for both the application CPU and the Cortex M7 coprocessor are
+available via the onboard dual USB-to-UART converter. If you use Linux, create a
+udev rule (as ``root``) to fix a permission issue when not using root for
+flashing.
+
+.. code-block:: console
+
+   # echo 'ATTR{idProduct}=="0a70", ATTR{idVendor}=="10c4", MODE="0666", GROUP="plugdev"' > /etc/udev/rules.d/50-usb-uart.rules
+
+Reload the rules and replug the device.
+
+.. code-block:: console
+
+   $ sudo udevadm control --reload-rules
+
+Finally, unplug and plug the board again for the rules to take effect.
+
+Connect to the console via your favorite terminal program. For example:
+
+.. code-block:: console
+
+   $ minicom -D /dev/ttyUSB1 -b 115200
+
+Flashing and Debugging via JTAG
 ===============================
 
-Load the compiled zephyr.bin to memory address 0x4800000.
+The PhyBOARD-Pollux can be debugged using a JTAG or SWD debug adapter. A Segger
-This should output something like this:
+JLink can be connected to the compatible JTAG connector on Phytec's
-
+``PEB-EVAL-01`` shield.
-.. code-block:: console
-
-   u-boot=> tftp 0x48000000 192.168.3.10:zephyr.bin
-   Using ethernet@30be0000 device
-   TFTP from server 192.168.3.10; our IP address is 192.168.3.11
-   Filename 'zephyr.bin'.
-   Load address: 0x48000000
-   Loading: ##
-            2 KiB/s
-   done
-   Bytes transferred = 27240 (6a68 hex)
-
-Because it's not possible to load directly to the TCM memory area you have to
-copy the binaries. The last argument given is the size of the file in bytes,
-you can copy it from the output of the last command.
-
-.. code-block:: console
-
-   u-boot=> cp.b 0x48000000 0x7e0000 27240
-
-And finaly starting the M7-Core at the right memory address:
-
-.. code-block:: console
-
-   u-boot=> bootaux 0x7e0000
-   ## Starting auxiliary core stack = 0x20003A58, pc = 0x1FFE1905...
-
-Debugging
-=========
-
-The PhyBOARD Polis can be debugged using a JTAG Debugger.
-The easiest way to do that is to use a SEGGER JLink Debugger and Phytec's
-``PEB-EVAL-01`` Shield, which can be directly connected to the JLink.
-You can find the JLink Software package here: `JLink Software`_
 
 .. figure:: img/PEB-EVAL-01.jpg
    :alt: PEB-EVAL-01
@@ -231,37 +208,47 @@ You can find the JLink Software package here: `JLink Software`_
 
    PEB-EVAL-01
 
-To debug efficiently you have to use multiple terminals:
+Before flashing or debugging via a JTAG debug adapter,
-
+the M7 core has to be switched on:
-After connecting everything and building with west use this command while in
-the directory of the program you build earlier to start a debug server:
 
 .. code-block:: console
 
-   host$ west debugserver
+   u-boot=> bootaux 0x7e0000
 
-West automatically connects via the JLink to the Target and keeps open a
+Here is an example for the :ref:`hello_world` application:
-debug server.
 
-Use another terminal, start gdb, connect to target and load Zephyr on the
+.. zephyr-app-commands::
-target:
+   :zephyr-app: samples/hello_world
+   :board: mimx8mp_phyboard_pollux/mimx8ml8/m7
+   :goals: flash
+
+The console should now show the output of the application:
 
 .. code-block:: console
 
-   host$ gdb-multiarch build/zephyr/zephyr.elf -tui
+   *** Booting Zephyr OS build v3.7.0 ***
-   (gdb) targ rem :2331
+   Hello World! mimx8mp_phyboard_pollux/mimx8ml8/m7
-   Remote debugging using :2331
-   0x1ffe0008 in _vector_table ()
-   (gdb) mon halt
-   (gdb) mon reset
-   (gdb) c
-   Continuing.
 
-The program can be debugged using standard gdb techniques.
+Starting a debug session is similar to flashing:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/hello_world
+   :board: mimx8mp_phyboard_pollux/mimx8ml8/m7
+   :goals: debug
+
+Starting the M7-Core from U-Boot and Linux
+==========================================
+
+Loading binaries and starting the M7-Core is supported from Linux via remoteproc
+or from U-boot by directly copying the firmware binary. Please check the
+`phyCORE-i.MX 8M Plus BSP Manual`_ for more information.
 
 References
 ==========
 
+- `i.MX 8M Plus Applications Processor Reference Manual`_
+- `phyCORE-i.MX 8M Plus BSP Manual`_
+
 .. _PHYTEC website:
    https://www.phytec.de/produkte/single-board-computer/phyboard-pollux/
 
@@ -270,3 +257,6 @@ References
 
 .. _JLink Software:
    https://www.segger.com/downloads/jlink/
+
+.. _phyCORE-i.MX 8M Plus BSP Manual:
+   https://phytec.github.io/doc-bsp-yocto/bsp/imx8/imx8mp/imx8mp.html