Add documentation for fdt_pinctrl driver

[gonzo]

Summary

• Add techical overview of the driver to section 4
• Add API description to section 9

[wblock]

share/man/man4/fdt_pinctrl.4

38

s/single/a single/

40

Serial comma and articles:

pin, ball, or pad) to connect a signal from one of the SoC internal

42

For example, based on the actual device design, a single SoC chip

43

pin can perform any of these roles: SPI clock, I2C

44

Serial comma: s/ping/ping,/

45

Definitely need some articles here. Maybe:

Function selection is performed by the pinmux controller, a SoC

46

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?

47

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

48

Needs an article: s/on/on the/

52

based systems, the pinmux controller is represented by a node in

53

the device tree.

78

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

Depending on the state the device is in (active, idle) it might

80

Article:

Each configuration is described by setting the pinctrl-N

82

Article:

nodes of the pinmux controller node.

85

Article:

pinctrl-0 is a default configuration that is applied in the

88

Needs a comma for a pause:

In addition to referring to pin configurations by index, they

89

Article and spelling correction:

can be referred to by name if the pinctrl-names property is set.

90

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

96

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 .

​

109

Article:

The pinctrl driver should implement FDT_PINCTRL_CONFIGURE

111

Serial comma:

calling fdt_pinctrl_register function, and call

113

Avoid contractions:

to configure pins for all enabled devices (devices where

114

the "status" property is not set to "disabled").

share/man/man9/fdt_pinctrl.9

50

No "s" on pins ("pin configurations" is the plural), articles:

provides an API for manipulating I/O pin configurations on

52

This is complex. Maybe:

On the controller side, the standard newbus probe and
attach methods are implemented.
This driver also implements the

55

method, in which it calls the

57

Break the sentence here:

function to register itself as a pinmux controller.

and add another line afterwards:

Then

59

is used to walk the device tree and configure pins specified by the pinctrl-0

61

If a client device requires a pin configuration change at some

62

point of its lifecycle, it uses the

68

I suggest these "The function" parts can be removed. In other words, change:

The function fdt_pinctrl_configure is used

to just

fdt_pinctrl_configure is used

This might make some people Very Concerned that the sentence does not start with a capital letter, but it does start with a proper name, the name of the function. And not all names start with capital letters.

An alternate approach is to move the word "function" after the function name:

The fdt_pinctrl_configure function is used

but I still think that is redundant and adds very little or nothing to the content.

72

to request a pin configuration

73

Probably don't need to quote this, earlier ones were not quoted. Also remove a possessive.

described by the pinctrl-N property with index

76

See above, note at line 67.

80

Article:

to request the pin configuration with name

83

As above.

92

Spelling:

identifies each descendant of the pinctrl

93

Break the sentence:

node.
The pinctrl node is a pin configuration

102

As above.

107

This is really hard to understand and needs to be broken into two or three sentences. Maybe:

.Fn fdt_pinctrl_configure_tree
walks through enabled devices in the device tree.
If the pinctrl-0 property contains references
to child nodes of the specified pinctrl device,
their pins are configured.

[gonzo]

Fixed. Thanks for edits Warren.

share/man/man4/fdt_pinctrl.4

46

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

[gonzo]

Implement wblock@ edits

[gonzo]

Hi Warren,

Is current version OK to be committed?

Thanks

[gonzo]

Add information that fdt_pinctrl_register can be called
mutiple type to handle more than one pins property type

[wblock]

In D14235#304554, @gonzo wrote:

Hi Warren,

Is current version OK to be committed?

Thanks

The man page looks good to me. Please remember to bump .Dd before commit. Thanks!