[STM32MP157_DK] README: Add VirtIO

ABOSTM · kbumsik · commit f7c1d95f5fb9 · 2020-03-15T12:30:20.000+09:00
diff --git a/variants/STM32MP157_DK/README.md b/variants/STM32MP157_DK/README.md
@@ -43,7 +43,8 @@ In this example, the user **must** upload `<Arduino build output path>/run_ardui
 After uploading the user can use `sh run_arduino_<sketch name>.sh start` in the console of host Linux via either SSH or Serial Console, to run the Arduino firmware.
 
 #### Note
- * `sh run_arduino_<sketch name>.sh start` is a one-shot command, the Arduino firmware only runs for the current boot. If you want to make it run after reboot, you need to use `sh run_arduino_<sketch name>.sh install` command. 
+
+* `sh run_arduino_<sketch name>.sh start` is a one-shot command, the Arduino firmware only runs for the current boot. If you want to make it run after reboot, you need to use `sh run_arduino_<sketch name>.sh install` command.
 
 `run_arduino_<sketch name>.sh` help page summary:
 
@@ -63,6 +64,21 @@ After uploading the user can use `sh run_arduino_<sketch name>.sh start` in the
     sh run_arduino_<sketch name>.sh uninstall
         Uninstall the autostart service.
 
+    sh run_arduino_<sketch name>.sh monitor
+        Monitor data received from the coprocessor via the virtual serial.
+
+    sh run_arduino_<sketch name>.sh send-msg <message...>
+        Send a message to the coprocessor via the virtual serial.
+
+    sh run_arduino_<sketch name>.sh send-file <filename>
+        Send a file content to the coprocessor via the virtual serial.
+
+    sh run_arduino_<sketch name>.sh minicom
+        Launch minicom interactive serial communication program.
+
+    sh run_arduino_<sketch name>.sh log
+        Print debugging log in OpenAMP trace buffer.
+
     sh run_arduino_<sketch name>.sh stop
         Stop the coprocessor.
 
@@ -73,6 +89,122 @@ See the source code [run_arduino_gen.sh] for the full help page and the more det
 
 [run_arduino_gen.sh] is the shell script that produces a copy of the script called `run_arduino_<sketch name>.sh` but with the sketch binary self-contained.
 
+## Virtual Serial
+
+With Virtual Serial, you can easily implement inter-core communication between the Linux host and Arduino coprocessor. Virtual Serial uses OpenAMP rpmsg framework. This is available as `SerialVirtIO` object and you can use it as a standard Arduino Serial object.
+
+Enable `SerialVirtIO` in Arduino IDE->Tools->Virtual serial support. You can optionally alias generic `Serial` object with `SerialVirtIO` as well.
+
+When enabled, `/dev/ttyRPMSG0` is available to the Linux host. You can use it as a normal serial tty. `sh run_arduino_<sketch name>.sh` provides `monitor`, `minicom`, `send-msg`, `send-file` as a convenience. See above command descriptions.
+
+See [OpenAMP] and [Linux RPMsg] to learn more.
+
+### Configuration
+
+To increase the performance of SerialVirtIO you can resize the related buffer configurations. There are three definitions you can use:
+
+* [`VRING_NUM_BUFFS`](/cores/arduino/stm32/OpenAMP/virtio_config.h)
+* [`RPMSG_BUFFER_SIZE`](/cores/arduino/stm32/OpenAMP/virtio_config.h)
+* [`VIRTIO_BUFFER_SIZE`](/cores/arduino/stm32/OpenAMP/virtio_buffer.h)
+
+The recommended option is to resize `VRING_NUM_BUFFS`. Be very cautious when resizing `RPMSG_BUFFER_SIZE`, which must be matched with the Linux kernel definition. Also `VIRTIO_BUFFER_SIZE` has the minimum required size depending on the other two. See their links above for further descriptions.
+
+To redefine these definitions, see how to create `build_opt.h` described in Debugging section below.
+
+### Virtual Serial Example
+
+Here is a basic echo example:
+```cpp
+int available;
+char buffer[1024];
+
+unsigned long time = 0;
+
+void setup() {
+  // You can SerialVirtIO.begin() and use SerialVirtIO later instead.
+  Serial.begin(); // You don't need to configure speed, it is ignored.
+  pinMode(LED_BUILTIN, OUTPUT);
+}
+
+void loop() {
+  available = Serial.available();
+  while (available > 0) {
+    int size = min(available, Serial.availableForWrite());
+    Serial.readBytes(buffer, size);
+    Serial.write(buffer, size);
+    available -= size;
+  }
+
+  // Heartbeat. If Arduino stops the LED won't flash anymore.
+  if ((millis() - time) > 1000) {
+    time = millis();
+    digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN));
+  }
+}
+```
+
+Note the use of `Serial.availableForWrite()`. SerialVirtIO has [a hard restriction of the write size], so it is important to `Serial.write()` less than the value of `Serial.availableForWrite()`.
+
+After loading Arduino, You can use SerialVirtIO in two ways in this example:
+
+* Run `sh run_arduino_<sketch name>.sh minicom` and type anything in the minicom console. The console will print out what you type immediately.
+
+* Open two Linux consoles (using SSH)
+  1. In the first console, run `sh run_arduino_<sketch name>.sh monitor`
+  2. In the second console, run `sh run_arduino_<sketch name>.sh send-msg <your message>` or `sh run_arduino_<sketch name>.sh send-file <your file>`, the first console will print the content of the message.
+
+## Debugging
+
+For printf-style debugging, `core_debug()` is highly recommended instead of using Arduino Serial. In STM32MP1, `core_debug()` utilizes OpenAMP trace buffer and it has a minimal real-time impact (other than the overhead of printf) because it is not bound to the speed of a hardware IO peripheral while printing it.
+
+Create [build_opt.h] in the sketch directory and simply put `-DCORE_DEBUG`. Additionally you can resize the buffer size of logging by redefining `VIRTIO_LOG_BUFFER_SIZE` (2kb by default). As an example you can create a file like the following:
+
+```
+build_opt.h (in the same directory of your Sketch)
+-----------------------------
+
+-DCORE_DEBUG
+-DVIRTIO_LOG_BUFFER_SIZE=4086
+```
+
+Don't forget to change any of Arduino IDE option to reflect this as in the warning section in [build_opt.h description in wiki]. This is important because if `-DCORE_DEBUG` is not configured correctly `core_debug()` silently becomes an empty function without triggering any build error. Don't forget to add `#include "core_debug.h"` in your code in order to use `core_debug()`.
+
+Also, you must enable the Virtual Serial (described in the above section) and include `SerialVirtIO.begin();` in your Arduino sketch, because this logging feature is tightly coupled to OpenAMP virtio.
+
+You can use `sh run_arduino_<sketch name>.sh log` command or `cat /sys/kernel/debug/remoteproc/remoteproc0/trace0` command to print out the debug log in the Linux host.
+
+Note that when overflow occurs the trace buffer is re-written from the beginning, removing existing logs. Consider increasing `VIRTIO_LOG_BUFFER_SIZE` in this case, as mentioned above.
+
+See [virtio_log.h] for more information.
+
+### Debugging Example
+
+Here is a basic blink example with `core_debug()`:
+```cpp
+#include "core_debug.h"
+
+unsigned long time = 0;
+unsigned long count = 1;
+
+void setup() {
+  // You must enable SerialVirtIO to use core_debug(), even if you don't use SerialVirtIO.
+  SerialVirtIO.begin();
+  pinMode(LED_BUILTIN, OUTPUT);
+}
+
+void loop() {
+  if ((millis() - time) > 1000) {
+    time = millis();
+    core_debug("%u seconds\n", count++);
+    digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN));
+  }
+}
+```
+
+Don't forget to add [build_opt.h] described above.
+
+After loading Arduino, you can simply `sh run_arduino_<sketch name>.sh log` to print the current `core_debug()` logs.
+
 ## Pin mapping
 
 The boards have two pin headers: Raspberry Pi HAT headers and Arduino shield headers. This project currently supports Arduino Shield headers only, leaving RPi HAT headers for the Linux applications.
