[U-Boot] [PATCH] of-platdata: improve documentation
Improve some things in the documentation of OF_PLATDATA that I found while porting socfgpa_gen5 to it.
Signed-off-by: Simon Goldschmidt simon.k.r.goldschmidt@gmail.com ---
doc/driver-model/of-plat.txt | 18 ++++++++++++------ dts/Kconfig | 6 ++---- 2 files changed, 14 insertions(+), 10 deletions(-)
diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.txt index 732bc34f06..ecb5f1724b 100644 --- a/doc/driver-model/of-plat.txt +++ b/doc/driver-model/of-plat.txt @@ -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.
diff --git a/dts/Kconfig b/dts/Kconfig index 8917f42444..3e85914d11 100644 --- a/dts/Kconfig +++ b/dts/Kconfig @@ -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
On Mon, 7 Jan 2019 at 12:23, Simon Goldschmidt simon.k.r.goldschmidt@gmail.com wrote:
Improve some things in the documentation of OF_PLATDATA that I found while porting socfgpa_gen5 to it.
Signed-off-by: Simon Goldschmidt simon.k.r.goldschmidt@gmail.com
doc/driver-model/of-plat.txt | 18 ++++++++++++------ dts/Kconfig | 6 ++---- 2 files changed, 14 insertions(+), 10 deletions(-)
Reviewed-by: Simon Glass sjg@chromium.org
diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.txt index 732bc34f06..ecb5f1724b 100644 --- a/doc/driver-model/of-plat.txt +++ b/doc/driver-model/of-plat.txt @@ -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?
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.
Not identical - e.g. hyphens change to underscores.
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
a pointer to platform data
referenced device (by searching for the pointer value). This feature is not yet implemented, however.
diff --git a/dts/Kconfig b/dts/Kconfig index 8917f42444..3e85914d11 100644 --- a/dts/Kconfig +++ b/dts/Kconfig @@ -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 moreinformation.
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 moreinformation.
declarations for each node. See of-plat.txt for more information.endmenu
-- 2.17.1
On Thu, Jan 10, 2019 at 1:57 PM Simon Glass sjg@chromium.org wrote:
On Mon, 7 Jan 2019 at 12:23, Simon Goldschmidt simon.k.r.goldschmidt@gmail.com wrote:
Improve some things in the documentation of OF_PLATDATA that I found while porting socfgpa_gen5 to it.
Signed-off-by: Simon Goldschmidt simon.k.r.goldschmidt@gmail.com
doc/driver-model/of-plat.txt | 18 ++++++++++++------ dts/Kconfig | 6 ++---- 2 files changed, 14 insertions(+), 10 deletions(-)
Reviewed-by: Simon Glass sjg@chromium.org
diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.txt index 732bc34f06..ecb5f1724b 100644 --- a/doc/driver-model/of-plat.txt +++ b/doc/driver-model/of-plat.txt @@ -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?
Right, didn't catch that.
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.
Not identical - e.g. hyphens change to underscores.
Ehrm, yeah. Seems like I need a V2...
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
a pointer to platform data
I'll change that as well in V2.
Regards, Simon
referenced device (by searching for the pointer value). This feature is not yet implemented, however.
diff --git a/dts/Kconfig b/dts/Kconfig index 8917f42444..3e85914d11 100644 --- a/dts/Kconfig +++ b/dts/Kconfig @@ -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 moreinformation.
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 moreinformation.
declarations for each node. See of-plat.txt for more information.endmenu
-- 2.17.1
Hi Simon,
On Thu, Jan 10, 2019 at 1:57 PM Simon Glass sjg@chromium.org wrote:
On Mon, 7 Jan 2019 at 12:23, Simon Goldschmidt simon.k.r.goldschmidt@gmail.com wrote:
Improve some things in the documentation of OF_PLATDATA that I found while porting socfgpa_gen5 to it.
Signed-off-by: Simon Goldschmidt simon.k.r.goldschmidt@gmail.com
doc/driver-model/of-plat.txt | 18 ++++++++++++------ dts/Kconfig | 6 ++---- 2 files changed, 14 insertions(+), 10 deletions(-)
Reviewed-by: Simon Glass sjg@chromium.org
diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.txt index 732bc34f06..ecb5f1724b 100644 --- a/doc/driver-model/of-plat.txt +++ b/doc/driver-model/of-plat.txt @@ -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?
Right, didn't catch that.
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.
Not identical - e.g. hyphens change to underscores.
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.
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
a pointer to platform data
I'll change that as well in V2.
Regards, Simon
referenced device (by searching for the pointer value). This feature is not yet implemented, however.
diff --git a/dts/Kconfig b/dts/Kconfig index 8917f42444..3e85914d11 100644 --- a/dts/Kconfig +++ b/dts/Kconfig @@ -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_DEVICE
declarations for each node. See README.platdata for moreinformation.
declarations for each node. See of-plat.txt for moreinformation.
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 structuredeclarations for each compatible string, then adding platform data and U_BOOT_DEVICE
declarations for each node. See README.platdata for moreinformation.
declarations for each node. See of-plat.txt for moreinformation.
endmenu
-- 2.17.1
U-Boot mailing list U-Boot@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@denx.de
participants (3)
-
Lukasz Majewski -
Simon Glass -
Simon Goldschmidt