Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Tue, 23 Apr 2019 17:42:23 -0300
From:   Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
To:     Changbin Du <changbin.du@gmail.com>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        Bjorn Helgaas <bhelgaas@google.com>, rjw@rjwysocki.net,
        linux-pci@vger.kernel.org, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org, tglx@linutronix.de, mingo@redhat.com,
        x86@kernel.org, fenghua.yu@intel.com,
        linuxppc-dev@lists.ozlabs.org, linux-acpi@vger.kernel.org,
        linux-gpio@vger.kernel.org
Subject: Re: [PATCH v4 03/63] Documentation: ACPI: move enumeration.txt to
 firmware-guide/acpi and convert to reST
Message-ID: <20190423174223.46cd298a@coco.lan>
In-Reply-To: <20190423162932.21428-4-changbin.du@gmail.com>
References: <20190423162932.21428-1-changbin.du@gmail.com>
        <20190423162932.21428-4-changbin.du@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Em Wed, 24 Apr 2019 00:28:32 +0800
Changbin Du <changbin.du@gmail.com> escreveu:

> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.

Just looking at the conversion itself, it looks good to me.

Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

> 
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
>  .../acpi/enumeration.rst}                     | 135 ++++++++++--------
>  Documentation/firmware-guide/acpi/index.rst   |   1 +
>  2 files changed, 74 insertions(+), 62 deletions(-)
>  rename Documentation/{acpi/enumeration.txt => firmware-guide/acpi/enumeration.rst} (87%)
> 
> diff --git a/Documentation/acpi/enumeration.txt b/Documentation/firmware-guide/acpi/enumeration.rst
> similarity index 87%
> rename from Documentation/acpi/enumeration.txt
> rename to Documentation/firmware-guide/acpi/enumeration.rst
> index 7bcf9c3d9fbe..ce755e963714 100644
> --- a/Documentation/acpi/enumeration.txt
> +++ b/Documentation/firmware-guide/acpi/enumeration.rst
> @@ -1,5 +1,9 @@
> -ACPI based device enumeration
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=============================
> +ACPI Based Device Enumeration
> +=============================
> +
>  ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
>  SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
>  devices behind serial bus controllers.
> @@ -11,12 +15,12 @@ that are accessed through memory-mapped registers.
>  In order to support this and re-use the existing drivers as much as
>  possible we decided to do following:
>  
> -	o Devices that have no bus connector resource are represented as
> -	  platform devices.
> +  - Devices that have no bus connector resource are represented as
> +    platform devices.
>  
> -	o Devices behind real busses where there is a connector resource
> -	  are represented as struct spi_device or struct i2c_device
> -	  (standard UARTs are not busses so there is no struct uart_device).
> +  - Devices behind real busses where there is a connector resource
> +    are represented as struct spi_device or struct i2c_device
> +    (standard UARTs are not busses so there is no struct uart_device).
>  
>  As both ACPI and Device Tree represent a tree of devices (and their
>  resources) this implementation follows the Device Tree way as much as
> @@ -31,7 +35,8 @@ enumerated from ACPI namespace. This handle can be used to extract other
>  device-specific configuration. There is an example of this below.
>  
>  Platform bus support
> -~~~~~~~~~~~~~~~~~~~~
> +====================
> +
>  Since we are using platform devices to represent devices that are not
>  connected to any physical bus we only need to implement a platform driver
>  for the device and add supported ACPI IDs. If this same IP-block is used on
> @@ -39,7 +44,7 @@ some other non-ACPI platform, the driver might work out of the box or needs
>  some minor changes.
>  
>  Adding ACPI support for an existing driver should be pretty
> -straightforward. Here is the simplest example:
> +straightforward. Here is the simplest example::
>  
>  	#ifdef CONFIG_ACPI
>  	static const struct acpi_device_id mydrv_acpi_match[] = {
> @@ -61,12 +66,13 @@ configuring GPIOs it can get its ACPI handle and extract this information
>  from ACPI tables.
>  
>  DMA support
> -~~~~~~~~~~~
> +===========
> +
>  DMA controllers enumerated via ACPI should be registered in the system to
>  provide generic access to their resources. For example, a driver that would
>  like to be accessible to slave devices via generic API call
>  dma_request_slave_channel() must register itself at the end of the probe
> -function like this:
> +function like this::
>  
>  	err = devm_acpi_dma_controller_register(dev, xlate_func, dw);
>  	/* Handle the error if it's not a case of !CONFIG_ACPI */
> @@ -74,7 +80,7 @@ function like this:
>  and implement custom xlate function if needed (usually acpi_dma_simple_xlate()
>  is enough) which converts the FixedDMA resource provided by struct
>  acpi_dma_spec into the corresponding DMA channel. A piece of code for that case
> -could look like:
> +could look like::
>  
>  	#ifdef CONFIG_ACPI
>  	struct filter_args {
> @@ -114,7 +120,7 @@ provided by struct acpi_dma.
>  Clients must call dma_request_slave_channel() with the string parameter that
>  corresponds to a specific FixedDMA resource. By default "tx" means the first
>  entry of the FixedDMA resource array, "rx" means the second entry. The table
> -below shows a layout:
> +below shows a layout::
>  
>  	Device (I2C0)
>  	{
> @@ -138,12 +144,13 @@ acpi_dma_request_slave_chan_by_index() directly and therefore choose the
>  specific FixedDMA resource by its index.
>  
>  SPI serial bus support
> -~~~~~~~~~~~~~~~~~~~~~~
> +======================
> +
>  Slave devices behind SPI bus have SpiSerialBus resource attached to them.
>  This is extracted automatically by the SPI core and the slave devices are
>  enumerated once spi_register_master() is called by the bus driver.
>  
> -Here is what the ACPI namespace for a SPI slave might look like:
> +Here is what the ACPI namespace for a SPI slave might look like::
>  
>  	Device (EEP0)
>  	{
> @@ -163,7 +170,7 @@ Here is what the ACPI namespace for a SPI slave might look like:
>  
>  The SPI device drivers only need to add ACPI IDs in a similar way than with
>  the platform device drivers. Below is an example where we add ACPI support
> -to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
> +to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::
>  
>  	#ifdef CONFIG_ACPI
>  	static const struct acpi_device_id at25_acpi_match[] = {
> @@ -182,7 +189,7 @@ to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
>  
>  Note that this driver actually needs more information like page size of the
>  eeprom etc. but at the time writing this there is no standard way of
> -passing those. One idea is to return this in _DSM method like:
> +passing those. One idea is to return this in _DSM method like::
>  
>  	Device (EEP0)
>  	{
> @@ -202,7 +209,7 @@ passing those. One idea is to return this in _DSM method like:
>  		}
>  
>  Then the at25 SPI driver can get this configuration by calling _DSM on its
> -ACPI handle like:
> +ACPI handle like::
>  
>  	struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
>  	struct acpi_object_list input;
> @@ -220,14 +227,15 @@ ACPI handle like:
>  	kfree(output.pointer);
>  
>  I2C serial bus support
> -~~~~~~~~~~~~~~~~~~~~~~
> +======================
> +
>  The slaves behind I2C bus controller only need to add the ACPI IDs like
>  with the platform and SPI drivers. The I2C core automatically enumerates
>  any slave devices behind the controller device once the adapter is
>  registered.
>  
>  Below is an example of how to add ACPI support to the existing mpu3050
> -input driver:
> +input driver::
>  
>  	#ifdef CONFIG_ACPI
>  	static const struct acpi_device_id mpu3050_acpi_match[] = {
> @@ -251,56 +259,57 @@ input driver:
>  	};
>  
>  GPIO support
> -~~~~~~~~~~~~
> +============
> +
>  ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
>  and GpioInt. These resources can be used to pass GPIO numbers used by
>  the device to the driver. ACPI 5.1 extended this with _DSD (Device
>  Specific Data) which made it possible to name the GPIOs among other things.
>  
> -For example:
> +For example::
>  
> -Device (DEV)
> -{
> -	Method (_CRS, 0, NotSerialized)
> +	Device (DEV)
>  	{
> -		Name (SBUF, ResourceTemplate()
> +		Method (_CRS, 0, NotSerialized)
>  		{
> -			...
> -			// Used to power on/off the device
> -			GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
> -				IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
> -				0x00, ResourceConsumer,,)
> +			Name (SBUF, ResourceTemplate()
>  			{
> -				// Pin List
> -				0x0055
> -			}
> +				...
> +				// Used to power on/off the device
> +				GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
> +					IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
> +					0x00, ResourceConsumer,,)
> +				{
> +					// Pin List
> +					0x0055
> +				}
> +
> +				// Interrupt for the device
> +				GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
> +					0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
> +				{
> +					// Pin list
> +					0x0058
> +				}
> +
> +				...
>  
> -			// Interrupt for the device
> -			GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
> -				 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
> -			{
> -				// Pin list
> -				0x0058
>  			}
>  
> -			...
> -
> +			Return (SBUF)
>  		}
>  
> -		Return (SBUF)
> -	}
> -
> -	// ACPI 5.1 _DSD used for naming the GPIOs
> -	Name (_DSD, Package ()
> -	{
> -		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
> -		Package ()
> +		// ACPI 5.1 _DSD used for naming the GPIOs
> +		Name (_DSD, Package ()
>  		{
> -			Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
> -			Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
> -		}
> -	})
> -	...
> +			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
> +			Package ()
> +			{
> +				Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
> +				Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
> +			}
> +		})
> +		...
>  
>  These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
>  specifies the path to the controller. In order to use these GPIOs in Linux
> @@ -310,7 +319,7 @@ There is a standard GPIO API for that and is documented in
>  Documentation/gpio/.
>  
>  In the above example we can get the corresponding two GPIO descriptors with
> -a code like this:
> +a code like this::
>  
>  	#include <linux/gpio/consumer.h>
>  	...
> @@ -334,21 +343,22 @@ See Documentation/acpi/gpio-properties.txt for more information about the
>  _DSD binding related to GPIOs.
>  
>  MFD devices
> -~~~~~~~~~~~
> +===========
> +
>  The MFD devices register their children as platform devices. For the child
>  devices there needs to be an ACPI handle that they can use to reference
>  parts of the ACPI namespace that relate to them. In the Linux MFD subsystem
>  we provide two ways:
>  
> -	o The children share the parent ACPI handle.
> -	o The MFD cell can specify the ACPI id of the device.
> +  - The children share the parent ACPI handle.
> +  - The MFD cell can specify the ACPI id of the device.
>  
>  For the first case, the MFD drivers do not need to do anything. The
>  resulting child platform device will have its ACPI_COMPANION() set to point
>  to the parent device.
>  
>  If the ACPI namespace has a device that we can match using an ACPI id or ACPI
> -adr, the cell should be set like:
> +adr, the cell should be set like::
>  
>  	static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = {
>  		.pnpid = "XYZ0001",
> @@ -366,7 +376,8 @@ the MFD device and if found, that ACPI companion device is bound to the
>  resulting child platform device.
>  
>  Device Tree namespace link device ID
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +====================================
> +
>  The Device Tree protocol uses device identification based on the "compatible"
>  property whose value is a string or an array of strings recognized as device
>  identifiers by drivers and the driver core.  The set of all those strings may be
> @@ -423,4 +434,4 @@ the _DSD of the device object itself or the _DSD of its ancestor in the
>  Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
>  property returned by it is meaningless.
>  
> -Refer to DSD-properties-rules.txt for more information.
> +Refer to :doc:`DSD-properties-rules` for more information.
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index 210ad8acd6df..99677c73f1fb 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -8,3 +8,4 @@ ACPI Support
>     :maxdepth: 1
>  
>     namespace
> +   enumeration


Thanks,
Mauro