Skip to contentSkip to conversation

of-platdata: improve documentation

PATCH New Simon Goldschmidt 3 participants 4 messages Jan 7, 2019 – Jan 11, 2019

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 of-platdata: improve documentation

Improve some things in the documentation of OF_PLATDATA that I found while porting socfgpa_gen5 to it.

---

 doc/driver-model/of-plat.txt | 18 ++++++++++++------
 dts/Kconfig                  |  6 ++----
 2 files changed, 14 insertions(+), 10 deletions(-)
doc/driver-model/of-plat.txt +12 -6
index 732bc34f06..ecb5f1724b 100644
@@ -69,12 +69,12 @@ How it works
 ------------
 
 The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only available
-in SPL and should be tested with:
+in SPL/TPL and should be tested with:
 
         #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
 
 A new tool called 'dtoc' converts a device tree file either into a set of
-struct declarations, one for each compatible node, or a set of
+struct declarations, one for each compatible node, and a set of
 U_BOOT_DEVICE() declarations along with the actual platform data for each
 device. As an example, consider this MMC node:
 
@@ -156,6 +156,12 @@ This avoids the code overhead of converting the device tree data to
 platform data in the driver. The ofdata_to_platdata() method should
 therefore do nothing in such a driver.
 
+Note that for the platform data to be matched with a driver, the 'name'
+property of the U_BOOT_DEVICE() declaration has to match a driver declared
+via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a
+'name' identical to the devicetree 'compatible' string is needed, so a
+dedicated driver is required for each 'compatible' string.
+
 Where a node has multiple compatible strings, a #define is used to make them
 equivalent, e.g.:
 
@@ -165,8 +171,8 @@ equivalent, e.g.:
 Converting of-platdata to a useful form
 ---------------------------------------
 
-Of course it would be possible use the of-platdata directly in your driver
-whenever configuration information is required. However this meands that the
+Of course it would be possible to use the of-platdata directly in your driver
+whenever configuration information is required. However this means that the
 driver will not be able to support device tree, since the of-platdata
 structure is not available when device tree is used. It would make no sense
 to use this structure if device tree were available, since the structure has
@@ -282,8 +288,8 @@ prevents them being used inadvertently. All usage must be bracketed with
 The dt-platdata.c file contains the device declarations and is is built in
 spl/dt-platdata.c.
 
-Some phandles (thsoe that are recognised as such) are converted into
-points to platform data. This pointer can potentially be used to access the
+Some phandles (those that are recognised as such) are converted into
+pointer to platform data. This pointer can potentially be used to access the
 referenced device (by searching for the pointer value). This feature is not
 yet implemented, however.
 
dts/Kconfig +2 -4
index 8917f42444..3e85914d11 100644
@@ -265,8 +265,7 @@ config SPL_OF_PLATDATA
 
 	  This option works by generating C structure declarations for each
 	  compatible string, then adding platform data and U_BOOT_DEVICE
-	  declarations for each node. See README.platdata for more
-	  information.
+	  declarations for each node. See of-plat.txt for more information.
 
 config TPL_OF_PLATDATA
 	bool "Generate platform data for use in TPL"
@@ -287,8 +286,7 @@ config TPL_OF_PLATDATA
 
 	  This option works by generating C structure declarations for each
 	  compatible string, then adding platform data and U_BOOT_DEVICE
-	  declarations for each node. See README.platdata for more
-	  information.
+	  declarations for each node. See of-plat.txt for more information.
 
 endmenu
 
Signature · 1 line
2.17.1
#1 lore raw

PATCH 1/1 of-platdata: improve documentation

Quoted 10 lines · Simon Goldschmidt

Improve some things in the documentation of OF_PLATDATA that I found while porting socfgpa_gen5 to it.

---

 doc/driver-model/of-plat.txt | 18 ++++++++++++------
 dts/Kconfig                  |  6 ++----
 2 files changed, 14 insertions(+), 10 deletions(-)

doc/driver-model/of-plat.txt How it works · line 74

Quoted 13 lines
doc/driver-model/of-plat.txt +1 -1
index 732bc34f06..ecb5f1724b 100644
@@ -69,12 +69,12 @@ How it works
 ------------
 
 The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only available
-in SPL and should be tested with:
+in SPL/TPL and should be tested with:
 
         #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)

