Page MenuHomeFreeBSD
Differential D14235 Diff 39778 share/man/man4/fdt_pinctrl.4

Changeset View

Standalone View

View Options

share/man/man4/fdt_pinctrl.4

  • This file was added.
PropertyOld ValueNew Value
svn:eol-stylenullnative
\ No newline at end of property
svn:keywordsnullFreeBSD=%H
\ No newline at end of property
\ No newline at end of property
svn:mime-typenulltext/plain
\ No newline at end of property
.\" Copyright (c) 2018 Oleksandr Tymoshenko
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd February 16, 2018
.Dt "FDT_PINCTRL" 4
.Os
.Sh NAME
.Nm fdt_pinctrl
.Nd FDT I/O pin multiplexing support
.Sh SYNOPSIS
.Cd "device fdt_pinctrl"
.Sh DESCRIPTION
.Pp
Pin multiplexing is a technology used to re-purpose a single
physical connection (depending on chip packaging it may be
wblockUnsubmitted
Done
Inline Actions

s/single/a single/

wblock: s/single/a single/
pin, ball, or pad) to pull signal from one of SoC internal
controllers to peripheral devices.
wblockUnsubmitted
Done
Inline Actions

Serial comma and articles:

pin, ball, or pad) to connect a signal from one of the SoC internal
wblock: Serial comma and articles: ```pin, ball, or pad) to connect a signal from one of the SoC…
For example, based on the actual device design, a single SoC chip
pin can perform any of these roles: SPI clock, I2C
wblockUnsubmitted
Done
Inline Actions
For example, based on the actual device design, a single SoC chip
wblock: ```For example, based on the actual device design, a single SoC chip```
data, GPIO pin, or PWM signal.
wblockUnsubmitted
Done
Inline Actions
pin can perform any of these roles: SPI clock, I2C
wblock: ```pin can perform any of these roles: SPI clock, I2C```
Function selection is performed by the pinmux controller, a SoC
wblockUnsubmitted
Done
Inline Actions

Serial comma: s/ping/ping,/

wblock: Serial comma: s/ping/ping,/
hardware block, usually controlled a set of registers.
wblockUnsubmitted
Done
Inline Actions

Definitely need some articles here. Maybe:

Function selection is performed by the pinmux controller, a SoC
wblock: Definitely need some articles here. Maybe: ```Function selection is performed by the pinmux…
Pinmux controller capabilities and register format depend
wblockUnsubmitted
Done
Inline Actions

The last part of this is unclear. Is the pinmux controller just a set of registers, or is it controlled by a set of registers?

wblock: The last part of this is unclear. Is the pinmux controller just a set of registers, or is it…
gonzoAuthorUnsubmitted
Not Done
Inline Actions

Controlled. It's more than just a set of registers. I changed to "usually controlled by a ..."

gonzo: Controlled. It's more than just a set of registers. I changed to "usually controlled by a ..."
on the actual hardware implementation.
wblockUnsubmitted
Done
Inline Actions

Don't need the "s" on registers: s/registers/register/

wblock: Don't need the "s" on registers: s/registers/register/
.Pp
wblockUnsubmitted
Done
Inline Actions

Needs an article: s/on/on the/

wblock: Needs an article: s/on/on the/
On
.Xr fdt 4
based systems, the pinmux controller is represented by a node in
the device tree.
wblockUnsubmitted
Done
Inline Actions
based systems, the pinmux controller is represented by a node in
wblock: ```based systems, the pinmux controller is represented by a node in```
It may have any number of child nodes representing pin
wblockUnsubmitted
Done
Inline Actions
the device tree.
wblock: ```the device tree.```
configuration groups.
Properties of such nodes are hardware-specific and handled
by individual pinctrl drivers.
.Ss Example 1
Pinmux controller device tree node
.Bd -literal
pinctrl@7e220000 {
compatible = "vndr,soc1715-pinctrl";
reg = <0x7e220000 0x100>
spi0_pins: spi0 {
vndr,pins = <11 12>
vndr,functions = <ALT0 ALT5>
}
i2c0_pins: i2c0 {
...
}
}
.Ed
.Pp
Client devices are hardware devices that require certain pin
configurations to function properly.
Depending on the state the device is in (active, idle) it might
require different pin configurations.
wblockUnsubmitted
Done
Inline Actions