@@ -108,7 +240,7 @@ There are additional pins for LEDs and buttons.
 | PA_13 | 17 / LED_RED                  | USER2_BTN            | Active Low, LED LD6, also connected to B4 button |
 | PH_7  | 18 / LED_ORANGE / LED_BUILTIN |                      | Active High, LED LD7                             |
 
-[`variant.h` of the board](https://github.com/stm32duino/Arduino_Core_STM32/tree/master/variants/STM32MP157_DK/variant.h) has the complete information about the pinouts.
+[`variant.h` of the board] has the complete information about the pinouts.
 
 ## Uploading
 
@@ -152,9 +284,8 @@ And then the Device Tree should enable TIM1 for the coprocessor, although this d
 ## Limitations
 
 * Ethernet and USB are not supported. Use them in the Linux host.
-* Currently there is no easy way for communication between the Linux host and Arduino coprocessor. There is ongoing work for virtual serial communications using OpenAMP rpmsg framework. Currently one possible way is to wire between UART7 (Arduino SCL/SDA pins) and USART3 (Linux RPi HAT GPIO14/GPIO15 pins), however, users should manually modify [Linux Device tree to enable `usart3` and recompile it](usart3).
 * I2C pins on Raspberry Pi HAT header (GPIO2 and GPIO3) are not available in Linux host. This is because the Discovery board shares I2C pins on Arduino header and those on the HAT header.
-* [Early firmware loading from U-Boot stage] is not supported. Only firmware loading on Linux boot stage by systemd supported. The binary itself may be loaded by U-Boot without any problems, but there is no out-of-box tool to configure U-Boot to load the firmware using Arduino IDE yet.
+* [Early firmware loading from U-Boot stage] is not supported. Only firmware loading on Linux boot stage by systemd (aka. `sh run_arduino_<sketch name>.sh install`) supported. The binary itself may be loaded by U-Boot without any problems, but there is no out-of-box tool to configure U-Boot to load the firmware using Arduino IDE yet.
 * EEPROM library: Those devices do not have non-volatile memory. The emulation is done using RETRAM. Therefore data will be preserved *only* when VBAT is supplied (e.g. A coin battery is connected to CN3 on STM32MP157A_DK1) and the coprocessor is waken up from sleep. This implies that cold boot the board may cause data loss, even if VBAT is supplied. See [discussions on RETRAM] for more detail.
 
 
@@ -170,11 +301,20 @@ And then the Device Tree should enable TIM1 for the coprocessor, although this d
 
 [run_arduino_gen.sh]: https://github.com/stm32duino/Arduino_Tools/blob/master/run_arduino_gen.sh
 
+[OpenAMP]: https://github.com/OpenAMP/open-amp/wiki/OpenAMP-Overview
+[Linux RPMsg]: https://wiki.st.com/stm32mpu/wiki/Linux_RPMsg_framework_overview
+[a hard restriction of the write size]: /cores/arduino/VirtIOSerial.cpp#L148
+
+[build_opt.h]: https://github.com/stm32duino/wiki/wiki/Customize-build-options-using-build_opt.h
+[build_opt.h description in wiki]: https://github.com/stm32duino/wiki/wiki/Customize-build-options-using-build_opt.h
+[virtio_log.h]: /cores/arduino/stm32/OpenAMP/virtio_log.h
+
+[`variant.h` of the board]: /variants/STM32MP157_DK/variant.h
+
 [The ST Wiki page on C-Kermit]: https://wiki.st.com/stm32mpu/wiki/How_to_transfer_a_file_over_serial_console
 [a bug in OpenSTLinux]: https://community.st.com/s/question/0D50X0000B9vHa4/cannot-get-download-a-file-using-kermit
 
 [stm32mp157c-dk2-m4-examples.dts]: https://github.com/STMicroelectronics/meta-st-stm32mp/blob/d8cbac759e1275b1a27d4ba38b64a0d83d0e8c9f/recipes-kernel/linux/linux-stm32mp/4.19/4.19.49/0029-ARM-stm32mp1-r2-DEVICETREE.patch#L4334
 
-[usart3]: https://github.com/STMicroelectronics/meta-st-stm32mp/blob/d8cbac759e1275b1a27d4ba38b64a0d83d0e8c9f/recipes-kernel/linux/linux-stm32mp/4.19/4.19.49/0029-ARM-stm32mp1-r2-DEVICETREE.patch#L4274
 [Early firmware loading from U-Boot stage]: https://wiki.st.com/stm32mpu/wiki/How_to_start_the_coprocessor_from_the_bootloader
 [discussions on RETRAM]: https://community.st.com/s/question/0D50X0000B44pHUSQY/doesnt-the-mcu-coprocessor-have-nonvolatile-memory