Actually that seems wrong. Shouldn't it omit the SPL_ part?

Quoted 8 lines
doc/driver-model/of-plat.txt +1 -1
 A new tool called 'dtoc' converts a device tree file either into a set of
-struct declarations, one for each compatible node, or a set of
+struct declarations, one for each compatible node, and a set of
 U_BOOT_DEVICE() declarations along with the actual platform data for each
 device. As an example, consider this MMC node:
 

doc/driver-model/of-plat.txt This avoids the code overhead of converting the device tree data to · line 163

Quoted 8 lines
doc/driver-model/of-plat.txt +5 -0
@@ -156,6 +156,12 @@ This avoids the code overhead of converting the device tree data to
 platform data in the driver. The ofdata_to_platdata() method should
 therefore do nothing in such a driver.
 
+Note that for the platform data to be matched with a driver, the 'name'
+property of the U_BOOT_DEVICE() declaration has to match a driver declared
+via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a
+'name' identical to the devicetree 'compatible' string is needed, so a
+dedicated driver is required for each 'compatible' string.

Not identical - e.g. hyphens change to underscores.

Quoted 16 lines
doc/driver-model/of-plat.txt +3 -2
+
 Where a node has multiple compatible strings, a #define is used to make them
 equivalent, e.g.:
 
@@ -165,8 +171,8 @@ equivalent, e.g.:
 Converting of-platdata to a useful form
 ---------------------------------------
 
-Of course it would be possible use the of-platdata directly in your driver
-whenever configuration information is required. However this meands that the
+Of course it would be possible to use the of-platdata directly in your driver
+whenever configuration information is required. However this means that the
 driver will not be able to support device tree, since the of-platdata
 structure is not available when device tree is used. It would make no sense
 to use this structure if device tree were available, since the structure has

doc/driver-model/of-plat.txt prevents them being used inadvertently. All usage must be bracketed with · line 292

Quoted 7 lines
doc/driver-model/of-plat.txt +2 -2
@@ -282,8 +288,8 @@ prevents them being used inadvertently. All usage must be bracketed with
 The dt-platdata.c file contains the device declarations and is is built in
 spl/dt-platdata.c.
 
-Some phandles (thsoe that are recognised as such) are converted into
-points to platform data. This pointer can potentially be used to access the
+Some phandles (those that are recognised as such) are converted into
+pointer to platform data. This pointer can potentially be used to access the

a pointer to platform data

Quoted 30 lines
doc/driver-model/of-plat.txt +0 -0
 referenced device (by searching for the pointer value). This feature is not
 yet implemented, however.
 
dts/Kconfig +2 -5
index 8917f42444..3e85914d11 100644
@@ -265,8 +265,7 @@ config SPL_OF_PLATDATA
 
          This option works by generating C structure declarations for each
          compatible string, then adding platform data and U_BOOT_DEVICE
-         declarations for each node. See README.platdata for more
-         information.
+         declarations for each node. See of-plat.txt for more information.
 
 config TPL_OF_PLATDATA
        bool "Generate platform data for use in TPL"
@@ -287,8 +286,7 @@ config TPL_OF_PLATDATA
 
          This option works by generating C structure declarations for each
          compatible string, then adding platform data and U_BOOT_DEVICE
-         declarations for each node. See README.platdata for more
-         information.
+         declarations for each node. See of-plat.txt for more information.
 
 endmenu
 
--

2.17.1

#2 lore raw

PATCH 1/1 of-platdata: improve documentation

Quoted 24 lines · Simon Glass
Quoted 10 lines · Simon Goldschmidt

Improve some things in the documentation of OF_PLATDATA that I found while porting socfgpa_gen5 to it.

---

 doc/driver-model/of-plat.txt | 18 ++++++++++++------
 dts/Kconfig                  |  6 ++----
 2 files changed, 14 insertions(+), 10 deletions(-)
Quoted 8 lines
doc/driver-model/of-plat.txt +0 -0
index 732bc34f06..ecb5f1724b 100644
@@ -69,12 +69,12 @@ How it works
 ------------
 
Quoted 7 lines

doc/driver-model/of-plat.txt How it works · line 74

Quoted 5 lines
doc/driver-model/of-plat.txt +1 -1
 The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only available
-in SPL and should be tested with:
+in SPL/TPL and should be tested with:
 
         #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)

