On Sun, 5 Jan 2020 23:50:07 +0100, Luca Ceresoli wrote:
> Among the "static" instantiation methods the "board file" method is
> described first. Move it as last, since it is being replaced by the other
> methods.
>
> Also fix subsubsection heading syntax and remove the "Method 1[abc]"
> prefix as the subsubsection structure clarifies the logical hierarchy.
>
> Signed-off-by: Luca Ceresoli <luca@xxxxxxxxxxxxxxxx>
> ---
> Documentation/i2c/instantiating-devices.rst | 98 ++++++++++++---------
> 1 file changed, 54 insertions(+), 44 deletions(-)
>
> diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
> index 5debaafef64d..cbcafb36b417 100644
> --- a/Documentation/i2c/instantiating-devices.rst
> +++ b/Documentation/i2c/instantiating-devices.rst
> @@ -9,54 +9,27 @@ reason, the kernel code must instantiate I2C devices explicitly. There are
> several ways to achieve this, depending on the context and requirements.
>
>
> -Method 1a: Declare the I2C devices by bus number
> -------------------------------------------------
> +Method 1: Declare the I2C devices statically
> +--------------------------------------------
>
> This method is appropriate when the I2C bus is a system bus as is the case
> -for many embedded systems. On such systems, each I2C bus has a number
> -which is known in advance. It is thus possible to pre-declare the I2C
> -devices which live on this bus. This is done with an array of struct
> -i2c_board_info which is registered by calling i2c_register_board_info().
> +for many embedded systems. On such systems, each I2C bus has a number which
> +is known in advance. It is thus possible to pre-declare the I2C devices
> +which live on this bus.
>
> -Example (from omap2 h4)::
> +This information is provided to the kernel in a different way on different
> +architectures: device tree, ACPI or board files.
>
> - static struct i2c_board_info h4_i2c_board_info[] __initdata = {
> - {
> - I2C_BOARD_INFO("isp1301_omap", 0x2d),
> - .irq = OMAP_GPIO_IRQ(125),
> - },
> - { /* EEPROM on mainboard */
> - I2C_BOARD_INFO("24c01", 0x52),
> - .platform_data = &m24c01,
> - },
> - { /* EEPROM on cpu card */
> - I2C_BOARD_INFO("24c01", 0x57),
> - .platform_data = &m24c01,
> - },
> - };
> -
> - static void __init omap_h4_init(void)
> - {
> - (...)
> - i2c_register_board_info(1, h4_i2c_board_info,
> - ARRAY_SIZE(h4_i2c_board_info));
> - (...)
> - }
> -
> -The above code declares 3 devices on I2C bus 1, including their respective
> -addresses and custom data needed by their drivers. When the I2C bus in
> -question is registered, the I2C devices will be instantiated automatically
> -by i2c-core.
> +When the I2C bus in question is registered, the I2C devices will be
> +instantiated automatically by i2c-core. The devices will be automatically
> +unbound and destroyed when the I2C bus they sit on goes away (if ever).
>
> -The devices will be automatically unbound and destroyed when the I2C bus
> -they sit on goes away (if ever.)
>
> +Declare the I2C devices via devicetree
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> -Method 1b: Declare the I2C devices via devicetree
> --------------------------------------------------
> -
> -This method has the same implications as method 1a. The declaration of I2C
> -devices is here done via devicetree as subnodes of the master controller.
> +On platforms using devicetree the declaration of I2C devices is done in
I suggest adding a comma between "devicetree" and "the" to make the
sentence easier to read.
> +subnodes of the master controller.
>
> Example::
>
> @@ -81,14 +54,51 @@ Here, two devices are attached to the bus using a speed of 100kHz. For
> additional properties which might be needed to set up the device, please refer
> to its devicetree documentation in Documentation/devicetree/bindings/.
>
> -
> -Method 1c: Declare the I2C devices via ACPI
> --------------------------------------------
> +Declare the I2C devices via ACPI
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> ACPI can also describe I2C devices. There is special documentation for this
> which is currently located at :doc:`../firmware-guide/acpi/enumeration` .
>
>
> +Declare the I2C devices in board files
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In many embedded architectures devicetree has replaced the old hardware
Same here between "architectures" and "devicetree".
> +description based on board files, but the latter are still used in old
> +code. Instantiating I2C devices via board files is done with an array of
> +struct i2c_board_info which is registered by calling
> +i2c_register_board_info().
> +
> +Example (from omap2 h4)::
> +
> + static struct i2c_board_info h4_i2c_board_info[] __initdata = {
> + {
> + I2C_BOARD_INFO("isp1301_omap", 0x2d),
> + .irq = OMAP_GPIO_IRQ(125),
> + },
> + { /* EEPROM on mainboard */
> + I2C_BOARD_INFO("24c01", 0x52),
> + .platform_data = &m24c01,
> + },
> + { /* EEPROM on cpu card */
> + I2C_BOARD_INFO("24c01", 0x57),
> + .platform_data = &m24c01,
> + },
> + };
> +
> + static void __init omap_h4_init(void)
> + {
> + (...)
> + i2c_register_board_info(1, h4_i2c_board_info,
> + ARRAY_SIZE(h4_i2c_board_info));
> + (...)
> + }
> +
> +The above code declares 3 devices on I2C bus 1, including their respective
> +addresses and custom data needed by their drivers.
> +
> +
> Method 2: Instantiate the devices explicitly
> --------------------------------------------
>
You have some inconsistency in your spacing between subsections, some
have 1 blank line before while some have 2. I think 1 is enough. At any
rate it should be consistent.
Reviewed-by: Jean Delvare <jdelvare@xxxxxxx>
--
Jean Delvare
SUSE L3 Support
