of-platdata: improve documentation
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
@@ -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
@@ -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
PATCH 1/1 of-platdata: improve documentation
Quoted 10 lines · Simon Goldschmidt
Improve some things in the documentation of
OF_PLATDATAthat I found while portingsocfgpa_gen5to it.Signed-off-by Simon Goldschmidt <[email protected]>---
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@@ -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
-1A 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
-0referenced device (by searching for the pointer value). This feature is not yet implemented, however.dts/Kconfig +2
-5@@ -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
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_PLATDATAthat I found while portingsocfgpa_gen5to it.Signed-off-by Simon Goldschmidt <[email protected]>---
doc/driver-model/of-plat.txt | 18 ++++++++++++------ dts/Kconfig | 6 ++---- 2 files changed, 14 insertions(+), 10 deletions(-)Reviewed-by Simon Glass <[email protected]>Quoted 8 lines
doc/driver-model/of-plat.txt +0
-0@@ -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
-1The 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
-1A 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 thea 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
-0referenced device (by searching for the pointer value). This feature is not yet implemented, however.dts/Kconfig +2
-5@@ -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
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_PLATDATAthat I found while portingsocfgpa_gen5to it.Signed-off-by Simon Goldschmidt <[email protected]>---
doc/driver-model/of-plat.txt | 18 ++++++++++++------ dts/Kconfig | 6 ++---- 2 files changed, 14 insertions(+), 10 deletions(-)Reviewed-by Simon Glass <[email protected]>Quoted 8 lines
(quoted diff) +0
-0
b/doc/driver-model/of-plat.txtindex732bc34f06..ecb5f1724b100644doc/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
-0The feature is enabled by CONFIG SPL_OF_PLATDATA. This is onlyavailable -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 ofU_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 convertingthe 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 +viaU_BOOT_DRIVER(). This effectively means that aU_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 inyour 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.cfile contains the device declarations and is is built inspl/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,
SimonQuoted 32 lines
Quoted 32 lines
referenced device (by searching for the pointer value). This
feature is not yet implemented, however.dts/Kconfig +0
-0@@ -265,8 +265,7 @@ config SPL_OF_PLATDATA This option works by generating C structuredeclarations for each compatible string, then adding platform data and
U_BOOT_DEVICEdts/Kconfig +1
-2- declarations for each node. See README.platdata for more - information. + declarations for each node. See of-plat.txt for moreinformation.
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 structuredeclarations for each compatible string, then adding platform data and
U_BOOT_DEVICEdts/Kconfig +1
-2- declarations for each node. See README.platdata for more - information. + declarations for each node. See of-plat.txt for moreinformation.
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>