Actually that seems wrong. Shouldn't it omit the SPL_ part?

Right, didn't catch that.

Quoted 11 lines
Quoted 11 lines
doc/driver-model/of-plat.txt +1 -1
 A new tool called 'dtoc' converts a device tree file either into a set of
-struct declarations, one for each compatible node, or a set of
+struct declarations, one for each compatible node, and a set of
 U_BOOT_DEVICE() declarations along with the actual platform data for each
 device. As an example, consider this MMC node:
 
@@ -156,6 +156,12 @@ This avoids the code overhead of converting the device tree data to
 platform data in the driver. The ofdata_to_platdata() method should
 therefore do nothing in such a driver.
 
Quoted 7 lines

doc/driver-model/of-plat.txt This avoids the code overhead of converting the device tree data to · line 163

Quoted 5 lines
doc/driver-model/of-plat.txt +5 -0
+Note that for the platform data to be matched with a driver, the 'name'
+property of the U_BOOT_DEVICE() declaration has to match a driver declared
+via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a
+'name' identical to the devicetree 'compatible' string is needed, so a
+dedicated driver is required for each 'compatible' string.

Not identical - e.g. hyphens change to underscores.

Ehrm, yeah. Seems like I need a V2...

Quoted 19 lines
Quoted 19 lines
doc/driver-model/of-plat.txt +3 -2
+
 Where a node has multiple compatible strings, a #define is used to make them
 equivalent, e.g.:
 
@@ -165,8 +171,8 @@ equivalent, e.g.:
 Converting of-platdata to a useful form
 ---------------------------------------
 
-Of course it would be possible use the of-platdata directly in your driver
-whenever configuration information is required. However this meands that the
+Of course it would be possible to use the of-platdata directly in your driver
+whenever configuration information is required. However this means that the
 driver will not be able to support device tree, since the of-platdata
 structure is not available when device tree is used. It would make no sense
 to use this structure if device tree were available, since the structure has
@@ -282,8 +288,8 @@ prevents them being used inadvertently. All usage must be bracketed with
 The dt-platdata.c file contains the device declarations and is is built in
 spl/dt-platdata.c.
 
Quoted 6 lines

doc/driver-model/of-plat.txt prevents them being used inadvertently. All usage must be bracketed with · line 292

Quoted 4 lines
doc/driver-model/of-plat.txt +2 -2
-Some phandles (thsoe that are recognised as such) are converted into
-points to platform data. This pointer can potentially be used to access the
+Some phandles (those that are recognised as such) are converted into
+pointer to platform data. This pointer can potentially be used to access the

a pointer to platform data

I'll change that as well in V2.

Regards,
Simon

Quoted 31 lines
Quoted 31 lines
doc/driver-model/of-plat.txt +0 -0
 referenced device (by searching for the pointer value). This feature is not
 yet implemented, however.
 
dts/Kconfig +2 -5
index 8917f42444..3e85914d11 100644
@@ -265,8 +265,7 @@ config SPL_OF_PLATDATA
 
          This option works by generating C structure declarations for each
          compatible string, then adding platform data and U_BOOT_DEVICE
-         declarations for each node. See README.platdata for more
-         information.
+         declarations for each node. See of-plat.txt for more information.
 
 config TPL_OF_PLATDATA
        bool "Generate platform data for use in TPL"
@@ -287,8 +286,7 @@ config TPL_OF_PLATDATA
 
          This option works by generating C structure declarations for each
          compatible string, then adding platform data and U_BOOT_DEVICE
-         declarations for each node. See README.platdata for more
-         information.
+         declarations for each node. See of-plat.txt for more information.
 
 endmenu
 
--

2.17.1

#3 lore raw

PATCH 1/1 of-platdata: improve documentation

Hi Simon,

Quoted 57 lines · Simon Glass
Quoted 24 lines
Quoted 10 lines · Simon Goldschmidt

Improve some things in the documentation of OF_PLATDATA that I found while porting socfgpa_gen5 to it.

---

 doc/driver-model/of-plat.txt | 18 ++++++++++++------
 dts/Kconfig                  |  6 ++----
 2 files changed, 14 insertions(+), 10 deletions(-)  
Quoted 8 lines
(quoted diff) +0 -0

