ACPI: docs: enumeration: Make footnotes links

Update the numeric footnotes so that they are rendered as hyperlinks in
the html output.

Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

ACPI: docs: enumeration: Clarify ACPI bus concepts

In some cases, ACPI drivers are implemented as a way to manage devices
enumerated with the help of the platform firmware through ACPI.

This might be confusing, since the preferred way to implement a driver
for a device that cannot be enumerated natively, is a platform
driver, as stated in the documentation.

Clarify relationships between ACPI device objects, platform devices and
ACPI Namespace entries.

Suggested-by: Elena Reshetova <elena.reshetova@intel.com>
Co-developed-by: Michal Wilczynski <michal.wilczynski@intel.com>
Signed-off-by: Michal Wilczynski <michal.wilczynski@intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

ACPI: docs: enumeration: Correct reference to the I²C device data type

I²C peripheral devices that are connected to the controller are
represented in the Linux kernel as objects of the struct i2c_client.
Fix this in the documentation.

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rjw@rjwysocki.net>

ACPI: docs: enumeration: Fix a few typos and wording mistakes

"sturct" -> "struct"
"similar than with" -> "similar to"
Missing comma, "it" and "to"

Signed-off-by: Jean Delvare <jdelvare@suse.de>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

ACPI / property: Document RS485 _DSD properties

Document RS485 related properties returned from ACPI _DSD as device
properties.

Signed-off-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
Link: https://lore.kernel.org/r/20220426122448.38997-5-ilpo.jarvinen@linux.intel.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

ACPI: docs: enumeration: Unify Package () for properties (part 2)

Unify Package () representation for properties:
- make them one line where it's possible
- add spaces between parentheses and curly braces
- drop the explicit size of package

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

docs: firmware-guide: ACPI: Add named interrupt doc

Add a detailed example of the named interrupts in the ACPI table.

Signed-off-by: Akhil R <akhilrajeev@nvidia.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

ACPI: docs: gpio-properties: Unify ASL style for GPIO examples

GPIO examples of ASL in the board.rst, enumeration.rst and gpio-properties.rst
are not unified. Unify them for better reader experience.

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Reviewed-by: Mika Westerberg <mika.westerberg@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

ACPI: docs: enumeration: Unify Package () for properties

Unify Package () representation for properties:
- make them one line where it's possible
- add spaces between parentheses and curly braces
- drop the explicit size of package

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

ACPI: docs: enumeration: Drop comma for terminator entry

Drop comma for terminator entry to avoid copy'n'paste of this pattern.

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

ACPI: docs: enumeration: Drop ugly ifdeffery from the examples

The ifdeffery around ACPI ID tables are ugly and in some cases
even less valuable than plain definitions. Drop them for good
to avoid spreading rather bad pattern.

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

ACPI: docs: enumeration: Amend PWM enumeration ASL example

Drop blank line and add a closing curly brace to make ASL example closer
to the reality.

Fixes: ef3d13b86763 ("docs: firmware-guide: ACPI: Add a PWM example")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

ACPI: docs: enumeration: Remove redundant .owner assignment

The owner member of the struct i2c_driver is assigned by a corresponding macro.
No need to assign it explicitly.

Fixes: 59c3987805a9 ("ACPI: add documentation about ACPI 5 enumeration")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

ACPI: docs: enumeration: Update UART serial bus resource documentation

In some cases UART serial bus resource may be represented by struct
serdev_device.

Fixes: 53c7626356c7 ("serdev: Add ACPI support")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

ACPI: docs: enumeration: Discourage to use custom _DSM methods

Since we have _DSD established and specified (ACPI v5.1+) there is no
need to use custom _DSM methods. Rewrite documentation to use _DSD.

Fixes: f60e7074902a ("misc: at25: Make use of device property API")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

docs: firmware-guide: ACPI: Add a PWM example

When PWM support for ACPI has been added into the kernel, it missed
the documentation update. Hence update documentation here.

Fixes: 4a6ef8e37c4d ("pwm: Add support referencing PWMs from ACPI")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: Thierry Reding <thierry.reding@gmail.com>

docs: firmware-guide: acpi: avoid using ReST :doc:`foo` markup

The :doc:`foo` tag is auto-generated via automarkup.py.
So, use the filename at the sources, instead of :doc:`foo`.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Link: https://lore.kernel.org/r/7162043c18f1ea96c446b332400e44e8087ba142.1623824363.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: ACPI: enumeration: add PCI hierarchy representation

For "fixed" PCI devices, such as chips directly soldered
on the main board (ethernet, Wi-Fi, serial ports, etc.),
it is possible to find an ACPI enumeration.

This allows to add useful properties to these devices.
Just for an example: the property "gpio-line-names" can be
added to the pins of a GPIO expander on the PCI bus.

In order to find the ACPI name of a PCI device, it's necessary
to disassemble the BIOS ACPI tables (in particular the DSDT)
and also to analyze the PCI bus topology of the board.

This patch, with a practical example, show how to do this.

Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>
Reviewed-by: Mika Westerberg <mika.westerberg@linux.intel.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

docs: firmware-guide: ACPI: Replace dma_request_slave_channel() with dma_request_chan()

dma_request_chan() is the preferred API to request slave channels.

Signed-off-by: Peter Ujfalusi <peter.ujfalusi@ti.com>
[ rjw: Subject ]
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

docs: gpio: add sysfs interface to the admin-guide

While this is stated as obsoleted, the sysfs interface described
there is still valid, and belongs to the admin-guide.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Linus Walleij <linus.walleij@linaro.org>

docs: fix broken documentation links

Mostly due to x86 and acpi conversion, several documentation
links are still pointing to the old file. Fix them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Wolfram Sang <wsa@the-dreams.de>
Reviewed-by: Sven Van Asbroeck <TheSven73@gmail.com>
Reviewed-by: Bhupesh Sharma <bhsharma@redhat.com>
Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: fix multiple doc build warnings in enumeration.rst

The conversion of acpi/enumeration.txt to RST included one markup error,
leading to many warnings like:

.../firmware-guide/acpi/enumeration.rst:430: WARNING: Unexpected indentation.

Add the missing colon and create some peace.

Fixes: c24bc66e8157 ("Documentation: ACPI: move enumeration.txt to firmware-guide/acpi and convert to reST")
Cc: Changbin Du <changbin.du@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: ACPI: move enumeration.txt to firmware-guide/acpi and convert to reST

This converts the plain text documentation to reStructuredText format
and adds it to Sphinx TOC tree.

No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>