Articles, and use "might" for probability instead of "may" which implies permission:

Depending on the state the device is in (active, idle) it might
wblock: Articles, and use "might" for probability instead of "may" which implies permission…
Each configuration is described by setting the pinctrl-N
property to the list of phandles pointing to specific child
wblockUnsubmitted
Done
Inline Actions

Article:

Each configuration is described by setting the pinctrl-N
wblock: Article: ```Each configuration is described by setting the pinctrl-N```
nodes of the pinmux controller node.
N is an integer value starting with 0 and incremented by 1
wblockUnsubmitted
Done
Inline Actions

Article:

nodes of the pinmux controller node.
wblock: Article: ```nodes of the pinmux controller node.```
for every new set of pin configurations.
pinctrl-0 is a default configuration that is applied in the
.Xr fdt_pinctrl_configure_tree 9
wblockUnsubmitted
Done
Inline Actions

Article:

pinctrl-0 is a default configuration that is applied in the
wblock: Article: ```pinctrl-0 is a default configuration that is applied in the```
call.
In addition to referring to pin configurations by index, they
can be referred to by name if the pinctrl-names property is set.
wblockUnsubmitted
Done
Inline Actions

Needs a comma for a pause:

In addition to referring to pin configurations by index, they
wblock: Needs a comma for a pause: ```In addition to referring to pin configurations by index, they```
The value of pinctrl-names is a list of strings with names for
wblockUnsubmitted
Done
Inline Actions

Article and spelling correction:

can be referred to by name if the pinctrl-names property is set.
wblock: Article and spelling correction: ```can be referred to by name if the pinctrl-names property…
each pinctrl-N property.
wblockUnsubmitted
Done
Inline Actions

I suggest avoiding possessives whenever possible because they so frequently go wrong.

The value of pinctrl-names is a list of strings with names for each pinctrl-N
wblock: I suggest avoiding possessives whenever possible because they so frequently go wrong. ```The…
Client devices can request specific configuration using
.Xr fdt_pinctrl_configure 9
and
.Xr fdt_pinctrl_configure_by_name 9 .
.Ss Example 2
.Bd -literal
wblockUnsubmitted
Done
Inline Actions

Should this word "names" be here? Seems like the sentence should end after the second function (with added article):

Client devices can request a specific configuration using
.Xr fdt_pinctrl_configure 9 
​and
​.Xr fdt_pinctrl_configure_by_name 9 .

​

wblock: Should this word "names" be here? Seems like the sentence should end after the second function…
backlight@7f000000 {
compatible = "vndr,vndr-bl"
reg = <0x7f000000 0x20>
...
pinctrl-name = "active", "idle"
pinctrl-0 = <&backlight_active_pins>
pinctrl-1 = <&backlight_idle_pins>
}
.Ed
.Pp
The pinctrl driver should implement FDT_PINCTRL_CONFIGURE
method, register itself as pin configuration handler by
calling fdt_pinctrl_register function, and call
wblockUnsubmitted
Done
Inline Actions

Article:

The pinctrl driver should implement FDT_PINCTRL_CONFIGURE
wblock: Article: ```The pinctrl driver should implement FDT_PINCTRL_CONFIGURE```
.Xr fdt_pinctrl_configure_tree 9
to configure pins for all enabled devices (device where
wblockUnsubmitted
Done
Inline Actions

Serial comma:

calling fdt_pinctrl_register function, and call
wblock: Serial comma: ```calling fdt_pinctrl_register function, and call```
the "status" property is not set to "disabled").
.Sh SEE ALSO
wblockUnsubmitted
Done
Inline Actions

Avoid contractions:

to configure pins for all enabled devices (devices where
wblock: Avoid contractions: ```to configure pins for all enabled devices (devices where```
.Xr fdt_pinctrl 9
wblockUnsubmitted
Done
Inline Actions
the "status" property is not set to "disabled").
wblock: ```the "status" property is not set to "disabled").```
.Sh HISTORY
The
.Nm
driver first appeared in
.Fx 10.2 .
.Sh AUTHORS
.An -nosplit
The
.Nm
device driver was developed by
.An \&Ian Lepore Aq Mt ian@FreeBSD.org .
This manual page was written by
.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .