pinctrl: Fix some typos and grammar issues in the documentation

I had been trying to learn a bit more about the pinctrl subsystem, and I realized several typos and grammar issues while going through the documentation. I have probably not caught all the possible issues, but this change is addressing several places for improvement. Signed-off-by: Laszlo Papp <lpapp@kde.org> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

pinctrl: Fix some typos and grammar issues in the documentation
I had been trying to learn a bit more about the pinctrl subsystem, and I realized several typos and grammar issues while going through the documentation. I have probably not caught all the possible issues, but this change is addressing several places for improvement. Signed-off-by: Laszlo Papp <lpapp@kde.org> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
Laszlo Papp · Linus Walleij
1 parent 655dada627
Showing 1 changed file with 21 additions and 22 deletions Side-by-side Diff
Documentation/pinctrl.txt
@@ -18,7 +18,7 @@
  
 - A pin controller is a piece of hardware, usually a set of registers, that
   can control PINs. It may be able to multiplex, bias, set load capacitance,
-  set drive strength etc for individual pins or groups of pins.
+  set drive strength, etc. for individual pins or groups of pins.
  
 Definition of PIN:
  
@@ -90,7 +90,7 @@
 since these are so tightly integrated with the machines they are used on.
 See for example arch/arm/mach-u300/Kconfig for an example.
  
-Pins usually have fancier names than this. You can find these in the dataheet
+Pins usually have fancier names than this. You can find these in the datasheet
 for your chip. Notice that the core pinctrl.h file provides a fancy macro
 called PINCTRL_PIN() to create the struct entries. As you can see I enumerated
 the pins from 0 in the upper left corner to 63 in the lower right corner.
@@ -185,7 +185,7 @@
 };
  
 The pin control subsystem will call the .get_groups_count() function to
-determine total number of legal selectors, then it will call the other functions
+determine the total number of legal selectors, then it will call the other functions
 to retrieve the name and pins of the group. Maintaining the data structure of
 the groups is up to the driver, this is just a simple example - in practice you
 may need more entries in your group structure, for example specific register
@@ -195,7 +195,7 @@
 Pin configuration
 =================
  
-Pins can sometimes be software-configured in an various ways, mostly related
+Pins can sometimes be software-configured in various ways, mostly related
 to their electronic properties when used as inputs or outputs. For example you
 may be able to make an output pin high impedance, or "tristate" meaning it is
 effectively disconnected. You may be able to connect an input pin to VDD or GND
@@ -291,7 +291,7 @@
 controller we need a mapping so that the pin control subsystem can figure out
 which pin controller handles control of a certain GPIO pin. Since a single
 pin controller may be muxing several GPIO ranges (typically SoCs that have
-one set of pins but internally several GPIO silicon blocks, each modelled as
+one set of pins, but internally several GPIO silicon blocks, each modelled as
 a struct gpio_chip) any number of GPIO ranges can be added to a pin controller
 instance like this:
  
  
@@ -373,9 +373,9 @@
  
 For all functionalities dealing with pin biasing, pin muxing etc, the pin
 controller subsystem will look up the corresponding pin number from the passed
-in gpio number, and use the range's internals to retrive a pin number. After
+in gpio number, and use the range's internals to retrieve a pin number. After
 that, the subsystem passes it on to the pin control driver, so the driver
-will get an pin number into its handled number range. Further it is also passed
+will get a pin number into its handled number range. Further it is also passed
 the range ID value, so that the pin controller knows which range it should
 deal with.
  
@@ -430,8 +430,8 @@
 to the chip, and quite a few will be taken by large ports like an external
 memory interface. The remaining pins will often be subject to pin multiplexing.
  
-The example 8x8 PGA package above will have pin numbers 0 thru 63 assigned to
-its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
+The example 8x8 PGA package above will have pin numbers 0 through 63 assigned
+to its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
 pinctrl_register_pins() and a suitable data set as shown earlier.
  
 In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port
@@ -442,7 +442,7 @@
 of the package the silicon performing the SPI logic can alternatively be routed
 out on pins { G4, G3, G2, G1 }.
  
