zephyrproject-rtos · jfischer-no · Nov 12, 2021 · Nov 12, 2021 · Nov 12, 2021 · Nov 12, 2021
diff --git a/boards/arm/degu_evk/Kconfig.defconfig b/boards/arm/degu_evk/Kconfig.defconfig
@@ -8,19 +8,6 @@ if BOARD_DEGU_EVK
 config BOARD
 	default "degu_evk"
 
-if USB_DEVICE_STACK
-
-config USB_DEVICE_PRODUCT
-	default "Degu Evaluation Kit"
-
-config UART_INTERRUPT_DRIVEN
-	default y
-
-config UART_LINE_CTRL
-	default y
-
-endif # USB_DEVICE_STACK
-
 if DISK_DRIVER_FLASH
 
 config DISK_FLASH_DEV_NAME

diff --git a/boards/arm/degu_evk/degu_evk.dts b/boards/arm/degu_evk/degu_evk.dts
@@ -15,8 +15,8 @@
 	chosen {
 		zephyr,sram = &sram0;
 		zephyr,flash = &flash0;
-		zephyr,console = &degu_cdc_acm_uart;
-		zephyr,shell-uart = &degu_cdc_acm_uart;
+		zephyr,console = &uart0;
+		zephyr,shell-uart = &uart0;
 		zephyr,code-partition = &slot0_partition;
 		zephyr,ieee802154 = &ieee802154;
 	};
@@ -161,8 +161,4 @@
 zephyr_udc0: &usbd {
 	compatible = "nordic,nrf-usbd";
 	status = "okay";
-
-	degu_cdc_acm_uart: degu_cdc_acm_uart {
-		compatible = "zephyr,cdc-acm-uart";
-	};
 };
diff --git a/boards/arm/degu_evk/degu_evk_defconfig b/boards/arm/degu_evk/degu_evk_defconfig
@@ -12,9 +12,6 @@ CONFIG_SERIAL=y
 CONFIG_CONSOLE=y
 CONFIG_UART_CONSOLE=y
 
-# enable USB (for CDC ACM console)
-CONFIG_USB_DEVICE_STACK=y
-
 # additional board options
 CONFIG_GPIO=y
 CONFIG_GPIO_AS_PINRESET=y

diff --git a/boards/arm/nrf52840dongle_nrf52840/Kconfig.defconfig b/boards/arm/nrf52840dongle_nrf52840/Kconfig.defconfig
@@ -24,14 +24,6 @@ config FLASH_LOAD_OFFSET
 	default 0x1000
 	depends on BOARD_HAS_NRF5_BOOTLOADER && !USE_DT_CODE_PARTITION
 
-if USB_DEVICE_STACK
-
-# Enable UART driver, needed for CDC ACM
-config SERIAL
-	default y
-
-endif # USB_DEVICE_STACK
-
 config BT_CTLR
 	default BT
 

