Hi Jean,
On 21/01/20 19:02, Jean Delvare wrote:
> 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.
OK.
>> +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.
I chose to have 2 lines as it is what was used (consistently) before my
changes.
--
Luca
