shields: add generic shield to use CDC ACM UART as backend

Add  generic shields that provide devicetree and configuration
overlays, and configure USB device stack so that CDC ACM UART
can be used as backend for console, logging, or shell.
This approach allows us to avoid many identical overlays in
samples and tests directories, and cumbersome board configurations.

These shields use Kconfig option CONFIG_USB_DEVICE_INITIALIZE_AT_BOOT
and is mainly intended to be used with boards like
nrf52840dongle_nrf52840 or bl654_usb.

Signed-off-by: Johann Fischer <[email protected]>

Author: jfischer-no

boards/shields/cdc_acm/Kconfig.defconfig

@@ -0,0 +1,43 @@
+# Copyright (c) 2021 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+if SHIELD_CDC_ACM_CONSOLE || SHIELD_CDC_ACM_SHELL
+
+# TEST_LOGGING_DEFAULTS option sets all log levels to INF,
+# including the USB_CDC_ACM_LOG_LEVEL and that can not work.
+config TEST_LOGGING_DEFAULTS
+	default n
+
+config SERIAL
+	default y
+
+config UART_LINE_CTRL
+	default y
+
+config USB_DEVICE_STACK
+	default y
+
+config USB_DEVICE_INITIALIZE_AT_BOOT
+	default y
+
+endif #if SHIELD_CDC_ACM_CONSOLE || SHIELD_CDC_ACM_SHELL
+
+if SHIELD_CDC_ACM_CONSOLE
+
+config CONSOLE
+	default y
+
+config UART_CONSOLE
+	default y
+
+endif #if SHIELD_CDC_ACM_CONSOLE
+
+if SHIELD_CDC_ACM_SHELL
+
+config SHELL_BACKEND_SERIAL_CHECK_DTR
+	default y
+
+config LOG_PRINTK
+	default y
+
+endif #if SHIELD_CDC_ACM_SHELL

boards/shields/cdc_acm/Kconfig.shield

@@ -0,0 +1,8 @@
+# Copyright (c) 2021
+# SPDX-License-Identifier: Apache-2.0
+
+config SHIELD_CDC_ACM_CONSOLE
+	def_bool $(shields_list_contains,cdc_acm_console)
+
+config SHIELD_CDC_ACM_SHELL
+	def_bool $(shields_list_contains,cdc_acm_shell)

boards/shields/cdc_acm/cdc_acm_console.overlay

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) 2021 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	chosen {
+		zephyr,console = &console_cdc_acm_uart0;
+	};
+};
+
+&zephyr_udc0 {
+	console_cdc_acm_uart0: console_cdc_acm_uart0 {
+		compatible = "zephyr,cdc-acm-uart";
+		label = "CONSOLE_CDC_ACM_0";
+	};
+};

boards/shields/cdc_acm/cdc_acm_shell.overlay

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) 2021 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	chosen {
+		zephyr,shell-uart = &shell_cdc_acm_uart0;
+	};
+};
+
+&zephyr_udc0 {
+	shell_cdc_acm_uart0: shell_cdc_acm_uart0 {
+		compatible = "zephyr,cdc-acm-uart";
+		label = "SHELL_CDC_ACM_0";
+	};
+};

boards/shields/cdc_acm/doc/index.rst

@@ -0,0 +1,64 @@
+.. _cdc_acm_shield:
+
+Generic shields for CDC ACM UART
+################################
+
+Overview
+********
+
+This is a generic shield that provides devicetree and configuration overlays,
+and configures USB device stack so that CDC ACM UART can be used as backend
+for console, logging, and shell. It is mainly intended to be used with boards
+that do not have a debug adapter or native UART, but do have a USB device
+controller.
+This approach allows us to avoid many identical overlays in samples and tests
+directories (see :ref:`usb_device_cdc_acm` for more details).
+It also simplifies the configuration of the above mentioned boards,
+they can stay with the minimal configuration which minimizes the conflicts
+especially with different in-tree samples.
+
+These shields enable :kconfig:`CONFIG_USB_DEVICE_INITIALIZE_AT_BOOT` and
+configure USB device stack so that it is automatically initialized.
+This is important for the boards like :ref:`nrf52840dongle_nrf52840`,
+otherwise in-tree samples, that do not enable USB device support, are
+not usable. But it also means that in-tree samples, like :ref:`usb_cdc-acm`,
+that initialize USB device support themselves cannot be used with these shields.
+This is a good compromise which provides maximum coverage of usable samples for
+these specific USB dongles.
+
+Current supported chosen properties
+===================================
+
++-----------------------+---------------------+
+| Chosen property       | Shield Designation  |
+|                       |                     |
++=======================+=====================+
+| ``zephyr,console``    | ``cdc_acm_console`` |
++-----------------------+---------------------+
+| ``zephyr,shell-uart`` | ``cdc_acm_shell``   |
++-----------------------+---------------------+
+
+Requirements
+************
+
+This shield can only be used with a board which provides a USB device
+controller.
+
+Programming
+***********
+
+Set ``-DSHIELD=cdc_acm_shell`` when you invoke ``west build``. For example:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/subsys/shell/shell_module
+   :board: nrf52840dongle_nrf52840
+   :shield: cdc_acm_shell
+   :goals: build
+
+Or ``-DSHIELD=cdc_acm_console``, for example:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/basic/threads
+   :board: nrf52840dongle_nrf52840
+   :shield: cdc_acm_console
+   :goals: build

doc/reference/usb/uds_cdc_acm.rst

@@ -106,3 +106,7 @@ CDC ACM UART as backend for a subsystem or application:
 * ``zephyr,shell-uart`` used by shell for serial backend,
   for example see :zephyr_file:`samples/subsys/shell/shell_module`
 * ``zephyr,uart-mcumgr`` used by :ref:`smp_svr_sample`
+
+In-tree samples that do not require any USB device classes other than
+CDC ACM UART for console, logging, or shell should be built with
+:ref:`cdc_acm_shield`.