b/doc/driver-model/of-plat.txt index 732bc34f06..ecb5f1724b 100644

doc/driver-model/of-plat.txt +0 -0
@@ -69,12 +69,12 @@ How it works
 ------------
 
Quoted 7 lines
Quoted 5 lines
doc/driver-model/of-plat.txt +0 -0
 The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only

available -in SPL and should be tested with:
+in SPL/TPL and should be tested with:

         #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)  

Actually that seems wrong. Shouldn't it omit the SPL_ part?

Right, didn't catch that.

Quoted 13 lines
Quoted 13 lines

A new tool called 'dtoc' converts a device tree file either into
a set of -struct declarations, one for each compatible node, or a set of +struct declarations, one for each compatible node, and a set of U_BOOT_DEVICE() declarations along with the actual platform data for each device. As an example, consider this MMC node:

doc/driver-model/of-plat.txt +0 -0
@@ -156,6 +156,12 @@ This avoids the code overhead of converting

the device tree data to platform data in the driver. The ofdata_to_platdata() method should therefore do nothing in such a driver.

Quoted 8 lines
Quoted 6 lines

+Note that for the platform data to be matched with a driver, the 'name' +property of the U_BOOT_DEVICE() declaration has to match a driver declared +via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a +'name' identical to the devicetree 'compatible' string is needed, so a +dedicated driver is required for each 'compatible' string.

Not identical - e.g. hyphens change to underscores.

Quoted 1 line

Ehrm, yeah. Seems like I need a V2...

If I may add my 2 cents.

Simon, could you add the information regarding what can be done and what is not yet implemented?

For example - from the other mail I've read that phandles are supported, but not parent/child relationship.

Quoted 67 lines
Quoted 22 lines
Quoted 22 lines

+
Where a node has multiple compatible strings, a #define is used
to make them equivalent, e.g.:

doc/driver-model/of-plat.txt +0 -1
@@ -165,8 +171,8 @@ equivalent, e.g.:
 Converting of-platdata to a useful form
 ---------------------------------------
 
-Of course it would be possible use the of-platdata directly in

your driver -whenever configuration information is required. However this meands that the +Of course it would be possible to use the of-platdata directly in your driver +whenever configuration information is required. However this means that the driver will not be able to support device tree, since the of-platdata structure is not available when device tree is used. It would make no sense to use this structure if device tree were available, since the structure has @@ -282,8 +288,8 @@ prevents them being used inadvertently. All usage must be bracketed with The dt-platdata.c file contains the device declarations and is is built in spl/dt-platdata.c.

Quoted 7 lines
Quoted 5 lines

-Some phandles (thsoe that are recognised as such) are converted into -points to platform data. This pointer can potentially be used to access the +Some phandles (those that are recognised as such) are converted into +pointer to platform data. This pointer can potentially be used to access the

a pointer to platform data

I'll change that as well in V2.

Regards,
Simon

Quoted 32 lines
Quoted 32 lines

referenced device (by searching for the pointer value). This
feature is not yet implemented, however.

dts/Kconfig +0 -0
index 8917f42444..3e85914d11 100644
@@ -265,8 +265,7 @@ config SPL_OF_PLATDATA
 
          This option works by generating C structure

declarations for each compatible string, then adding platform data and U_BOOT_DEVICE

dts/Kconfig +1 -2
-         declarations for each node. See README.platdata for more
-         information.
+         declarations for each node. See of-plat.txt for more

information.

config TPL_OF_PLATDATA
bool "Generate platform data for use in TPL"

dts/Kconfig +0 -0
@@ -287,8 +286,7 @@ config TPL_OF_PLATDATA
 
          This option works by generating C structure

declarations for each compatible string, then adding platform data and U_BOOT_DEVICE

dts/Kconfig +1 -2
-         declarations for each node. See README.platdata for more
-         information.
+         declarations for each node. See of-plat.txt for more

information.

endmenu

Quoted 7 lines
Quoted 3 lines
Quoted 3 lines

--
2.17.1

_______________________________________________
U-Boot mailing list
U-Boot at lists.denx.de
https://lists.denx.de/listinfo/u-boot

Best regards,

Lukasz Majewski

--

DENX Software Engineering GmbH, Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-59 Fax: (+49)-8142-66989-80 Email: lukma at denx.de -------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20190111/07e62aed/attachment.sig>