diff --git a/boards/shields/cdc_acm/Kconfig.defconfig b/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 || SHIELD_CDC_ACM_BT_C2H
+
+# 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
diff --git a/boards/shields/cdc_acm/Kconfig.shield b/boards/shields/cdc_acm/Kconfig.shield
@@ -0,0 +1,11 @@
+# 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)
+
+config SHIELD_CDC_ACM_BT_C2H
+	def_bool $(shields_list_contains,cdc_acm_bt_c2h)
diff --git a/tests/bluetooth/shell/usb.overlay → ...ds/shields/cdc_acm/cdc_acm_bt_c2h.overlay b/tests/bluetooth/shell/usb.overlay → ...ds/shields/cdc_acm/cdc_acm_bt_c2h.overlay
@@ -6,12 +6,13 @@
 
 / {
 	chosen {
-		zephyr,shell-uart = &cdc_acm_uart0;
+		zephyr,bt-c2h-uart = &bt_c2h_cdc_acm_uart0;
 	};
 };
 
 &zephyr_udc0 {
-	cdc_acm_uart0: cdc_acm_uart0 {
+	bt_c2h_cdc_acm_uart0: bt_c2h_cdc_acm_uart0 {
 		compatible = "zephyr,cdc-acm-uart";
+		label = "BT_C2H_CDC_ACM_0";
 	};
 };
diff --git a/...les/subsys/shell/shell_module/usb.overlay → ...s/shields/cdc_acm/cdc_acm_console.overlay b/...les/subsys/shell/shell_module/usb.overlay → ...s/shields/cdc_acm/cdc_acm_console.overlay
@@ -6,12 +6,13 @@
 
 / {
 	chosen {
-		zephyr,shell-uart = &cdc_acm_uart0;
+		zephyr,console = &console_cdc_acm_uart0;
 	};
 };
 
 &zephyr_udc0 {
-	cdc_acm_uart0: cdc_acm_uart0 {
+	console_cdc_acm_uart0: console_cdc_acm_uart0 {
 		compatible = "zephyr,cdc-acm-uart";
+		label = "CONSOLE_CDC_ACM_0";
 	};
 };
diff --git a/samples/boards/sensortile_box/app.overlay → boards/shields/cdc_acm/cdc_acm_shell.overlay b/samples/boards/sensortile_box/app.overlay → boards/shields/cdc_acm/cdc_acm_shell.overlay
@@ -6,12 +6,13 @@
 
 / {
 	chosen {
-		zephyr,console = &cdc_acm_uart0;
+		zephyr,shell-uart = &shell_cdc_acm_uart0;
 	};
 };
 
 &zephyr_udc0 {
-	cdc_acm_uart0: cdc_acm_uart0 {
+	shell_cdc_acm_uart0: shell_cdc_acm_uart0 {
 		compatible = "zephyr,cdc-acm-uart";
+		label = "SHELL_CDC_ACM_0";
 	};
 };
diff --git a/boards/shields/cdc_acm/doc/index.rst b/boards/shields/cdc_acm/doc/index.rst
@@ -0,0 +1,75 @@
+.. _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``   |
++------------------------+---------------------+
+| ``zephyr,bt-c2h-uart`` | ``cdc_acm_bt_c2h``  |
++------------------------+---------------------+
+
+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
+
+With ``-DSHIELD=cdc_acm_bt_c2h``, :ref:`bluetooth-hci-uart-sample` can use
+CDC ACM UART as interface to the host:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/bluetooth/hci_uart
+   :board: nrf52840dongle_nrf52840
+   :shield: cdc_acm_bt_c2h
+   :goals: build
diff --git a/doc/services/usb/uds_cdc_acm.rst b/doc/services/usb/uds_cdc_acm.rst
@@ -103,3 +103,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`.
diff --git a/samples/boards/sensortile_box/README.rst b/samples/boards/sensortile_box/README.rst
@@ -37,6 +37,7 @@ Build and flash the sample in the following way:
 .. zephyr-app-commands::
     :zephyr-app: samples/boards/sensortile_box
     :board: sensortile_box
+    :shield: cdc_acm_console
     :goals: build flash
 
 Please note that flashing the board requires a few preliminary steps described

diff --git a/samples/boards/sensortile_box/prj.conf b/samples/boards/sensortile_box/prj.conf
@@ -16,12 +16,9 @@ CONFIG_STTS751_TRIGGER_NONE=y
 CONFIG_IIS3DHHC_TRIGGER_OWN_THREAD=y
 CONFIG_LIS2MDL_TRIGGER_NONE=y
 
-# config USB and USB console
+# config USB device support
 CONFIG_USB_DEVICE_VID=0x0483
 CONFIG_USB_DEVICE_PID=0x1234
-CONFIG_USB_DEVICE_STACK=y
 CONFIG_USB_DEVICE_PRODUCT="Zephyr CDC SensorTile.box"
 
-CONFIG_UART_INTERRUPT_DRIVEN=y
-CONFIG_UART_LINE_CTRL=y
 CONFIG_CBPRINTF_FP_SUPPORT=y
diff --git a/samples/boards/sensortile_box/sample.yaml b/samples/boards/sensortile_box/sample.yaml
@@ -7,3 +7,4 @@ tests:
     platform_allow: sensortile_box
     tags: sensors
     depends_on: i2c spi gpio
+    extra_args: SHIELD="cdc_acm_console"
diff --git a/samples/boards/sensortile_box/src/main.c b/samples/boards/sensortile_box/src/main.c
@@ -256,8 +256,7 @@ void main(void)
 	int cnt = 1;
 	uint32_t dtr = 0;
 
-	/* Application must enable USB by itself */
-	if (!device_is_ready(dev) || usb_enable(NULL)) {
+	if (!device_is_ready(dev)) {
 		return;
 	}
 

diff --git a/samples/subsys/shell/shell_module/overlay-usb.conf b/samples/subsys/shell/shell_module/overlay-usb.conf
diff --git a/samples/subsys/shell/shell_module/sample.yaml b/samples/subsys/shell/shell_module/sample.yaml
@@ -13,8 +13,7 @@ tests:
     tags: shell usb
     harness: keyboard
     min_ram: 40
-    extra_args: OVERLAY_CONFIG="overlay-usb.conf"
-                DTC_OVERLAY_FILE="usb.overlay"
+    extra_args: SHIELD="cdc_acm_shell"
     integration_platforms:
       - native_posix
   sample.shell.shell_module.minimal:

diff --git a/samples/subsys/shell/shell_module/src/main.c b/samples/subsys/shell/shell_module/src/main.c
@@ -425,19 +425,4 @@ void main(void)
 	if (IS_ENABLED(CONFIG_SHELL_START_OBSCURED)) {
 		login_init();
 	}
-
-#if DT_NODE_HAS_COMPAT(DT_CHOSEN(zephyr_shell_uart), zephyr_cdc_acm_uart)
-	const struct device *dev;
-	uint32_t dtr = 0;
-
-	dev = DEVICE_DT_GET(DT_CHOSEN(zephyr_shell_uart));
-	if (!device_is_ready(dev) || usb_enable(NULL)) {
-		return;
-	}
-
-	while (!dtr) {
-		uart_line_ctrl_get(dev, UART_LINE_CTRL_DTR, &dtr);
-		k_sleep(K_MSEC(100));
-	}
-#endif
 }
diff --git a/tests/bluetooth/shell/cdc_acm.conf b/tests/bluetooth/shell/cdc_acm.conf
diff --git a/tests/bluetooth/shell/src/main.c b/tests/bluetooth/shell/src/main.c
@@ -123,21 +123,6 @@ static void hrs_notify(void)
 
 void main(void)
 {
-#if DT_NODE_HAS_COMPAT(DT_CHOSEN(zephyr_shell_uart), zephyr_cdc_acm_uart)
-	const struct device *dev;
-	uint32_t dtr = 0;
-
-	dev = DEVICE_DT_GET(DT_CHOSEN(zephyr_shell_uart));
-	if (!device_is_ready(dev) || usb_enable(NULL)) {
-		return;
-	}
-
-	while (!dtr) {
-		uart_line_ctrl_get(dev, UART_LINE_CTRL_DTR, &dtr);
-		k_sleep(K_MSEC(100));
-	}
-#endif
-
 	printk("Type \"help\" for supported commands.");
 	printk("Before any Bluetooth commands you must `bt init` to initialize"
 	       " the stack.\n");

diff --git a/tests/bluetooth/shell/testcase.yaml b/tests/bluetooth/shell/testcase.yaml
@@ -8,8 +8,7 @@ tests:
     harness: keyboard
     min_flash: 145
   bluetooth.shell.cdc_acm:
-    extra_args: OVERLAY_CONFIG=cdc_acm.conf
-                DTC_OVERLAY_FILE="usb.overlay"
+    extra_args: SHIELD="cdc_acm_shell"
     depends_on: usb_device
     platform_allow: native_posix native_posix_64 nrf52840dk_nrf52840
     platform_exclude: nrf52dk_nrf52810

diff --git a/tests/drivers/uart/uart_basic_api/overlay-usb.conf b/tests/drivers/uart/uart_basic_api/overlay-usb.conf
diff --git a/tests/drivers/uart/uart_basic_api/src/main.c b/tests/drivers/uart/uart_basic_api/src/main.c
@@ -63,7 +63,7 @@ void test_main(void)
 	uint32_t dtr = 0;
 
 	dev = DEVICE_DT_GET(DT_CHOSEN(zephyr_console));
-	if (!device_is_ready(dev) || usb_enable(NULL)) {
+	if (!device_is_ready(dev)) {
 		return;
 	}
 

diff --git a/tests/drivers/uart/uart_basic_api/testcase.yaml b/tests/drivers/uart/uart_basic_api/testcase.yaml
@@ -21,8 +21,7 @@ tests:
     integration_platforms:
       - mps2_an385
   drivers.uart.basic_api.cdc_acm:
-    extra_args: OVERLAY_CONFIG="overlay-usb.conf"
-                DTC_OVERLAY_FILE="usb.overlay"
+    extra_args: SHIELD="cdc_acm_console"
     tags: drivers usb
     filter: CONFIG_UART_CONSOLE
     depends_on: usb_device