-On the botton row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something
+On the bottom row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something
 special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
 consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or
 { A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI
@@ -549,7 +549,7 @@
  
 We assume that the number of possible function maps to pin groups is limited by
 the hardware. I.e. we assume that there is no system where any function can be
-mapped to any pin, like in a phone exchange. So the available pins groups for
+mapped to any pin, like in a phone exchange. So the available pin groups for
 a certain function will be limited to a few choices (say up to eight or so),
 not hundreds or any amount of choices. This is the characteristic we have found
 by inspecting available pinmux hardware, and a necessary assumption since we
@@ -564,7 +564,7 @@
 the pin controller driver to execute different settings.
  
 It is the responsibility of the pinmux driver to impose further restrictions
-(say for example infer electronic limitations due to load etc) to determine
+(say for example infer electronic limitations due to load, etc.) to determine
 whether or not the requested function can actually be allowed, and in case it
 is possible to perform the requested mux setting, poke the hardware so that
 this happens.
@@ -755,7 +755,7 @@
 Note that the following implies that the use case is to use a certain pin
 from the Linux kernel using the API in <linux/gpio.h> with gpio_request()
 and similar functions. There are cases where you may be using something
-that your datasheet calls "GPIO mode" but actually is just an electrical
+that your datasheet calls "GPIO mode", but actually is just an electrical
 configuration for a certain device. See the section below named
 "GPIO mode pitfalls" for more details on this scenario.
  
@@ -871,7 +871,7 @@
  
 - Registers (or fields within registers) that control muxing of signals
   from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should
-  be exposed through the pinctrl subssytem, as mux functions.
+  be exposed through the pinctrl subsystem, as mux functions.
  
 - Registers (or fields within registers) that control GPIO functionality
   such as setting a GPIO's output value, reading a GPIO's input value, or
@@ -895,7 +895,7 @@
 system sleep, we need to put this pin into "GPIO mode" and ground it.
  
 If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start
-to think that you need to come up with something real complex, that the
+to think that you need to come up with something really complex, that the
 pin shall be used for UART TX and GPIO at the same time, that you will grab
 a pin control handle and set it to a certain state to enable UART TX to be
 muxed in, then twist it over to GPIO mode and use gpio_direction_output()
  
@@ -964,12 +964,12 @@
 This will give the desired effect without any bogus interaction with the
 GPIO subsystem. It is just an electrical configuration used by that device
 when going to sleep, it might imply that the pin is set into something the
-datasheet calls "GPIO mode" but that is not the point: it is still used
+datasheet calls "GPIO mode", but that is not the point: it is still used
 by that UART device to control the pins that pertain to that very UART
 driver, putting them into modes needed by the UART. GPIO in the Linux
 kernel sense are just some 1-bit line, and is a different use case.
  
-How the registers are poked to attain the push/pull and output low
+How the registers are poked to attain the push or pull, and output low
 configuration and the muxing of the "u0" or "gpio-mode" group onto these
 pins is a question for the driver.
  
@@ -977,7 +977,7 @@
 "low power mode" rather than anything to do with GPIO. This often means
 the same thing electrically speaking, but in this latter case the
 software engineers will usually quickly identify that this is some
-specific muxing/configuration rather than anything related to the GPIO
+specific muxing or configuration rather than anything related to the GPIO
 API.
  
  
@@ -1024,8 +1024,7 @@
 must match a function provided by the pinmux driver handling this pin range.
  
 As you can see we may have several pin controllers on the system and thus
-we need to specify which one of them that contain the functions we wish
-to map.
+we need to specify which one of them contains the functions we wish to map.
  
 You register this pinmux mapping to the pinmux subsystem by simply:
  
  
@@ -1254,10 +1253,10 @@
   pinctrl_get().
  
 - pinctrl_lookup_state() is called in process context to obtain a handle to a
-  specific state for a the client device. This operation may be slow too.
+  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
+  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
...	...	@@ -18,7 +18,7 @@
18	18
19	19	- A pin controller is a piece of hardware, usually a set of registers, that
20	20	can control PINs. It may be able to multiplex, bias, set load capacitance,
21		- set drive strength etc for individual pins or groups of pins.
	21	+ set drive strength, etc. for individual pins or groups of pins.
22	22
23	23	Definition of PIN:
24	24
...	...	@@ -90,7 +90,7 @@
90	90	since these are so tightly integrated with the machines they are used on.
91	91	See for example arch/arm/mach-u300/Kconfig for an example.
92	92
93		-Pins usually have fancier names than this. You can find these in the dataheet
	93	+Pins usually have fancier names than this. You can find these in the datasheet
94	94	for your chip. Notice that the core pinctrl.h file provides a fancy macro
95	95	called PINCTRL_PIN() to create the struct entries. As you can see I enumerated
96	96	the pins from 0 in the upper left corner to 63 in the lower right corner.
...	...	@@ -185,7 +185,7 @@
185	185	};
186	186
187	187	The pin control subsystem will call the .get_groups_count() function to
188		-determine total number of legal selectors, then it will call the other functions
	188	+determine the total number of legal selectors, then it will call the other functions
