doc: usb: document USB message notifications

Add documentation about USB message notifications. Use literalinclude to
pull code snippets from the samples.

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

Author: jfischer-no

doc/connectivity/usb/device_next/usb_device.rst

@@ -193,3 +193,31 @@ enumerating the device. The application can disable the USB device using
    :dedent:
    :start-after: doc device enable start
    :end-before: doc device enable end
+
+USB Message notifications
+=========================
+
+The application can register a callback using :c:func:`usbd_msg_register_cb` to
+receive message notification from the USB device support subsystem. The
+messages are mostly about the common device state changes, and a few specific
+types from the USB CDC ACM implementation.
+
+.. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
+   :language: c
+   :dedent:
+   :start-after: doc device init-and-msg start
+   :end-before: doc device init-and-msg end
+
+The helper function :c:func:`usbd_msg_type_string()` can be used to convert
+:c:enumerator:`usbd_msg_type` to a human readable form for logging.
+
+If the controller supports VBUS state change detection, the battery-powered
+application may want to enable the USB device only when it is connected to a
+host. A generic application should use :c:func:`usbd_can_detect_vbus` to check
+for this capability.
+
+.. literalinclude:: ../../../../samples/subsys/usb/hid-keyboard/src/main.c
+   :language: c
+   :dedent:
+   :start-after: doc device msg-cb start
+   :end-before: doc device msg-cb end

samples/subsys/usb/common/sample_usbd_init.c

@@ -148,15 +148,15 @@ struct usbd_context *sample_usbd_init_device(usbd_msg_cb_t msg_cb)
 
 	sample_fix_code_triple(&sample_usbd, USBD_SPEED_FS);
 
-	/* doc message callback register start */
 	if (msg_cb != NULL) {
+		/* doc device init-and-msg start */
 		err = usbd_msg_register_cb(&sample_usbd, msg_cb);
 		if (err) {
 			LOG_ERR("Failed to register message callback");
 			return NULL;
 		}
+		/* doc device init-and-msg end */
 	}
-	/* doc message callback register end */
 
 	if (IS_ENABLED(CONFIG_SAMPLE_USBD_20_EXTENSION_DESC)) {
 		(void)usbd_device_set_bcd(&sample_usbd, USBD_SPEED_FS, 0x0201);

samples/subsys/usb/hid-keyboard/src/main.c

@@ -141,6 +141,28 @@ struct hid_device_ops kb_ops = {
 	.output_report = kb_output_report,
 };
 
+/* doc device msg-cb start */
+static void msg_cb(struct usbd_context *const usbd_ctx,
+		   const struct usbd_msg *const msg)
+{
+	LOG_INF("USBD message: %s", usbd_msg_type_string(msg->type));
+
+	if (usbd_can_detect_vbus(usbd_ctx)) {
+		if (msg->type == USBD_MSG_VBUS_READY) {
+			if (usbd_enable(usbd_ctx)) {
+				LOG_ERR("Failed to enable device support");
+			}
+		}
+
+		if (msg->type == USBD_MSG_VBUS_REMOVED) {
+			if (usbd_disable(usbd_ctx)) {
+				LOG_ERR("Failed to disable device support");
+			}
+		}
+	}
+}
+/* doc device msg-cb end */
+
 int main(void)
 {
 	struct usbd_context *sample_usbd;
@@ -178,19 +200,21 @@ int main(void)
 		return ret;
 	}
 
-	sample_usbd = sample_usbd_init_device(NULL);
+	sample_usbd = sample_usbd_init_device(msg_cb);
 	if (sample_usbd == NULL) {
 		LOG_ERR("Failed to initialize USB device");
 		return -ENODEV;
 	}
 
-	/* doc device enable start */
-	ret = usbd_enable(sample_usbd);
-	if (ret) {
-		LOG_ERR("Failed to enable device support");
-		return ret;
+	if (!usbd_can_detect_vbus(sample_usbd)) {
+		/* doc device enable start */
+		ret = usbd_enable(sample_usbd);
+		if (ret) {
+			LOG_ERR("Failed to enable device support");
+			return ret;
+		}
+		/* doc device enable end */
 	}
-	/* doc device enable end */
 
 	LOG_INF("HID keyboard sample is initialized");