Lines Matching +full:soc +full:- +full:dependent
1 .. _pinctrl-guide:
6 This is a high-level guide to pin control. See :ref:`pinctrl_api` for API
13 parameters such as pin direction, pull-up/down resistors, etc. are named **pin
14 controllers**. The pin controller's main users are SoC hardware peripherals,
18 of a peripheral, for example, the slew-rate depending on the operating
19 frequency. The available configuration options are vendor/SoC dependent and can
20 range from simple pull-up/down options to more advanced settings such as
21 debouncing, low-power modes, etc.
23 The way pin control is implemented in hardware is vendor/SoC specific. It is
29 pull-up/down are controlled in the same block via ``CONFIG`` bits. This model is
30 used by several SoC families, such as many from NXP and STM32.
32 .. figure:: images/hw-cent-control.svg
34 Example of pin control centralized into a single per-pin block
41 .. figure:: images/hw-dist-control.svg
43 Example pin control distributed between peripheral registers and per-pin block
49 more effort, since the driver needs to gather knowledge of peripheral dependent
56 drivers. For example, pull-up/down resistors can usually be enabled by both the
60 Therefore, the main users of the pin control driver are SoC peripherals. In
70 depending on the operating conditions, for example, to enable a low-power mode
82 +----+------------------+----+------------------+
86 +----+------------------+----+------------------+
87 | TX | - Pin: PA0 | TX | - Pin: PA0 |
88 | | - Pull: NONE | | - Pull: NONE |
89 | | - Low Power: NO | | - Low Power: YES |
90 +----+------------------+----+------------------+
91 | RX | - Pin: PA1 | RX | - Pin: PA1 |
92 | | - Pull: UP | | - Pull: NONE |
93 | | - Low Power: NO | | - Low Power: YES |
94 +----+------------------+----+------------------+
109 +-------------+----------------------------------+-------------------------+
111 +-------------+----------------------------------+-------------------------+
115 +-------------+----------------------------------+-------------------------+
119 +-------------+----------------------------------+-------------------------+
159 .. code-block:: c
180 de-initialization yet, this functionality should only be used during early
203 ``pinctrl-N`` properties, being ``N`` the state index starting from zero. The
204 ``pinctrl-names`` property is then used to assign a unique identifier for each
205 state property by index, for example, ``pinctrl-names`` list entry 0 is the name
206 for ``pinctrl-0``.
208 .. code-block:: devicetree
213 pinctrl-0 = <...>;
216 pinctrl-N = <...>;
218 pinctrl-names = "default", ..., "mystate";
228 pull-up is enabled. The representation choice largely depends on each
229 vendor/SoC, so the Devicetree binding files for the pin control drivers are the
238 .. code-block:: devicetree
241 #include "board-pinctrl.dtsi"
244 pinctrl-0 = <&periph0_default>;
245 pinctrl-names = "default";
248 .. code-block:: c
250 /* vnd-soc-pkgxx.h
260 .. code-block:: devicetree
262 /* board-pinctrl.dtsi */
263 #include <vnd-soc-pkgxx.h>
269 /* Mappings: PERIPH0_SIGA -> PX0, PERIPH0_SIGC -> PZ1 */
271 /* Pins PX0 and PZ1 have pull-up enabled */
272 bias-pull-up;
276 /* Mappings: PERIPH0_SIGB -> PY7 */
285 nodes can not be re-used for multiple states. This method is discouraged if
292 to prefix pre-generated nodes with ``/omit-if-no-ref/``. This prefix makes
295 .. code-block:: devicetree
298 #include "board-pinctrl.dtsi"
301 pinctrl-0 = <&periph0_siga_px0_default &periph0_sigb_py7_default
303 pinctrl-names = "default";
306 .. code-block:: devicetree
308 /* vnd-soc-pkgxx.dtsi
314 /* Mapping for PERIPH0_SIGA -> PX0, to be used for default state */
315 /omit-if-no-ref/ periph0_siga_px0_default: periph0_siga_px0_default {
319 /* Mapping for PERIPH0_SIGB -> PY7, to be used for default state */
320 /omit-if-no-ref/ periph0_sigb_py7_default: periph0_sigb_py7_default {
324 /* Mapping for PERIPH0_SIGC -> PZ1, to be used for default state */
325 /omit-if-no-ref/ periph0_sigc_pz1_default: periph0_sigc_pz1_default {
330 .. code-block:: devicetree
332 /* board-pinctrl.dts */
333 #include <vnd-soc-pkgxx.dtsi>
335 /* Enable pull-up for PX0 (default state) */
337 bias-pull-up;
340 /* Enable pull-up for PZ1 (default state) */
342 bias-pull-up;
347 It is discouraged to add pin configuration defaults in pre-defined nodes.
350 For example, enabling a pull-up by default may not always be desired because
355 .. code-block:: devicetree
357 /* not evident that "periph0_siga_px0_default" also implies "bias-pull-up" */
358 /omit-if-no-ref/ periph0_siga_px0_default: periph0_siga_px0_default {
360 bias-pull-up;
376 The pin configuration is stored in an opaque type that is vendor/SoC dependent:
381 arguments: a node identifier and a property name (``pinctrl-N``). With this
383 contained within the ``pinctrl-N`` property of the given node.
389 - Use ``pinctrl-N`` (N=0, 1, ...) and ``pinctrl-names`` properties to define pin
391 :file:`dts/bindings/pinctrl/pinctrl-device.yaml`.
392 - Use standard pin configuration properties as defined in
393 :file:`dts/bindings/pinctrl/pincfg-node.yaml`.
405 the ``pinctrl-device.yaml`` is included. For example:
407 .. code-block:: yaml
409 include: [base.yaml, pinctrl-device.yaml]
411 This file is needed to add ``pinctrl-N`` and ``pinctrl-names`` properties to the
442 .. code-block:: c
462 const struct mydev_config *config = dev->config;
466 ret = pinctrl_apply_state(config->pcfg, PINCTRL_STATE_DEFAULT);
506 - `Introduction to pin muxing and GPIO control under Linux <https://elinux.org/images/a/a7/ELC-2021…