189	189	to retrieve the name and pins of the group. Maintaining the data structure of
190	190	the groups is up to the driver, this is just a simple example - in practice you
191	191	may need more entries in your group structure, for example specific register
...	...	@@ -195,7 +195,7 @@
195	195	Pin configuration
196	196	=================
197	197
198		-Pins can sometimes be software-configured in an various ways, mostly related
	198	+Pins can sometimes be software-configured in various ways, mostly related
199	199	to their electronic properties when used as inputs or outputs. For example you
200	200	may be able to make an output pin high impedance, or "tristate" meaning it is
201	201	effectively disconnected. You may be able to connect an input pin to VDD or GND
...	...	@@ -291,7 +291,7 @@
291	291	controller we need a mapping so that the pin control subsystem can figure out
292	292	which pin controller handles control of a certain GPIO pin. Since a single
293	293	pin controller may be muxing several GPIO ranges (typically SoCs that have
294		-one set of pins but internally several GPIO silicon blocks, each modelled as
	294	+one set of pins, but internally several GPIO silicon blocks, each modelled as
295	295	a struct gpio_chip) any number of GPIO ranges can be added to a pin controller
296	296	instance like this:
297	297
298	298
...	...	@@ -373,9 +373,9 @@
373	373
374	374	For all functionalities dealing with pin biasing, pin muxing etc, the pin
375	375	controller subsystem will look up the corresponding pin number from the passed
376		-in gpio number, and use the range's internals to retrive a pin number. After
	376	+in gpio number, and use the range's internals to retrieve a pin number. After
377	377	that, the subsystem passes it on to the pin control driver, so the driver
378		-will get an pin number into its handled number range. Further it is also passed
	378	+will get a pin number into its handled number range. Further it is also passed
379	379	the range ID value, so that the pin controller knows which range it should
380	380	deal with.
381	381
...	...	@@ -430,8 +430,8 @@
430	430	to the chip, and quite a few will be taken by large ports like an external
431	431	memory interface. The remaining pins will often be subject to pin multiplexing.
432	432
433		-The example 8x8 PGA package above will have pin numbers 0 thru 63 assigned to
434		-its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
	433	+The example 8x8 PGA package above will have pin numbers 0 through 63 assigned
	434	+to its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
435	435	pinctrl_register_pins() and a suitable data set as shown earlier.
436	436
437	437	In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port
...	...	@@ -442,7 +442,7 @@
442	442	of the package the silicon performing the SPI logic can alternatively be routed
443	443	out on pins { G4, G3, G2, G1 }.
444	444
445		-On the botton row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something
	445	+On the bottom row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something
