Documentation/driver-api/pin-control.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/pin-control.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/pin-control.rst
Extension
.rst
Size
54859 bytes
Lines
1511
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct foo_state {
	struct pinctrl *p;
	struct pinctrl_state *s;
	...
	};

	foo_probe()
	{
		/* Allocate a state holder named "foo" etc */
		struct foo_state *foo = ...;
		int ret;

		foo->p = devm_pinctrl_get(&device);
		if (IS_ERR(foo->p)) {
			ret = PTR_ERR(foo->p);
			foo->p = NULL;
			return ret;
		}

		foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
		if (IS_ERR(foo->s)) {
			devm_pinctrl_put(foo->p);
			return PTR_ERR(foo->s);
		}

		ret = pinctrl_select_state(foo->p, foo->s);
		if (ret < 0) {
			devm_pinctrl_put(foo->p);
			return ret;
		}
	}

This get/lookup/select/put sequence can just as well be handled by bus drivers
if you don't want each and every driver to handle it and you know the
arrangement on your bus.

The semantics of the pinctrl APIs are:

- ``pinctrl_get()`` is called in process context to obtain a handle to all pinctrl
  information for a given client device. It will allocate a struct from the
  kernel memory to hold the pinmux state. All mapping table parsing or similar
  slow operations take place within this API.

- ``devm_pinctrl_get()`` is a variant of pinctrl_get() that causes ``pinctrl_put()``
  to be called automatically on the retrieved pointer when the associated
  device is removed. It is recommended to use this function over plain
  ``pinctrl_get()``.

- ``pinctrl_lookup_state()`` is called in process context to obtain a handle to a
  specific state for a client device. This operation may be slow, too.

- ``pinctrl_select_state()`` programs pin controller hardware according to the
  definition of the state as given by the mapping table. In theory, this is a
  fast-path operation, since it only involved blasting some register settings
  into hardware. However, note that some pin controllers may have their
  registers on a slow/IRQ-based bus, so client devices should not assume they
  can call ``pinctrl_select_state()`` from non-blocking contexts.

- ``pinctrl_put()`` frees all information associated with a pinctrl handle.

- ``devm_pinctrl_put()`` is a variant of ``pinctrl_put()`` that may be used to
  explicitly destroy a pinctrl object returned by ``devm_pinctrl_get()``.
  However, use of this function will be rare, due to the automatic cleanup
  that will occur even without calling it.

  ``pinctrl_get()`` must be paired with a plain ``pinctrl_put()``.
  ``pinctrl_get()`` may not be paired with ``devm_pinctrl_put()``.
  ``devm_pinctrl_get()`` can optionally be paired with ``devm_pinctrl_put()``.
  ``devm_pinctrl_get()`` may not be paired with plain ``pinctrl_put()``.

Annotation

Implementation Notes