1.. _usbc_api:
2
3USB-C device stack
4##################
5
6The USB-C device stack is a hardware independent interface between a
7Type-C Port Controller (TCPC) and customer applications. It is a port of
8the Google ChromeOS Type-C Port Manager (TCPM) stack.
9It provides the following functionalities:
10
11* Uses the APIs provided by the Type-C Port Controller drivers to interact with
12  the Type-C Port Controller.
13* Provides a programming interface that's used by a customer applications.
14  The APIs is described in
15  :zephyr_file:`include/zephyr/usb_c/usbc.h`
16
17Currently the device stack supports implementation of Sink only and Source only
18devices. Dual Role Power (DRP) devices are not yet supported.
19
20:zephyr:code-sample-category:`List<usbc>` of samples for different purposes.
21
22Implementing a Sink Type-C and Power Delivery USB-C device
23**********************************************************
24
25The configuration of a USB-C Device is done in the stack layer and devicetree.
26
27The following devicetree, structures and callbacks need to be defined:
28
29* Devicetree usb-c-connector node referencing a TCPC
30* Devicetree vbus node referencing a VBUS measurement device
31* User defined structure that encapsulates application specific data
32* Policy callbacks
33
34For example, for the Sample USB-C Sink application:
35
36Each Physical Type-C port is represented in the devicetree by a usb-c-connector
37compatible node:
38
39.. literalinclude:: ../../../../samples/subsys/usb_c/sink/boards/b_g474e_dpow1.overlay
40   :language: dts
41   :start-after: usbc.rst usbc-port start
42   :end-before: usbc.rst usbc-port end
43   :linenos:
44
45VBUS is measured by a device that's referenced in the devicetree by a
46usb-c-vbus-adc compatible node:
47
48.. literalinclude:: ../../../../samples/subsys/usb_c/sink/boards/b_g474e_dpow1.overlay
49   :language: dts
50   :start-after: usbc.rst vbus-voltage-divider-adc start
51   :end-before: usbc.rst vbus-voltage-divider-adc end
52   :linenos:
53
54
55A user defined structure is defined and later registered with the subsystem and can
56be accessed from callback through an API:
57
58.. literalinclude:: ../../../../samples/subsys/usb_c/sink/src/main.c
59   :language: c
60   :start-after: usbc.rst port data object start
61   :end-before: usbc.rst port data object end
62   :linenos:
63
64These callbacks are used by the subsystem to set or get application specific data:
65
66.. literalinclude:: ../../../../samples/subsys/usb_c/sink/src/main.c
67   :language: c
68   :start-after: usbc.rst callbacks start
69   :end-before: usbc.rst callbacks end
70   :linenos:
71
72This callback is used by the subsystem to query if a certain action can be taken:
73
74.. literalinclude:: ../../../../samples/subsys/usb_c/sink/src/main.c
75   :language: c
76   :start-after: usbc.rst check start
77   :end-before: usbc.rst check end
78   :linenos:
79
80This callback is used by the subsystem to notify the application of an event:
81
82.. literalinclude:: ../../../../samples/subsys/usb_c/sink/src/main.c
83   :language: c
84   :start-after: usbc.rst notify start
85   :end-before: usbc.rst notify end
86   :linenos:
87
88Registering the callbacks:
89
90.. literalinclude:: ../../../../samples/subsys/usb_c/sink/src/main.c
91   :language: c
92   :start-after: usbc.rst register start
93   :end-before: usbc.rst register end
94   :linenos:
95
96Register the user defined structure:
97
98.. literalinclude:: ../../../../samples/subsys/usb_c/sink/src/main.c
99   :language: c
100   :start-after: usbc.rst user data start
101   :end-before: usbc.rst user data end
102   :linenos:
103
104Start the USB-C subsystem:
105
106.. literalinclude:: ../../../../samples/subsys/usb_c/sink/src/main.c
107   :language: c
108   :start-after: usbc.rst usbc start
109   :end-before: usbc.rst usbc end
110   :linenos:
111
112Implementing a Source Type-C and Power Delivery USB-C device
113************************************************************
114
115The configuration of a USB-C Device is done in the stack layer and devicetree.
116
117Define the following devicetree, structures and callbacks:
118
119* Devicetree ``usb-c-connector`` node referencing a TCPC
120* Devicetree ``vbus`` node referencing a VBUS measurement device
121* User defined structure that encapsulates application specific data
122* Policy callbacks
123
124For example, for the Sample USB-C Source application:
125
126Each Physical Type-C port is represented in the devicetree by a ``usb-c-connector``
127compatible node:
128
129.. literalinclude:: ../../../../samples/subsys/usb_c/source/boards/stm32g081b_eval.overlay
130   :language: dts
131   :start-after: usbc.rst usbc-port start
132   :end-before: usbc.rst usbc-port end
133   :linenos:
134
135VBUS is measured by a device that's referenced in the devicetree by a
136``usb-c-vbus-adc`` compatible node:
137
138.. literalinclude:: ../../../../samples/subsys/usb_c/source/boards/stm32g081b_eval.overlay
139   :language: dts
140   :start-after: usbc.rst vbus-voltage-divider-adc start
141   :end-before: usbc.rst vbus-voltage-divider-adc end
142   :linenos:
143
144
145A user defined structure is defined and later registered with the subsystem and can
146be accessed from callback through an API:
147
148.. literalinclude:: ../../../../samples/subsys/usb_c/source/src/main.c
149   :language: c
150   :start-after: usbc.rst port data object start
151   :end-before: usbc.rst port data object end
152   :linenos:
153
154These callbacks are used by the subsystem to set or get application specific data:
155
156.. literalinclude:: ../../../../samples/subsys/usb_c/source/src/main.c
157   :language: c
158   :start-after: usbc.rst callbacks start
159   :end-before: usbc.rst callbacks end
160   :linenos:
161
162This callback is used by the subsystem to query if a certain action can be taken:
163
164.. literalinclude:: ../../../../samples/subsys/usb_c/source/src/main.c
165   :language: c
166   :start-after: usbc.rst check start
167   :end-before: usbc.rst check end
168   :linenos:
169
170This callback is used by the subsystem to notify the application of an event:
171
172.. literalinclude:: ../../../../samples/subsys/usb_c/source/src/main.c
173   :language: c
174   :start-after: usbc.rst notify start
175   :end-before: usbc.rst notify end
176   :linenos:
177
178Registering the callbacks:
179
180.. literalinclude:: ../../../../samples/subsys/usb_c/source/src/main.c
181   :language: c
182   :start-after: usbc.rst register start
183   :end-before: usbc.rst register end
184   :linenos:
185
186Register the user defined structure:
187
188.. literalinclude:: ../../../../samples/subsys/usb_c/source/src/main.c
189   :language: c
190   :start-after: usbc.rst user data start
191   :end-before: usbc.rst user data end
192   :linenos:
193
194Start the USB-C subsystem:
195
196.. literalinclude:: ../../../../samples/subsys/usb_c/source/src/main.c
197   :language: c
198   :start-after: usbc.rst usbc start
199   :end-before: usbc.rst usbc end
200   :linenos:
201
202API reference
203*************
204
205.. doxygengroup:: _usbc_device_api
206
207SINK callback reference
208***********************
209
210.. doxygengroup:: sink_callbacks
211
212SOURCE callback reference
213*************************
214
215.. doxygengroup:: source_callbacks
216