doc: Document the USB-C Source Subsystem

Documents the USB-C Source Subsystem API.

Signed-off-by: Sam Hurst <[email protected]>

doc/connectivity/usb_c/ucds.rst

@@ -14,7 +14,8 @@ It provides the following functionalities:
   The APIs is described in
   :zephyr_file:`include/zephyr/usb_c/usbc.h`
 
-Currently the device stack only support implementation of Sink devices.
+Currently the device stack supports implementation of Sink only and Source only
+devices. Dual Role Power (DRP) devices are not yet supported.
 
 :ref:`List<usbc-samples>` of samples for different purposes.
 
@@ -108,6 +109,96 @@ Start the USB-C subsystem:
    :end-before: usbc.rst usbc end
    :linenos:
 
+Implementing a Source Type-C and Power Delivery USB-C device
+************************************************************
+
+The configuration of a USB-C Device is done in the stack layer and devicetree.
+
+Define the following devicetree, structures and callbacks:
+
+* Devicetree ``usb-c-connector`` node referencing a TCPC
+* Devicetree ``vbus`` node referencing a VBUS measurment device
+* User defined structure that encapsulates application specific data
+* Policy callbacks
+
+For example, for the Sample USB-C Source application:
+
+Each Physical Type-C port is represented in the devicetree by a ``usb-c-connector``
+compatible node:
+
+.. literalinclude:: ../../../samples/subsys/usb_c/source/boards/stm32g081b_eval.overlay
+   :language: dts
+   :start-after: usbc.rst usbc-port start
+   :end-before: usbc.rst usbc-port end
+   :linenos:
+
+VBUS is measured by a device that's referenced in the devicetree by a
+``usb-c-vbus-adc`` compatible node:
+
+.. literalinclude:: ../../../samples/subsys/usb_c/source/boards/stm32g081b_eval.overlay
+   :language: dts
+   :start-after: usbc.rst vbus-voltage-divider-adc start
+   :end-before: usbc.rst vbus-voltage-divider-adc end
+   :linenos:
+
+
+A user defined structure is defined and later registered with the subsystem and can
+be accessed from callback through an API:
+
+.. literalinclude:: ../../../samples/subsys/usb_c/source/src/main.c
+   :language: c
+   :start-after: usbc.rst port data object start
+   :end-before: usbc.rst port data object end
+   :linenos:
+
+These callbacks are used by the subsystem to set or get application specific data:
+
+.. literalinclude:: ../../../samples/subsys/usb_c/source/src/main.c
+   :language: c
+   :start-after: usbc.rst callbacks start
+   :end-before: usbc.rst callbacks end
+   :linenos:
+
+This callback is used by the subsystem to query if a certain action can be taken:
+
+.. literalinclude:: ../../../samples/subsys/usb_c/source/src/main.c
+   :language: c
+   :start-after: usbc.rst check start
+   :end-before: usbc.rst check end
+   :linenos:
+
+This callback is used by the subsystem to notify the application of an event:
+
+.. literalinclude:: ../../../samples/subsys/usb_c/source/src/main.c
+   :language: c
+   :start-after: usbc.rst notify start
+   :end-before: usbc.rst notify end
+   :linenos:
+
+Registering the callbacks:
+
+.. literalinclude:: ../../../samples/subsys/usb_c/source/src/main.c
+   :language: c
+   :start-after: usbc.rst register start
+   :end-before: usbc.rst register end
+   :linenos:
+
+Register the user defined structure:
+
+.. literalinclude:: ../../../samples/subsys/usb_c/source/src/main.c
+   :language: c
+   :start-after: usbc.rst user data start
+   :end-before: usbc.rst user data end
+   :linenos:
+
+Start the USB-C subsystem:
+
+.. literalinclude:: ../../../samples/subsys/usb_c/source/src/main.c
+   :language: c
+   :start-after: usbc.rst usbc start
+   :end-before: usbc.rst usbc end
+   :linenos:
+
 API reference
 *************
 

samples/subsys/usb_c/source/boards/stm32g081b_eval.overlay

@@ -45,6 +45,7 @@
 		};
 	};
 
+	/* usbc.rst vbus-voltage-divider-adc start */
 	vbus1: vbus {
 		compatible = "zephyr,usb-c-vbus-adc";
 		io-channels = <&adc1 9>;
@@ -54,11 +55,13 @@
 		/* Pin B13 is used to control VBUS Discharge for Port1 */
 		discharge-gpios = <&gpiob 13 GPIO_ACTIVE_HIGH>;
 	};
+	/* usbc.rst vbus-voltage-divider-adc end */
 
 	ports {
 		#address-cells = <1>;
 		#size-cells = <0>;
 
+		/* usbc.rst usbc-port start */
 		port1: usbc-port@1 {
 			compatible = "usb-c-connector";
 			reg = <1>;
@@ -68,5 +71,6 @@
 			typec-power-opmode = "3.0A";
 			source-pdos = <PDO_FIXED(5000, 100, 0) PDO_FIXED(9000, 100, 0) PDO_FIXED(15000, 100, 0)>;
 		};
+		/* usbc.rst usbc-port end */
 	};
 };