From: Jean Delvare <jdelvare@suse.de>
To: Luca Ceresoli <luca@lucaceresoli.net>
Cc: linux-doc@vger.kernel.org, linux-i2c@vger.kernel.org,
Wolfram Sang <wsa@the-dreams.de>, Peter Rosin <peda@axentia.se>,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH 21/26] docs: i2c: instantiating-devices: rearrange static instatiation
Date: Tue, 21 Jan 2020 19:02:31 +0100 [thread overview]
Message-ID: <20200121190231.6e88bbdc@endymion> (raw)
In-Reply-To: <20200105225012.11701-21-luca@lucaceresoli.net>
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@lucaceresoli.net>
> ---
> 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@suse.de>
--
Jean Delvare
SUSE L3 Support
next prev parent reply other threads:[~2020-01-21 18:02 UTC|newest]
Thread overview: 72+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-01-05 22:39 [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
2020-01-05 22:49 ` [PATCH 02/26] docs: i2c: summary: extend introduction Luca Ceresoli
2020-01-20 9:27 ` Jean Delvare
2020-01-20 21:54 ` Luca Ceresoli
2020-01-05 22:49 ` [PATCH 03/26] docs: i2c: summary: rewrite the "terminology" section Luca Ceresoli
2020-01-20 10:04 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 04/26] docs: i2c: call it "I2C" consistently Luca Ceresoli
2020-01-07 10:33 ` Peter Rosin
2020-01-16 9:39 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 05/26] docs: i2c: fix typo Luca Ceresoli
2020-01-07 10:33 ` Peter Rosin
2020-01-16 9:40 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 06/26] docs: i2c: replace "I2C-transfer" -> "I2C transfer" consistently Luca Ceresoli
2020-01-07 10:34 ` Peter Rosin
2020-01-20 10:07 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 07/26] docs: i2c: i2c-protocol: fix kernel-doc function syntax Luca Ceresoli
2020-01-20 10:51 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 08/26] docs: i2c: i2c-protocol: properly name start and stop conditions Luca Ceresoli
2020-01-20 12:49 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 09/26] docs: i2c: i2c-protocol: remove unneeded colons from table Luca Ceresoli
2020-01-20 13:38 ` Jean Delvare
2020-01-20 14:22 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 10/26] docs: i2c: i2c-protocol: use proper names for ACK and NACK Luca Ceresoli
2020-01-20 13:50 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 11/26] docs: i2c: smbus: fix link syntax Luca Ceresoli
2020-01-20 14:10 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 12/26] docs: i2c: smbus-protocol: properly name start and stop conditions Luca Ceresoli
2020-01-20 14:16 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 13/26] docs: i2c: smbus-protocol: remove unneeded colons from table Luca Ceresoli
2020-01-20 14:23 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 14/26] docs: i2c: smbus-protocol: use proper names for ACK and NACK Luca Ceresoli
2020-01-20 14:26 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax Luca Ceresoli
2020-01-20 14:44 ` Jean Delvare
2020-01-21 17:31 ` Luca Ceresoli
2020-01-22 11:48 ` Jean Delvare
2020-01-23 9:51 ` Luca Ceresoli
2020-01-22 14:26 ` Jean Delvare
2020-01-22 15:37 ` Wolfram Sang
2020-01-23 9:51 ` Luca Ceresoli
2020-01-05 22:50 ` [PATCH 16/26] docs: i2c: smbus-protocol: fix " Luca Ceresoli
2020-01-20 14:51 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 17/26] docs: i2c: i2c-protocol: fix typo Luca Ceresoli
2020-01-20 15:15 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 18/26] docs: i2c: i2c-protocol: fix punctuation Luca Ceresoli
2020-01-20 15:16 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 19/26] docs: i2c: smbus-protocol: improve I2C Block transactions description Luca Ceresoli
2020-01-21 9:16 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 20/26] docs: i2c: instantiating-devices: fix internal hyperlink Luca Ceresoli
2020-01-21 10:07 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 21/26] docs: i2c: instantiating-devices: rearrange static instatiation Luca Ceresoli
2020-01-21 18:02 ` Jean Delvare [this message]
2020-01-23 9:51 ` Luca Ceresoli
2020-01-05 22:50 ` [PATCH 22/26] docs: i2c: instantiating-devices: use monospace for filenames Luca Ceresoli
2020-01-22 10:08 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 23/26] docs: i2c: old-module-parameters: fix internal hyperlink Luca Ceresoli
2020-01-22 10:16 ` Jean Delvare
2020-01-23 9:50 ` Luca Ceresoli
2020-01-20 9:08 ` [PATCH 01/26] docs: i2c: sort index logically Jean Delvare
2020-01-20 9:22 ` Luca Ceresoli
2020-01-20 13:56 ` Luca Ceresoli
2020-01-06 7:46 ` [PATCH 24/26] docs: i2c: old-module-parameters: clarify this is for obsolete kernels Luca Ceresoli
2020-01-22 11:18 ` Jean Delvare
2020-01-06 7:46 ` [PATCH 25/26] docs: i2c: old-module-parameters: use monospace for filenames Luca Ceresoli
2020-01-22 11:45 ` Jean Delvare
2020-01-06 7:49 ` [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer Luca Ceresoli
2020-01-07 10:36 ` Peter Rosin
2020-01-16 9:49 ` Jean Delvare
2020-01-16 10:38 ` Luca Ceresoli
2020-01-16 13:34 ` Peter Rosin
2020-01-06 8:03 ` [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200121190231.6e88bbdc@endymion \
--to=jdelvare@suse.de \
--cc=linux-doc@vger.kernel.org \
--cc=linux-i2c@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=luca@lucaceresoli.net \
--cc=peda@axentia.se \
--cc=wsa@the-dreams.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).