446	446	special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
447	447	consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or
448	448	{ A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI
...	...	@@ -549,7 +549,7 @@
549	549
550	550	We assume that the number of possible function maps to pin groups is limited by
551	551	the hardware. I.e. we assume that there is no system where any function can be
552		-mapped to any pin, like in a phone exchange. So the available pins groups for
	552	+mapped to any pin, like in a phone exchange. So the available pin groups for
553	553	a certain function will be limited to a few choices (say up to eight or so),
554	554	not hundreds or any amount of choices. This is the characteristic we have found
555	555	by inspecting available pinmux hardware, and a necessary assumption since we
...	...	@@ -564,7 +564,7 @@
564	564	the pin controller driver to execute different settings.
565	565
566	566	It is the responsibility of the pinmux driver to impose further restrictions
567		-(say for example infer electronic limitations due to load etc) to determine
	567	+(say for example infer electronic limitations due to load, etc.) to determine
568	568	whether or not the requested function can actually be allowed, and in case it
569	569	is possible to perform the requested mux setting, poke the hardware so that
570	570	this happens.
...	...	@@ -755,7 +755,7 @@
755	755	Note that the following implies that the use case is to use a certain pin
756	756	from the Linux kernel using the API in <linux/gpio.h> with gpio_request()
757	757	and similar functions. There are cases where you may be using something
758		-that your datasheet calls "GPIO mode" but actually is just an electrical
	758	+that your datasheet calls "GPIO mode", but actually is just an electrical
759	759	configuration for a certain device. See the section below named
760	760	"GPIO mode pitfalls" for more details on this scenario.
761	761
...	...	@@ -871,7 +871,7 @@
871	871
872	872	- Registers (or fields within registers) that control muxing of signals
873	873	from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should
874		- be exposed through the pinctrl subssytem, as mux functions.
	874	+ be exposed through the pinctrl subsystem, as mux functions.
875	875
876	876	- Registers (or fields within registers) that control GPIO functionality
877	877	such as setting a GPIO's output value, reading a GPIO's input value, or
...	...	@@ -895,7 +895,7 @@
895	895	system sleep, we need to put this pin into "GPIO mode" and ground it.
896	896
897	897	If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start
898		-to think that you need to come up with something real complex, that the
	898	+to think that you need to come up with something really complex, that the
899	899	pin shall be used for UART TX and GPIO at the same time, that you will grab
900	900	a pin control handle and set it to a certain state to enable UART TX to be
901	901	muxed in, then twist it over to GPIO mode and use gpio_direction_output()
902	902
...	...	@@ -964,12 +964,12 @@
964	964	This will give the desired effect without any bogus interaction with the
965	965	GPIO subsystem. It is just an electrical configuration used by that device
966	966	when going to sleep, it might imply that the pin is set into something the
967		-datasheet calls "GPIO mode" but that is not the point: it is still used
	967	+datasheet calls "GPIO mode", but that is not the point: it is still used
968	968	by that UART device to control the pins that pertain to that very UART
969	969	driver, putting them into modes needed by the UART. GPIO in the Linux
970	970	kernel sense are just some 1-bit line, and is a different use case.
971	971
972		-How the registers are poked to attain the push/pull and output low
	972	+How the registers are poked to attain the push or pull, and output low
973	973	configuration and the muxing of the "u0" or "gpio-mode" group onto these
974	974	pins is a question for the driver.
975	975
...	...	@@ -977,7 +977,7 @@
977	977	"low power mode" rather than anything to do with GPIO. This often means
978	978	the same thing electrically speaking, but in this latter case the
979	979	software engineers will usually quickly identify that this is some
980		-specific muxing/configuration rather than anything related to the GPIO
	980	+specific muxing or configuration rather than anything related to the GPIO
981	981	API.
982	982
983	983
...	...	@@ -1024,8 +1024,7 @@
1024	1024	must match a function provided by the pinmux driver handling this pin range.
1025	1025
1026	1026	As you can see we may have several pin controllers on the system and thus
1027		-we need to specify which one of them that contain the functions we wish
1028		-to map.
	1027	+we need to specify which one of them contains the functions we wish to map.
1029	1028
1030	1029	You register this pinmux mapping to the pinmux subsystem by simply:
1031	1030
1032	1031
...	...	@@ -1254,10 +1253,10 @@
1254	1253	pinctrl_get().
1255	1254
1256	1255	- pinctrl_lookup_state() is called in process context to obtain a handle to a
1257		- specific state for a the client device. This operation may be slow too.
	1256	+ specific state for a client device. This operation may be slow, too.
1258	1257
1259	1258	- pinctrl_select_state() programs pin controller hardware according to the
1260		- definition of the state as given by the mapping table. In theory this is a
	1259	+ definition of the state as given by the mapping table. In theory, this is a
1261	1260	fast-path operation, since it only involved blasting some register settings
1262	1261	into hardware. However, note that some pin controllers may have their
1263	1262	registers on a slow/IRQ-based bus, so client devices should not assume they