code:
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

============================================================
Linuxized ACPICA - Introduction to ACPICA Release Automation
============================================================

:Copyright: |copy| 2013-2016, Intel Corporation

:Author: Lv Zheng <lv.zheng@intel.com>

Abstract
========
This document describes the ACPICA project and the relationship between
ACPICA and Linux.  It also describes how ACPICA code in drivers/acpi/acpica,
include/acpi and tools/power/acpi is automatically updated to follow the
upstream.

ACPICA Project
==============

The ACPI Component Architecture (ACPICA) project provides an operating
system (OS)-independent reference implementation of the Advanced
Configuration and Power Interface Specification (ACPI).  It has been
adapted by various host OSes.  By directly integrating ACPICA, Linux can
also benefit from the application experiences of ACPICA from other host
OSes.

The homepage of ACPICA project is: www.acpica.org, it is maintained and
supported by Intel Corporation.

The following figure depicts the Linux ACPI subsystem where the ACPICA
adaptation is included::

      +---------------------------------------------------------+
      |                                                         |
      |   +---------------------------------------------------+ |
      |   | +------------------+                              | |
      |   | | Table Management |                              | |
      |   | +------------------+                              | |
      |   | +----------------------+                          | |
      |   | | Namespace Management |                          | |
      |   | +----------------------+                          | |
      |   | +------------------+       ACPICA Components      | |
      |   | | Event Management |                              | |
      |   | +------------------+                              | |
      |   | +---------------------+                           | |
      |   | | Resource Management |                           | |
      |   | +---------------------+                           | |
      |   | +---------------------+                           | |
      |   | | Hardware Management |                           | |
      |   | +---------------------+                           | |
      | +---------------------------------------------------+ | |
      | | |                            +------------------+ | | |
      | | |                            | OS Service Layer | | | |
      | | |                            +------------------+ | | |
      | | +-------------------------------------------------|-+ |
      | |   +--------------------+                          |   |
      | |   | Device Enumeration |                          |   |
      | |   +--------------------+                          |   |
      | |   +------------------+                            |   |
      | |   | Power Management |                            |   |
      | |   +------------------+     Linux/ACPI Components  |   |
      | |   +--------------------+                          |   |
      | |   | Thermal Management |                          |   |
      | |   +--------------------+                          |   |
      | |   +--------------------------+                    |   |
      | |   | Drivers for ACPI Devices |                    |   |
      | |   +--------------------------+                    |   |
      | |   +--------+                                      |   |
      | |   | ...... |                                      |   |
      | |   +--------+                                      |   |
      | +---------------------------------------------------+   |
      |                                                         |
      +---------------------------------------------------------+

                 Figure 1. Linux ACPI Software Components

.. note::
    A. OS Service Layer - Provided by Linux to offer OS dependent
       implementation of the predefined ACPICA interfaces (acpi_os_*).
       ::

         include/acpi/acpiosxf.h
         drivers/acpi/osl.c
         include/acpi/platform
         include/asm/acenv.h
    B. ACPICA Functionality - Released from ACPICA code base to offer
       OS independent implementation of the ACPICA interfaces (acpi_*).
       ::

         drivers/acpi/acpica
         include/acpi/ac*.h
         tools/power/acpi
    C. Linux/ACPI Functionality - Providing Linux specific ACPI
       functionality to the other Linux kernel subsystems and user space
       programs.
       ::

         drivers/acpi
         include/linux/acpi.h
         include/linux/acpi*.h
         include/acpi
         tools/power/acpi
    D. Architecture Specific ACPICA/ACPI Functionalities - Provided by the
       ACPI subsystem to offer architecture specific implementation of the
       ACPI interfaces.  They are Linux specific components and are out of
       the scope of this document.
       ::

         include/asm/acpi.h
         include/asm/acpi*.h
         arch/*/acpi

ACPICA Release
==============

The ACPICA project maintains its code base at the following repository URL:
https://github.com/acpica/acpica.git. As a rule, a release is made every
month.

As the coding style adopted by the ACPICA project is not acceptable by
Linux, there is a release process to convert the ACPICA git commits into
Linux patches.  The patches generated by this process are referred to as
"linuxized ACPICA patches".  The release process is carried out on a local
copy the ACPICA git repository.  Each commit in the monthly release is
converted into a linuxized ACPICA patch.  Together, they form the monthly
ACPICA release patchset for the Linux ACPI community.  This process is
illustrated in the following figure::

    +-----------------------------+
    | acpica / master (-) commits |
    +-----------------------------+
       /|\         |
        |         \|/
        |  /---------------------\    +----------------------+
        | < Linuxize repo Utility >-->| old linuxized acpica |--+
        |  \---------------------/    +----------------------+  |
        |                                                       |
     /---------\                                                |
    < git reset >                                                \
     \---------/                                                  \
       /|\                                                        /+-+
        |                                                        /   |
    +-----------------------------+                             |    |
    | acpica / master (+) commits |                             |    |
    +-----------------------------+                             |    |
                   |                                            |    |
                  \|/                                           |    |
         /-----------------------\    +----------------------+  |    |
        < Linuxize repo Utilities >-->| new linuxized acpica |--+    |
         \-----------------------/    +----------------------+       |
                                                                    \|/
    +--------------------------+                  /----------------------\
    | Linuxized ACPICA Patches |<----------------< Linuxize patch Utility >
    +--------------------------+                  \----------------------/
                   |
                  \|/
     /---------------------------\
    < Linux ACPI Community Review >
     \---------------------------/
                   |
                  \|/
    +-----------------------+    /------------------\    +----------------+
    | linux-pm / linux-next |-->< Linux Merge Window >-->| linux / master |
    +-----------------------+    \------------------/    +----------------+

                Figure 2. ACPICA -> Linux Upstream Process

.. note::
    A. Linuxize Utilities - Provided by the ACPICA repository, including a
       utility located in source/tools/acpisrc folder and a number of
       scripts located in generate/linux folder.
    B. acpica / master - "master" branch of the git repository at
       <https://github.com/acpica/acpica.git>.
    C. linux-pm / linux-next - "linux-next" branch of the git repository at
       <https://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>.
    D. linux / master - "master" branch of the git repository at
       <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>.

   Before the linuxized ACPICA patches are sent to the Linux ACPI community
   for review, there is a quality assurance build test process to reduce
   porting issues.  Currently this build process only takes care of the
   following kernel configuration options:
   CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER

ACPICA Divergences
==================

Ideally, all of the ACPICA commits should be converted into Linux patches
automatically without manual modifications, the "linux / master" tree should
contain the ACPICA code that exactly corresponds to the ACPICA code
contained in "new linuxized acpica" tree and it should be possible to run
the release process fully automatically.

As a matter of fact, however, there are source code differences between
the ACPICA code in Linux and the upstream ACPICA code, referred to as
"ACPICA Divergences".

The various sources of ACPICA divergences include:
   1. Legacy divergences - Before the current ACPICA release process was
      established, there already had been divergences between Linux and
      ACPICA. Over the past several years those divergences have been greatly
      reduced, but there still are several ones and it takes time to figure
      out the underlying reasons for their existence.
   2. Manual modifications - Any manual modification (eg. coding style fixes)
      made directly in the Linux sources obviously hurts the ACPICA release
      automation.  Thus it is recommended to fix such issues in the ACPICA
      upstream source code and generate the linuxized fix using the ACPICA
      release utilities (please refer to Section 4 below for the details).
   3. Linux specific features - Sometimes it's impossible to use the
      current ACPICA APIs to implement features required by the Linux kernel,
      so Linux developers occasionally have to change ACPICA code directly.
      Those changes may not be acceptable by ACPICA upstream and in such cases
      they are left as committed ACPICA divergences unless the ACPICA side can
      implement new mechanisms as replacements for them.
   4. ACPICA release fixups - ACPICA only tests commits using a set of the
      user space simulation utilities, thus the linuxized ACPICA patches may
      break the Linux kernel, leaving us build/boot failures.  In order to
      avoid breaking Linux bisection, fixes are applied directly to the
      linuxized ACPICA patches during the release process.  When the release
      fixups are backported to the upstream ACPICA sources, they must follow
      the upstream ACPICA rules and so further modifications may appear.
      That may result in the appearance of new divergences.
   5. Fast tracking of ACPICA commits - Some ACPICA commits are regression
      fixes or stable-candidate material, so they are applied in advance with
      respect to the ACPICA release process.  If such commits are reverted or
      rebased on the ACPICA side in order to offer better solutions, new ACPICA
      divergences are generated.

ACPICA Development
==================

This paragraph guides Linux developers to use the ACPICA upstream release
utilities to obtain Linux patches corresponding to upstream ACPICA commits
before they become available from the ACPICA release process.

   1. Cherry-pick an ACPICA commit

   First you need to git clone the ACPICA repository and the ACPICA change
   you want to cherry pick must be committed into the local repository.

   Then the gen-patch.sh command can help to cherry-pick an ACPICA commit
   from the ACPICA local repository::

   $ git clone https://github.com/acpica/acpica
   $ cd acpica
   $ generate/linux/gen-patch.sh -u [commit ID]

   Here the commit ID is the ACPICA local repository commit ID you want to
   cherry pick.  It can be omitted if the commit is "HEAD".

   2. Cherry-pick recent ACPICA commits

   Sometimes you need to rebase your code on top of the most recent ACPICA
   changes that haven't been applied to Linux yet.

   You can generate the ACPICA release series yourself and rebase your code on
   top of the generated ACPICA release patches::

   $ git clone https://github.com/acpica/acpica
   $ cd acpica
   $ generate/linux/make-patches.sh -u [commit ID]

   The commit ID should be the last ACPICA commit accepted by Linux.  Usually,
   it is the commit modifying ACPI_CA_VERSION.  It can be found by executing
   "git blame source/include/acpixf.h" and referencing the line that contains
   "ACPI_CA_VERSION".

   3. Inspect the current divergences

   If you have local copies of both Linux and upstream ACPICA, you can generate
   a diff file indicating the state of the current divergences::

   # git clone https://github.com/acpica/acpica
   # git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
   # cd acpica
   # generate/linux/divergence.sh -s ../linux


code:
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

==================
ACPI Scan Handlers
==================

:Copyright: |copy| 2012, Intel Corporation

:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

During system initialization and ACPI-based device hot-add, the ACPI namespace
is scanned in search of device objects that generally represent various pieces
of hardware.  This causes a struct acpi_device object to be created and
registered with the driver core for every device object in the ACPI namespace
and the hierarchy of those struct acpi_device objects reflects the namespace
layout (i.e. parent device objects in the namespace are represented by parent
struct acpi_device objects and analogously for their children).  Those struct
acpi_device objects are referred to as "device nodes" in what follows, but they
should not be confused with struct device_node objects used by the Device Trees
parsing code (although their role is analogous to the role of those objects).

During ACPI-based device hot-remove device nodes representing pieces of hardware
being removed are unregistered and deleted.

The core ACPI namespace scanning code in drivers/acpi/scan.c carries out basic
initialization of device nodes, such as retrieving common configuration
information from the device objects represented by them and populating them with
appropriate data, but some of them require additional handling after they have
been registered.  For example, if the given device node represents a PCI host
bridge, its registration should cause the PCI bus under that bridge to be
enumerated and PCI devices on that bus to be registered with the driver core.
Similarly, if the device node represents a PCI interrupt link, it is necessary
to configure that link so that the kernel can use it.

Those additional configuration tasks usually depend on the type of the hardware
component represented by the given device node which can be determined on the
basis of the device node's hardware ID (HID).  They are performed by objects
called ACPI scan handlers represented by the following structure::

	struct acpi_scan_handler {
		const struct acpi_device_id *ids;
		struct list_head list_node;
		int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id);
		void (*detach)(struct acpi_device *dev);
	};

where ids is the list of IDs of device nodes the given handler is supposed to
take care of, list_node is the hook to the global list of ACPI scan handlers
maintained by the ACPI core and the .attach() and .detach() callbacks are
executed, respectively, after registration of new device nodes and before
unregistration of device nodes the handler attached to previously.

The namespace scanning function, acpi_bus_scan(), first registers all of the
device nodes in the given namespace scope with the driver core.  Then, it tries
to match a scan handler against each of them using the ids arrays of the
available scan handlers.  If a matching scan handler is found, its .attach()
callback is executed for the given device node.  If that callback returns 1,
that means that the handler has claimed the device node and is now responsible
for carrying out any additional configuration tasks related to it.  It also will
be responsible for preparing the device node for unregistration in that case.
The device node's handler field is then populated with the address of the scan
handler that has claimed it.

If the .attach() callback returns 0, it means that the device node is not
interesting to the given scan handler and may be matched against the next scan
handler in the list.  If it returns a (negative) error code, that means that
the namespace scan should be terminated due to a serious error.  The error code
returned should then reflect the type of the error.

The namespace trimming function, acpi_bus_trim(), first executes .detach()
callbacks from the scan handlers of all device nodes in the given namespace
scope (if they have scan handlers).  Next, it unregisters all of the device
nodes in that scope.

ACPI scan handlers can be added to the list maintained by the ACPI core with the
help of the acpi_scan_add_handler() function taking a pointer to the new scan
handler as an argument.  The order in which scan handlers are added to the list
is the order in which they are matched against device nodes during namespace
scans.

All scan handles must be added to the list before acpi_bus_scan() is run for the
first time and they cannot be removed from it.

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GPL-2.0

Managing Ownership of the Framebuffer Aperture
==============================================

.. kernel-doc:: drivers/video/aperture.c
   :doc: overview

.. kernel-doc:: include/linux/aperture.h
   :internal:

.. kernel-doc:: drivers/video/aperture.c
   :export:


code:
.. SPDX-License-Identifier: GPL-2.0-only

.. _auxiliary_bus:

=============
Auxiliary Bus
=============

.. kernel-doc:: drivers/base/auxiliary.c
   :doc: PURPOSE

When Should the Auxiliary Bus Be Used
=====================================

.. kernel-doc:: drivers/base/auxiliary.c
   :doc: USAGE

Auxiliary Device Creation
=========================

.. kernel-doc:: include/linux/auxiliary_bus.h
   :identifiers: auxiliary_device

.. kernel-doc:: drivers/base/auxiliary.c
   :identifiers: auxiliary_device_init __auxiliary_device_add
                 auxiliary_find_device

Auxiliary Device Memory Model and Lifespan
------------------------------------------

.. kernel-doc:: include/linux/auxiliary_bus.h
   :doc: DEVICE_LIFESPAN

Auxiliary Drivers
=================

.. kernel-doc:: include/linux/auxiliary_bus.h
   :identifiers: auxiliary_driver module_auxiliary_driver

.. kernel-doc:: drivers/base/auxiliary.c
   :identifiers: __auxiliary_driver_register auxiliary_driver_unregister

Example Usage
=============

.. kernel-doc:: drivers/base/auxiliary.c
   :doc: EXAMPLE


code:
====================
Kernel driver lp855x
====================

Backlight driver for LP855x ICs

Supported chips:

	Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and
	LP8557

Author: Milo(Woogyom) Kim <milo.kim@ti.com>

Description
-----------

* Brightness control

  Brightness can be controlled by the pwm input or the i2c command.
  The lp855x driver supports both cases.

* Device attributes

  1) bl_ctl_mode

  Backlight control mode.

  Value: pwm based or register based

  2) chip_id

  The lp855x chip id.

  Value: lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557

Platform data for lp855x
------------------------

For supporting platform specific data, the lp855x platform data can be used.

* name:
	Backlight driver name. If it is not defined, default name is set.
* device_control:
	Value of DEVICE CONTROL register.
* initial_brightness:
	Initial value of backlight brightness.
* period_ns:
	Platform specific PWM period value. unit is nano.
	Only valid when brightness is pwm input mode.
* size_program:
	Total size of lp855x_rom_data.
* rom_data:
	List of new eeprom/eprom registers.

Examples
========

1) lp8552 platform data: i2c register mode with new eeprom data::

    #define EEPROM_A5_ADDR	0xA5
    #define EEPROM_A5_VAL	0x4f	/* EN_VSYNC=0 */

    static struct lp855x_rom_data lp8552_eeprom_arr[] = {
	{EEPROM_A5_ADDR, EEPROM_A5_VAL},
    };

    static struct lp855x_platform_data lp8552_pdata = {
	.name = "lcd-bl",
	.device_control = I2C_CONFIG(LP8552),
	.initial_brightness = INITIAL_BRT,
	.size_program = ARRAY_SIZE(lp8552_eeprom_arr),
	.rom_data = lp8552_eeprom_arr,
    };

2) lp8556 platform data: pwm input mode with default rom data::

    static struct lp855x_platform_data lp8556_pdata = {
	.device_control = PWM_CONFIG(LP8556),
	.initial_brightness = INITIAL_BRT,
	.period_ns = 1000000,
    };


code:
Driver Basics
=============

Driver Entry and Exit points
----------------------------

.. kernel-doc:: include/linux/module.h
   :internal:

Driver device table
-------------------

.. kernel-doc:: include/linux/mod_devicetable.h
   :internal:
   :no-identifiers: pci_device_id

Delaying, scheduling, and timer routines
----------------------------------------

.. kernel-doc:: include/linux/sched.h
   :internal:

.. kernel-doc:: kernel/sched/core.c
   :export:

.. kernel-doc:: kernel/sched/cpupri.c
   :internal:

.. kernel-doc:: kernel/sched/fair.c
   :internal:

.. kernel-doc:: include/linux/completion.h
   :internal:

.. kernel-doc:: kernel/time/timer.c
   :export:

Wait queues and Wake events
---------------------------

.. kernel-doc:: include/linux/wait.h
   :internal:

.. kernel-doc:: kernel/sched/wait.c
   :export:

High-resolution timers
----------------------

.. kernel-doc:: include/linux/ktime.h
   :internal:

.. kernel-doc:: include/linux/hrtimer.h
   :internal:

.. kernel-doc:: kernel/time/hrtimer.c
   :export:

Internal Functions
------------------

.. kernel-doc:: kernel/exit.c
   :internal:

.. kernel-doc:: kernel/signal.c
   :internal:

.. kernel-doc:: include/linux/kthread.h
   :internal:

.. kernel-doc:: kernel/kthread.c
   :export:

Reference counting
------------------

.. kernel-doc:: include/linux/refcount.h
   :internal:

.. kernel-doc:: lib/refcount.c
   :export:

Atomics
-------

.. kernel-doc:: arch/x86/include/asm/atomic.h
   :internal:

Kernel objects manipulation
---------------------------

.. kernel-doc:: lib/kobject.c
   :export:

Kernel utility functions
------------------------

.. kernel-doc:: include/linux/kernel.h
   :internal:
   :no-identifiers: kstrtol kstrtoul

.. kernel-doc:: kernel/printk/printk.c
   :export:
   :no-identifiers: printk

.. kernel-doc:: kernel/panic.c
   :export:

Device Resource Management
--------------------------

.. kernel-doc:: drivers/base/devres.c
   :export:


code:
========================
The Common Clk Framework
========================

:Author: Mike Turquette <mturquette@ti.com>

This document endeavours to explain the common clk framework details,
and how to port a platform over to this framework.  It is not yet a
detailed explanation of the clock api in include/linux/clk.h, but
perhaps someday it will include that information.

Introduction and interface split
================================

The common clk framework is an interface to control the clock nodes
available on various devices today.  This may come in the form of clock
gating, rate adjustment, muxing or other operations.  This framework is
enabled with the CONFIG_COMMON_CLK option.

The interface itself is divided into two halves, each shielded from the
details of its counterpart.  First is the common definition of struct
clk which unifies the framework-level accounting and infrastructure that
has traditionally been duplicated across a variety of platforms.  Second
is a common implementation of the clk.h api, defined in
drivers/clk/clk.c.  Finally there is struct clk_ops, whose operations
are invoked by the clk api implementation.

The second half of the interface is comprised of the hardware-specific
callbacks registered with struct clk_ops and the corresponding
hardware-specific structures needed to model a particular clock.  For
the remainder of this document any reference to a callback in struct
clk_ops, such as .enable or .set_rate, implies the hardware-specific
implementation of that code.  Likewise, references to struct clk_foo
serve as a convenient shorthand for the implementation of the
hardware-specific bits for the hypothetical "foo" hardware.

Tying the two halves of this interface together is struct clk_hw, which
is defined in struct clk_foo and pointed to within struct clk_core.  This
allows for easy navigation between the two discrete halves of the common
clock interface.

Common data structures and api
==============================

Below is the common struct clk_core definition from
drivers/clk/clk.c, modified for brevity::

	struct clk_core {
		const char		*name;
		const struct clk_ops	*ops;
		struct clk_hw		*hw;
		struct module		*owner;
		struct clk_core		*parent;
		const char		**parent_names;
		struct clk_core		**parents;
		u8			num_parents;
		u8			new_parent_index;
		...
	};

The members above make up the core of the clk tree topology.  The clk
api itself defines several driver-facing functions which operate on
struct clk.  That api is documented in include/linux/clk.h.

Platforms and devices utilizing the common struct clk_core use the struct
clk_ops pointer in struct clk_core to perform the hardware-specific parts of
the operations defined in clk-provider.h::

	struct clk_ops {
		int		(*prepare)(struct clk_hw *hw);
		void		(*unprepare)(struct clk_hw *hw);
		int		(*is_prepared)(struct clk_hw *hw);
		void		(*unprepare_unused)(struct clk_hw *hw);
		int		(*enable)(struct clk_hw *hw);
		void		(*disable)(struct clk_hw *hw);
		int		(*is_enabled)(struct clk_hw *hw);
		void		(*disable_unused)(struct clk_hw *hw);
		unsigned long	(*recalc_rate)(struct clk_hw *hw,
						unsigned long parent_rate);
		long		(*round_rate)(struct clk_hw *hw,
						unsigned long rate,
						unsigned long *parent_rate);
		int		(*determine_rate)(struct clk_hw *hw,
						  struct clk_rate_request *req);
		int		(*set_parent)(struct clk_hw *hw, u8 index);
		u8		(*get_parent)(struct clk_hw *hw);
		int		(*set_rate)(struct clk_hw *hw,
					    unsigned long rate,
					    unsigned long parent_rate);
		int		(*set_rate_and_parent)(struct clk_hw *hw,
					    unsigned long rate,
					    unsigned long parent_rate,
					    u8 index);
		unsigned long	(*recalc_accuracy)(struct clk_hw *hw,
						unsigned long parent_accuracy);
		int		(*get_phase)(struct clk_hw *hw);
		int		(*set_phase)(struct clk_hw *hw, int degrees);
		void		(*init)(struct clk_hw *hw);
		void		(*debug_init)(struct clk_hw *hw,
					      struct dentry *dentry);
	};

Hardware clk implementations
============================

The strength of the common struct clk_core comes from its .ops and .hw pointers
which abstract the details of struct clk from the hardware-specific bits, and
vice versa.  To illustrate consider the simple gateable clk implementation in
drivers/clk/clk-gate.c::

	struct clk_gate {
		struct clk_hw	hw;
		void __iomem    *reg;
		u8              bit_idx;
		...
	};

struct clk_gate contains struct clk_hw hw as well as hardware-specific
knowledge about which register and bit controls this clk's gating.
Nothing about clock topology or accounting, such as enable_count or
notifier_count, is needed here.  That is all handled by the common
framework code and struct clk_core.

Let's walk through enabling this clk from driver code::

	struct clk *clk;
	clk = clk_get(NULL, "my_gateable_clk");

	clk_prepare(clk);
	clk_enable(clk);

The call graph for clk_enable is very simple::

	clk_enable(clk);
		clk->ops->enable(clk->hw);
		[resolves to...]
			clk_gate_enable(hw);
			[resolves struct clk gate with to_clk_gate(hw)]
				clk_gate_set_bit(gate);

And the definition of clk_gate_set_bit::

	static void clk_gate_set_bit(struct clk_gate *gate)
	{
		u32 reg;

		reg = __raw_readl(gate->reg);
		reg |= BIT(gate->bit_idx);
		writel(reg, gate->reg);
	}

Note that to_clk_gate is defined as::

	#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw)

This pattern of abstraction is used for every clock hardware
representation.

Supporting your own clk hardware
================================

When implementing support for a new type of clock it is only necessary to
include the following header::

	#include <linux/clk-provider.h>

To construct a clk hardware structure for your platform you must define
the following::

	struct clk_foo {
		struct clk_hw hw;
		... hardware specific data goes here ...
	};

To take advantage of your data you'll need to support valid operations
for your clk::

	struct clk_ops clk_foo_ops = {
		.enable		= &clk_foo_enable,
		.disable	= &clk_foo_disable,
	};

Implement the above functions using container_of::

	#define to_clk_foo(_hw) container_of(_hw, struct clk_foo, hw)

	int clk_foo_enable(struct clk_hw *hw)
	{
		struct clk_foo *foo;

		foo = to_clk_foo(hw);

		... perform magic on foo ...

		return 0;
	};

Below is a matrix detailing which clk_ops are mandatory based upon the
hardware capabilities of that clock.  A cell marked as "y" means
mandatory, a cell marked as "n" implies that either including that
callback is invalid or otherwise unnecessary.  Empty cells are either
optional or must be evaluated on a case-by-case basis.

.. table:: clock hardware characteristics

   +----------------+------+-------------+---------------+-------------+------+
   |                | gate | change rate | single parent | multiplexer | root |
   +================+======+=============+===============+=============+======+
   |.prepare        |      |             |               |             |      |
   +----------------+------+-------------+---------------+-------------+------+
   |.unprepare      |      |             |               |             |      |
   +----------------+------+-------------+---------------+-------------+------+
   +----------------+------+-------------+---------------+-------------+------+
   |.enable         | y    |             |               |             |      |
   +----------------+------+-------------+---------------+-------------+------+
   |.disable        | y    |             |               |             |      |
   +----------------+------+-------------+---------------+-------------+------+
   |.is_enabled     | y    |             |               |             |      |
   +----------------+------+-------------+---------------+-------------+------+
   +----------------+------+-------------+---------------+-------------+------+
   |.recalc_rate    |      | y           |               |             |      |
   +----------------+------+-------------+---------------+-------------+------+
   |.round_rate     |      | y [1]_      |               |             |      |
   +----------------+------+-------------+---------------+-------------+------+
   |.determine_rate |      | y [1]_      |               |             |      |
   +----------------+------+-------------+---------------+-------------+------+
   |.set_rate       |      | y           |               |             |      |
   +----------------+------+-------------+---------------+-------------+------+
   +----------------+------+-------------+---------------+-------------+------+
   |.set_parent     |      |             | n             | y           | n    |
   +----------------+------+-------------+---------------+-------------+------+
   |.get_parent     |      |             | n             | y           | n    |
   +----------------+------+-------------+---------------+-------------+------+
   +----------------+------+-------------+---------------+-------------+------+
   |.recalc_accuracy|      |             |               |             |      |
   +----------------+------+-------------+---------------+-------------+------+
   +----------------+------+-------------+---------------+-------------+------+
   |.init           |      |             |               |             |      |
   +----------------+------+-------------+---------------+-------------+------+

.. [1] either one of round_rate or determine_rate is required.

Finally, register your clock at run-time with a hardware-specific
registration function.  This function simply populates struct clk_foo's
data and then passes the common struct clk parameters to the framework
with a call to::

	clk_register(...)

See the basic clock types in ``drivers/clk/clk-*.c`` for examples.

Disabling clock gating of unused clocks
=======================================

Sometimes during development it can be useful to be able to bypass the
default disabling of unused clocks. For example, if drivers aren't enabling
clocks properly but rely on them being on from the bootloader, bypassing
the disabling means that the driver will remain functional while the issues
are sorted out.

To bypass this disabling, include "clk_ignore_unused" in the bootargs to the
kernel.

Locking
=======

The common clock framework uses two global locks, the prepare lock and the
enable lock.

The enable lock is a spinlock and is held across calls to the .enable,
.disable operations. Those operations are thus not allowed to sleep,
and calls to the clk_enable(), clk_disable() API functions are allowed in
atomic context.

For clk_is_enabled() API, it is also designed to be allowed to be used in
atomic context. However, it doesn't really make any sense to hold the enable
lock in core, unless you want to do something else with the information of
the enable state with that lock held. Otherwise, seeing if a clk is enabled is
a one-shot read of the enabled state, which could just as easily change after
the function returns because the lock is released. Thus the user of this API
needs to handle synchronizing the read of the state with whatever they're
using it for to make sure that the enable state doesn't change during that
time.

The prepare lock is a mutex and is held across calls to all other operations.
All those operations are allowed to sleep, and calls to the corresponding API
functions are not allowed in atomic context.

This effectively divides operations in two groups from a locking perspective.

Drivers don't need to manually protect resources shared between the operations
of one group, regardless of whether those resources are shared by multiple
clocks or not. However, access to resources that are shared between operations
of the two groups needs to be protected by the drivers. An example of such a
resource would be a register that controls both the clock rate and the clock
enable/disable state.

The clock framework is reentrant, in that a driver is allowed to call clock
framework functions from within its implementation of clock operations. This
can for instance cause a .set_rate operation of one clock being called from
within the .set_rate operation of another clock. This case must be considered
in the driver implementations, but the code flow is usually controlled by the
driver in that case.

Note that locking must also be considered when code outside of the common
clock framework needs to access resources used by the clock operations. This
is considered out of scope of this document.


code:
.. _component:

======================================
Component Helper for Aggregate Drivers
======================================

.. kernel-doc:: drivers/base/component.c
   :doc: overview

API
===

.. kernel-doc:: include/linux/component.h
   :internal:

.. kernel-doc:: drivers/base/component.c
   :export:


code:
.. SPDX-License-Identifier: GPL-2.0

================
Kernel Connector
================

Kernel connector - new netlink based userspace <-> kernel space easy
to use communication module.

The Connector driver makes it easy to connect various agents using a
netlink based network.  One must register a callback and an identifier.
When the driver receives a special netlink message with the appropriate
identifier, the appropriate callback will be called.

From the userspace point of view it's quite straightforward:

	- socket();
	- bind();
	- send();
	- recv();

But if kernelspace wants to use the full power of such connections, the
driver writer must create special sockets, must know about struct sk_buff
handling, etc...  The Connector driver allows any kernelspace agents to use
netlink based networking for inter-process communication in a significantly
easier way::

  int cn_add_callback(const struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
  void cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
  void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);

  struct cb_id
  {
	__u32			idx;
	__u32			val;
  };

idx and val are unique identifiers which must be registered in the
connector.h header for in-kernel usage.  `void (*callback) (void *)` is a
callback function which will be called when a message with above idx.val
is received by the connector core.  The argument for that function must
be dereferenced to `struct cn_msg *`::

  struct cn_msg
  {
	struct cb_id		id;

	__u32			seq;
	__u32			ack;

	__u16			len;	/* Length of the following data */
	__u16			flags;
	__u8			data[0];
  };

Connector interfaces
====================

 .. kernel-doc:: include/linux/connector.h

 Note:
   When registering new callback user, connector core assigns
   netlink group to the user which is equal to its id.idx.

Protocol description
====================

The current framework offers a transport layer with fixed headers.  The
recommended protocol which uses such a header is as following:

msg->seq and msg->ack are used to determine message genealogy.  When
someone sends a message, they use a locally unique sequence and random
acknowledge number.  The sequence number may be copied into
nlmsghdr->nlmsg_seq too.

The sequence number is incremented with each message sent.

If you expect a reply to the message, then the sequence number in the
received message MUST be the same as in the original message, and the
acknowledge number MUST be the same + 1.

If we receive a message and its sequence number is not equal to one we
are expecting, then it is a new message.  If we receive a message and
its sequence number is the same as one we are expecting, but its
acknowledge is not equal to the sequence number in the original
message + 1, then it is a new message.

Obviously, the protocol header contains the above id.

The connector allows event notification in the following form: kernel
driver or userspace process can ask connector to notify it when
selected ids will be turned on or off (registered or unregistered its
callback).  It is done by sending a special command to the connector
driver (it also registers itself with id={-1, -1}).

As example of this usage can be found in the cn_test.c module which
uses the connector to request notification and to send messages.

Reliability
===========

Netlink itself is not a reliable protocol.  That means that messages can
be lost due to memory pressure or process' receiving queue overflowed,
so caller is warned that it must be prepared.  That is why the struct
cn_msg [main connector's message header] contains u32 seq and u32 ack
fields.

Userspace usage
===============

2.6.14 has a new netlink socket implementation, which by default does not
allow people to send data to netlink groups other than 1.
So, if you wish to use a netlink socket (for example using connector)
with a different group number, the userspace application must subscribe to
that group first.  It can be achieved by the following pseudocode::

  s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);

  l_local.nl_family = AF_NETLINK;
  l_local.nl_groups = 12345;
  l_local.nl_pid = 0;

  if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
	perror("bind");
	close(s);
	return -1;
  }

  {
	int on = l_local.nl_groups;
	setsockopt(s, 270, 1, &on, sizeof(on));
  }

Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket
option.  To drop a multicast subscription, one should call the above socket
option with the NETLINK_DROP_MEMBERSHIP parameter which is defined as 0.

2.6.14 netlink code only allows to select a group which is less or equal to
the maximum group number, which is used at netlink_kernel_create() time.
In case of connector it is CN_NETLINK_USERS + 0xf, so if you want to use
group number 12345, you must increment CN_NETLINK_USERS to that number.
Additional 0xf numbers are allocated to be used by non-in-kernel users.

Due to this limitation, group 0xffffffff does not work now, so one can
not use add/remove connector's group notifications, but as far as I know,
only cn_test.c test module used it.

Some work in netlink area is still being done, so things can be changed in
2.6.15 timeframe, if it will happen, documentation will be updated for that
kernel.

Code samples
============

Sample code for a connector test module and user space can be found
in samples/connector/. To build this code, enable CONFIG_CONNECTOR
and CONFIG_SAMPLES.


code:
.. SPDX-License-Identifier: GPL-2.0

===============
Console Drivers
===============

The Linux kernel has 2 general types of console drivers.  The first type is
assigned by the kernel to all the virtual consoles during the boot process.
This type will be called 'system driver', and only one system driver is allowed
to exist. The system driver is persistent and it can never be unloaded, though
it may become inactive.

The second type has to be explicitly loaded and unloaded. This will be called
'modular driver' by this document. Multiple modular drivers can coexist at
any time with each driver sharing the console with other drivers including
the system driver. However, modular drivers cannot take over the console
that is currently occupied by another modular driver. (Exception: Drivers that
call do_take_over_console() will succeed in the takeover regardless of the type
of driver occupying the consoles.) They can only take over the console that is
occupied by the system driver. In the same token, if the modular driver is
released by the console, the system driver will take over.

Modular drivers, from the programmer's point of view, have to call::

	 do_take_over_console() - load and bind driver to console layer
	 give_up_console() - unload driver; it will only work if driver
			     is fully unbound

In newer kernels, the following are also available::

	 do_register_con_driver()
	 do_unregister_con_driver()

If sysfs is enabled, the contents of /sys/class/vtconsole can be
examined. This shows the console backends currently registered by the
system which are named vtcon<n> where <n> is an integer from 0 to 15.
Thus::

       ls /sys/class/vtconsole
       .  ..  vtcon0  vtcon1

Each directory in /sys/class/vtconsole has 3 files::

     ls /sys/class/vtconsole/vtcon0
     .  ..  bind  name  uevent

What do these files signify?

     1. bind - this is a read/write file. It shows the status of the driver if
        read, or acts to bind or unbind the driver to the virtual consoles
        when written to. The possible values are:

	0
	  - means the driver is not bound and if echo'ed, commands the driver
	    to unbind

        1
	  - means the driver is bound and if echo'ed, commands the driver to
	    bind

     2. name - read-only file. Shows the name of the driver in this format::

	  cat /sys/class/vtconsole/vtcon0/name
	  (S) VGA+

	      '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
	      commanded to bind or unbind

	      'VGA+' is the name of the driver

	  cat /sys/class/vtconsole/vtcon1/name
	  (M) frame buffer device

	      In this case, '(M)' stands for a (M)odular driver, one that can be
	      directly commanded to bind or unbind.

     3. uevent - ignore this file

When unbinding, the modular driver is detached first, and then the system
driver takes over the consoles vacated by the driver. Binding, on the other
hand, will bind the driver to the consoles that are currently occupied by a
system driver.

NOTE1:
  Binding and unbinding must be selected in Kconfig. It's under::

    Device Drivers ->
	Character devices ->
		Support for binding and unbinding console drivers

NOTE2:
  If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
  unbinding will not succeed. An example of an application that sets the
  console to KD_GRAPHICS is X.

How useful is this feature? This is very useful for console driver
developers. By unbinding the driver from the console layer, one can unload the
driver, make changes, recompile, reload and rebind the driver without any need
for rebooting the kernel. For regular users who may want to switch from
framebuffer console to VGA console and vice versa, this feature also makes
this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb
for more details.)

Notes for developers
====================

do_take_over_console() is now broken up into::

     do_register_con_driver()
     do_bind_con_driver() - private function

give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must
be fully unbound for this call to succeed. con_is_bound() will check if the
driver is bound or not.

Guidelines for console driver writers
=====================================

In order for binding to and unbinding from the console to properly work,
console drivers must follow these guidelines:

1. All drivers, except system drivers, must call either do_register_con_driver()
   or do_take_over_console(). do_register_con_driver() will just add the driver
   to the console's internal list. It won't take over the
   console. do_take_over_console(), as it name implies, will also take over (or
   bind to) the console.

2. All resources allocated during con->con_init() must be released in
   con->con_deinit().

3. All resources allocated in con->con_startup() must be released when the
   driver, which was previously bound, becomes unbound.  The console layer
   does not have a complementary call to con->con_startup() so it's up to the
   driver to check when it's legal to release these resources. Calling
   con_is_bound() in con->con_deinit() will help.  If the call returned
   false(), then it's safe to release the resources.  This balance has to be
   ensured because con->con_startup() can be called again when a request to
   rebind the driver to the console arrives.

4. Upon exit of the driver, ensure that the driver is totally unbound. If the
   condition is satisfied, then the driver must call do_unregister_con_driver()
   or give_up_console().

5. do_unregister_con_driver() can also be called on conditions which make it
   impossible for the driver to service console requests.  This can happen
   with the framebuffer console that suddenly lost all of its drivers.

The current crop of console drivers should still work correctly, but binding
and unbinding them may cause problems. With minimal fixes, these drivers can
be made to work correctly.

Antonino Daplas <adaplas@pol.net>


code:
.. SPDX-License-Identifier: GPL-2.0

====================
Compute Express Link
====================

.. toctree::
   :maxdepth: 1

   memory-devices

.. only::  subproject and html


code:
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

===================================
Compute Express Link Memory Devices
===================================

A Compute Express Link Memory Device is a CXL component that implements the
CXL.mem protocol. It contains some amount of volatile memory, persistent memory,
or both. It is enumerated as a PCI device for configuration and passing
messages over an MMIO mailbox. Its contribution to the System Physical
Address space is handled via HDM (Host Managed Device Memory) decoders
that optionally define a device's contribution to an interleaved address
range across multiple devices underneath a host-bridge or interleaved
across host-bridges.

CXL Bus: Theory of Operation
============================
Similar to how a RAID driver takes disk objects and assembles them into a new
logical device, the CXL subsystem is tasked to take PCIe and ACPI objects and
assemble them into a CXL.mem decode topology. The need for runtime configuration
of the CXL.mem topology is also similar to RAID in that different environments
with the same hardware configuration may decide to assemble the topology in
contrasting ways. One may choose performance (RAID0) striping memory across
multiple Host Bridges and endpoints while another may opt for fault tolerance
and disable any striping in the CXL.mem topology.

Platform firmware enumerates a menu of interleave options at the "CXL root port"
(Linux term for the top of the CXL decode topology). From there, PCIe topology
dictates which endpoints can participate in which Host Bridge decode regimes.
Each PCIe Switch in the path between the root and an endpoint introduces a point
at which the interleave can be split. For example platform firmware may say at a
given range only decodes to 1 one Host Bridge, but that Host Bridge may in turn
interleave cycles across multiple Root Ports. An intervening Switch between a
port and an endpoint may interleave cycles across multiple Downstream Switch
Ports, etc.

Here is a sample listing of a CXL topology defined by 'cxl_test'. The 'cxl_test'
module generates an emulated CXL topology of 2 Host Bridges each with 2 Root
Ports. Each of those Root Ports are connected to 2-way switches with endpoints
connected to those downstream ports for a total of 8 endpoints::

    # cxl list -BEMPu -b cxl_test
    {
      "bus":"root3",
      "provider":"cxl_test",
      "ports:root3":[
        {
          "port":"port5",
          "host":"cxl_host_bridge.1",
          "ports:port5":[
            {
              "port":"port8",
              "host":"cxl_switch_uport.1",
              "endpoints:port8":[
                {
                  "endpoint":"endpoint9",
                  "host":"mem2",
                  "memdev":{
                    "memdev":"mem2",
                    "pmem_size":"256.00 MiB (268.44 MB)",
                    "ram_size":"256.00 MiB (268.44 MB)",
                    "serial":"0x1",
                    "numa_node":1,
                    "host":"cxl_mem.1"
                  }
                },
                {
                  "endpoint":"endpoint15",
                  "host":"mem6",
                  "memdev":{
                    "memdev":"mem6",
                    "pmem_size":"256.00 MiB (268.44 MB)",
                    "ram_size":"256.00 MiB (268.44 MB)",
                    "serial":"0x5",
                    "numa_node":1,
                    "host":"cxl_mem.5"
                  }
                }
              ]
            },
            {
              "port":"port12",
              "host":"cxl_switch_uport.3",
              "endpoints:port12":[
                {
                  "endpoint":"endpoint17",
                  "host":"mem8",
                  "memdev":{
                    "memdev":"mem8",
                    "pmem_size":"256.00 MiB (268.44 MB)",
                    "ram_size":"256.00 MiB (268.44 MB)",
                    "serial":"0x7",
                    "numa_node":1,
                    "host":"cxl_mem.7"
                  }
                },
                {
                  "endpoint":"endpoint13",
                  "host":"mem4",
                  "memdev":{
                    "memdev":"mem4",
                    "pmem_size":"256.00 MiB (268.44 MB)",
                    "ram_size":"256.00 MiB (268.44 MB)",
                    "serial":"0x3",
                    "numa_node":1,
                    "host":"cxl_mem.3"
                  }
                }
              ]
            }
          ]
        },
        {
          "port":"port4",
          "host":"cxl_host_bridge.0",
          "ports:port4":[
            {
              "port":"port6",
              "host":"cxl_switch_uport.0",
              "endpoints:port6":[
                {
                  "endpoint":"endpoint7",
                  "host":"mem1",
                  "memdev":{
                    "memdev":"mem1",
                    "pmem_size":"256.00 MiB (268.44 MB)",
                    "ram_size":"256.00 MiB (268.44 MB)",
                    "serial":"0",
                    "numa_node":0,
                    "host":"cxl_mem.0"
                  }
                },
                {
                  "endpoint":"endpoint14",
                  "host":"mem5",
                  "memdev":{
                    "memdev":"mem5",
                    "pmem_size":"256.00 MiB (268.44 MB)",
                    "ram_size":"256.00 MiB (268.44 MB)",
                    "serial":"0x4",
                    "numa_node":0,
                    "host":"cxl_mem.4"
                  }
                }
              ]
            },
            {
              "port":"port10",
              "host":"cxl_switch_uport.2",
              "endpoints:port10":[
                {
                  "endpoint":"endpoint16",
                  "host":"mem7",
                  "memdev":{
                    "memdev":"mem7",
                    "pmem_size":"256.00 MiB (268.44 MB)",
                    "ram_size":"256.00 MiB (268.44 MB)",
                    "serial":"0x6",
                    "numa_node":0,
                    "host":"cxl_mem.6"
                  }
                },
                {
                  "endpoint":"endpoint11",
                  "host":"mem3",
                  "memdev":{
                    "memdev":"mem3",
                    "pmem_size":"256.00 MiB (268.44 MB)",
                    "ram_size":"256.00 MiB (268.44 MB)",
                    "serial":"0x2",
                    "numa_node":0,
                    "host":"cxl_mem.2"
                  }
                }
              ]
            }
          ]
        }
      ]
    }

In that listing each "root", "port", and "endpoint" object correspond a kernel
'struct cxl_port' object. A 'cxl_port' is a device that can decode CXL.mem to
its descendants. So "root" claims non-PCIe enumerable platform decode ranges and
decodes them to "ports", "ports" decode to "endpoints", and "endpoints"
represent the decode from SPA (System Physical Address) to DPA (Device Physical
Address).

Continuing the RAID analogy, disks have both topology metadata and on device
metadata that determine RAID set assembly. CXL Port topology and CXL Port link
status is metadata for CXL.mem set assembly. The CXL Port topology is enumerated
by the arrival of a CXL.mem device. I.e. unless and until the PCIe core attaches
the cxl_pci driver to a CXL Memory Expander there is no role for CXL Port
objects. Conversely for hot-unplug / removal scenarios, there is no need for
the Linux PCI core to tear down switch-level CXL resources because the endpoint
->remove() event cleans up the port data that was established to support that
Memory Expander.

The port metadata and potential decode schemes that a give memory device may
participate can be determined via a command like::

    # cxl list -BDMu -d root -m mem3
    {
      "bus":"root3",
      "provider":"cxl_test",
      "decoders:root3":[
        {
          "decoder":"decoder3.1",
          "resource":"0x8030000000",
          "size":"512.00 MiB (536.87 MB)",
          "volatile_capable":true,
          "nr_targets":2
        },
        {
          "decoder":"decoder3.3",
          "resource":"0x8060000000",
          "size":"512.00 MiB (536.87 MB)",
          "pmem_capable":true,
          "nr_targets":2
        },
        {
          "decoder":"decoder3.0",
          "resource":"0x8020000000",
          "size":"256.00 MiB (268.44 MB)",
          "volatile_capable":true,
          "nr_targets":1
        },
        {
          "decoder":"decoder3.2",
          "resource":"0x8050000000",
          "size":"256.00 MiB (268.44 MB)",
          "pmem_capable":true,
          "nr_targets":1
        }
      ],
      "memdevs:root3":[
        {
          "memdev":"mem3",
          "pmem_size":"256.00 MiB (268.44 MB)",
          "ram_size":"256.00 MiB (268.44 MB)",
          "serial":"0x2",
          "numa_node":0,
          "host":"cxl_mem.2"
        }
      ]
    }

...which queries the CXL topology to ask "given CXL Memory Expander with a kernel
device name of 'mem3' which platform level decode ranges may this device
participate". A given expander can participate in multiple CXL.mem interleave
sets simultaneously depending on how many decoder resource it has. In this
example mem3 can participate in one or more of a PMEM interleave that spans to
Host Bridges, a PMEM interleave that targets a single Host Bridge, a Volatile
memory interleave that spans 2 Host Bridges, and a Volatile memory interleave
that only targets a single Host Bridge.

Conversely the memory devices that can participate in a given platform level
decode scheme can be determined via a command like the following::

    # cxl list -MDu -d 3.2
    [
      {
        "memdevs":[
          {
            "memdev":"mem1",
            "pmem_size":"256.00 MiB (268.44 MB)",
            "ram_size":"256.00 MiB (268.44 MB)",
            "serial":"0",
            "numa_node":0,
            "host":"cxl_mem.0"
          },
          {
            "memdev":"mem5",
            "pmem_size":"256.00 MiB (268.44 MB)",
            "ram_size":"256.00 MiB (268.44 MB)",
            "serial":"0x4",
            "numa_node":0,
            "host":"cxl_mem.4"
          },
          {
            "memdev":"mem7",
            "pmem_size":"256.00 MiB (268.44 MB)",
            "ram_size":"256.00 MiB (268.44 MB)",
            "serial":"0x6",
            "numa_node":0,
            "host":"cxl_mem.6"
          },
          {
            "memdev":"mem3",
            "pmem_size":"256.00 MiB (268.44 MB)",
            "ram_size":"256.00 MiB (268.44 MB)",
            "serial":"0x2",
            "numa_node":0,
            "host":"cxl_mem.2"
          }
        ]
      },
      {
        "root decoders":[
          {
            "decoder":"decoder3.2",
            "resource":"0x8050000000",
            "size":"256.00 MiB (268.44 MB)",
            "pmem_capable":true,
            "nr_targets":1
          }
        ]
      }
    ]

...where the naming scheme for decoders is "decoder<port_id>.<instance_id>".

Driver Infrastructure
=====================

This section covers the driver infrastructure for a CXL memory device.

CXL Memory Device
-----------------

.. kernel-doc:: drivers/cxl/pci.c
   :doc: cxl pci

.. kernel-doc:: drivers/cxl/pci.c
   :internal:

.. kernel-doc:: drivers/cxl/mem.c
   :doc: cxl mem

CXL Port
--------
.. kernel-doc:: drivers/cxl/port.c
   :doc: cxl port

CXL Core
--------
.. kernel-doc:: drivers/cxl/cxl.h
   :doc: cxl objects

.. kernel-doc:: drivers/cxl/cxl.h
   :internal:

.. kernel-doc:: drivers/cxl/core/port.c
   :doc: cxl core

.. kernel-doc:: drivers/cxl/core/port.c
   :identifiers:

.. kernel-doc:: drivers/cxl/core/pci.c
   :doc: cxl core pci

.. kernel-doc:: drivers/cxl/core/pci.c
   :identifiers:

.. kernel-doc:: drivers/cxl/core/pmem.c
   :doc: cxl pmem

.. kernel-doc:: drivers/cxl/core/regs.c
   :doc: cxl registers

.. kernel-doc:: drivers/cxl/core/mbox.c
   :doc: cxl mbox

CXL Regions
-----------
.. kernel-doc:: drivers/cxl/core/region.c
   :doc: cxl core region

.. kernel-doc:: drivers/cxl/core/region.c
   :identifiers:

External Interfaces
===================

CXL IOCTL Interface
-------------------

.. kernel-doc:: include/uapi/linux/cxl_mem.h
   :doc: UAPI

.. kernel-doc:: include/uapi/linux/cxl_mem.h
   :internal:


code:
===================================
Dell Systems Management Base Driver
===================================

Overview
========

The Dell Systems Management Base Driver provides a sysfs interface for
systems management software such as Dell OpenManage to perform system
management interrupts and host control actions (system power cycle or
power off after OS shutdown) on certain Dell systems.

Dell OpenManage requires this driver on the following Dell PowerEdge systems:
300, 1300, 1400, 400SC, 500SC, 1500SC, 1550, 600SC, 1600SC, 650, 1655MC,
700, and 750.  Other Dell software such as the open source libsmbios project
is expected to make use of this driver, and it may include the use of this
driver on other Dell systems.

The Dell libsmbios project aims towards providing access to as much BIOS
information as possible.  See http://linux.dell.com/libsmbios/main/ for
more information about the libsmbios project.

System Management Interrupt
===========================

On some Dell systems, systems management software must access certain
management information via a system management interrupt (SMI).  The SMI data
buffer must reside in 32-bit address space, and the physical address of the
buffer is required for the SMI.  The driver maintains the memory required for
the SMI and provides a way for the application to generate the SMI.
The driver creates the following sysfs entries for systems management
software to perform these system management interrupts::

	/sys/devices/platform/dcdbas/smi_data
	/sys/devices/platform/dcdbas/smi_data_buf_phys_addr
	/sys/devices/platform/dcdbas/smi_data_buf_size
	/sys/devices/platform/dcdbas/smi_request

Systems management software must perform the following steps to execute
a SMI using this driver:

1) Lock smi_data.
2) Write system management command to smi_data.
3) Write "1" to smi_request to generate a calling interface SMI or
   "2" to generate a raw SMI.
4) Read system management command response from smi_data.
5) Unlock smi_data.

Host Control Action
===================

Dell OpenManage supports a host control feature that allows the administrator
to perform a power cycle or power off of the system after the OS has finished
shutting down.  On some Dell systems, this host control feature requires that
a driver perform a SMI after the OS has finished shutting down.

The driver creates the following sysfs entries for systems management software
to schedule the driver to perform a power cycle or power off host control
action after the system has finished shutting down:

/sys/devices/platform/dcdbas/host_control_action
/sys/devices/platform/dcdbas/host_control_smi_type
/sys/devices/platform/dcdbas/host_control_on_shutdown

Dell OpenManage performs the following steps to execute a power cycle or
power off host control action using this driver:

1) Write host control action to be performed to host_control_action.
2) Write type of SMI that driver needs to perform to host_control_smi_type.
3) Write "1" to host_control_on_shutdown to enable host control action.
4) Initiate OS shutdown.
   (Driver will perform host control SMI when it is notified that the OS
   has finished shutting down.)

Host Control SMI Type
=====================

The following table shows the value to write to host_control_smi_type to
perform a power cycle or power off host control action:

=================== =====================
PowerEdge System    Host Control SMI Type
=================== =====================
      300             HC_SMITYPE_TYPE1
     1300             HC_SMITYPE_TYPE1
     1400             HC_SMITYPE_TYPE2
      500SC           HC_SMITYPE_TYPE2
     1500SC           HC_SMITYPE_TYPE2
     1550             HC_SMITYPE_TYPE2
      600SC           HC_SMITYPE_TYPE2
     1600SC           HC_SMITYPE_TYPE2
      650             HC_SMITYPE_TYPE2
     1655MC           HC_SMITYPE_TYPE2
      700             HC_SMITYPE_TYPE3
      750             HC_SMITYPE_TYPE3
=================== =====================


code:
.. SPDX-License-Identifier: GPL-2.0

========================
Device Frequency Scaling
========================

Introduction
------------

This framework provides a standard kernel interface for Dynamic Voltage and
Frequency Switching on arbitrary devices.

It exposes controls for adjusting frequency through sysfs files which are
similar to the cpufreq subsystem.

Devices for which current usage can be measured can have their frequency
automatically adjusted by governors.

API
---

Device drivers need to initialize a :c:type:`devfreq_profile` and call the
:c:func:`devfreq_add_device` function to create a :c:type:`devfreq` instance.

.. kernel-doc:: include/linux/devfreq.h
.. kernel-doc:: include/linux/devfreq-event.h
.. kernel-doc:: drivers/devfreq/devfreq.c
        :export:
.. kernel-doc:: drivers/devfreq/devfreq-event.c
        :export:


code:
.. Copyright 2001 Matthew Wilcox
..
..     This documentation is free software; you can redistribute
..     it and/or modify it under the terms of the GNU General Public
..     License as published by the Free Software Foundation; either
..     version 2 of the License, or (at your option) any later
..     version.

===============================
Bus-Independent Device Accesses
===============================

:Author: Matthew Wilcox
:Author: Alan Cox

Introduction
============

Linux provides an API which abstracts performing IO across all busses
and devices, allowing device drivers to be written independently of bus
type.

Memory Mapped IO
================

Getting Access to the Device
----------------------------

The most widely supported form of IO is memory mapped IO. That is, a
part of the CPU's address space is interpreted not as accesses to
memory, but as accesses to a device. Some architectures define devices
to be at a fixed address, but most have some method of discovering
devices. The PCI bus walk is a good example of such a scheme. This
document does not cover how to receive such an address, but assumes you
are starting with one. Physical addresses are of type unsigned long.

This address should not be used directly. Instead, to get an address
suitable for passing to the accessor functions described below, you
should call ioremap(). An address suitable for accessing
the device will be returned to you.

After you've finished using the device (say, in your module's exit
routine), call iounmap() in order to return the address
space to the kernel. Most architectures allocate new address space each
time you call ioremap(), and they can run out unless you
call iounmap().

Accessing the device
--------------------

The part of the interface most used by drivers is reading and writing
memory-mapped registers on the device. Linux provides interfaces to read
and write 8-bit, 16-bit, 32-bit and 64-bit quantities. Due to a
historical accident, these are named byte, word, long and quad accesses.
Both read and write accesses are supported; there is no prefetch support
at this time.

The functions are named readb(), readw(), readl(), readq(),
readb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(),
writeb(), writew(), writel() and writeq().

Some devices (such as framebuffers) would like to use larger transfers than
8 bytes at a time. For these devices, the memcpy_toio(),
memcpy_fromio() and memset_io() functions are
provided. Do not use memset or memcpy on IO addresses; they are not
guaranteed to copy data in order.

The read and write functions are defined to be ordered. That is the
compiler is not permitted to reorder the I/O sequence. When the ordering
can be compiler optimised, you can use __readb() and friends to
indicate the relaxed ordering. Use this with care.

While the basic functions are defined to be synchronous with respect to
each other and ordered with respect to each other the busses the devices
sit on may themselves have asynchronicity. In particular many authors
are burned by the fact that PCI bus writes are posted asynchronously. A
driver author must issue a read from the same device to ensure that
writes have occurred in the specific cases the author cares. This kind
of property cannot be hidden from driver writers in the API. In some
cases, the read used to flush the device may be expected to fail (if the
card is resetting, for example). In that case, the read should be done
from config space, which is guaranteed to soft-fail if the card doesn't
respond.

The following is an example of flushing a write to a device when the
driver would like to ensure the write's effects are visible prior to
continuing execution::

    static inline void
    qla1280_disable_intrs(struct scsi_qla_host *ha)
    {
        struct device_reg *reg;

        reg = ha->iobase;
        /* disable risc and host interrupts */
        WRT_REG_WORD(&reg->ictrl, 0);
        /*
         * The following read will ensure that the above write
         * has been received by the device before we return from this
         * function.
         */
        RD_REG_WORD(&reg->ictrl);
        ha->flags.ints_enabled = 0;
    }

PCI ordering rules also guarantee that PIO read responses arrive after any
outstanding DMA writes from that bus, since for some devices the result of
a readb() call may signal to the driver that a DMA transaction is
complete. In many cases, however, the driver may want to indicate that the
next readb() call has no relation to any previous DMA writes
performed by the device. The driver can use readb_relaxed() for
these cases, although only some platforms will honor the relaxed
semantics. Using the relaxed read functions will provide significant
performance benefits on platforms that support it. The qla2xxx driver
provides examples of how to use readX_relaxed(). In many cases, a majority
of the driver's readX() calls can safely be converted to readX_relaxed()
calls, since only a few will indicate or depend on DMA completion.

Port Space Accesses
===================

Port Space Explained
--------------------

Another form of IO commonly supported is Port Space. This is a range of
addresses separate to the normal memory address space. Access to these
addresses is generally not as fast as accesses to the memory mapped
addresses, and it also has a potentially smaller address space.

Unlike memory mapped IO, no preparation is required to access port
space.

Accessing Port Space
--------------------

Accesses to this space are provided through a set of functions which
allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and
long. These functions are inb(), inw(),
inl(), outb(), outw() and
outl().

Some variants are provided for these functions. Some devices require
that accesses to their ports are slowed down. This functionality is
provided by appending a ``_p`` to the end of the function.
There are also equivalents to memcpy. The ins() and
outs() functions copy bytes, words or longs to the given
port.

__iomem pointer tokens
======================

The data type for an MMIO address is an ``__iomem`` qualified pointer, such as
``void __iomem *reg``. On most architectures it is a regular pointer that
points to a virtual memory address and can be offset or dereferenced, but in
portable code, it must only be passed from and to functions that explicitly
operated on an ``__iomem`` token, in particular the ioremap() and
readl()/writel() functions. The 'sparse' semantic code checker can be used to
verify that this is done correctly.

While on most architectures, ioremap() creates a page table entry for an
uncached virtual address pointing to the physical MMIO address, some
architectures require special instructions for MMIO, and the ``__iomem`` pointer
just encodes the physical address or an offsettable cookie that is interpreted
by readl()/writel().

Differences between I/O access functions
========================================

readq(), readl(), readw(), readb(), writeq(), writel(), writew(), writeb()

  These are the most generic accessors, providing serialization against other
  MMIO accesses and DMA accesses as well as fixed endianness for accessing
  little-endian PCI devices and on-chip peripherals. Portable device drivers
  should generally use these for any access to ``__iomem`` pointers.

  Note that posted writes are not strictly ordered against a spinlock, see
  Documentation/driver-api/io_ordering.rst.

readq_relaxed(), readl_relaxed(), readw_relaxed(), readb_relaxed(),
writeq_relaxed(), writel_relaxed(), writew_relaxed(), writeb_relaxed()

  On architectures that require an expensive barrier for serializing against
  DMA, these "relaxed" versions of the MMIO accessors only serialize against
  each other, but contain a less expensive barrier operation. A device driver
  might use these in a particularly performance sensitive fast path, with a
  comment that explains why the usage in a specific location is safe without
  the extra barriers.

  See memory-barriers.txt for a more detailed discussion on the precise ordering
  guarantees of the non-relaxed and relaxed versions.

ioread64(), ioread32(), ioread16(), ioread8(),
iowrite64(), iowrite32(), iowrite16(), iowrite8()

  These are an alternative to the normal readl()/writel() functions, with almost
  identical behavior, but they can also operate on ``__iomem`` tokens returned
  for mapping PCI I/O space with pci_iomap() or ioport_map(). On architectures
  that require special instructions for I/O port access, this adds a small
  overhead for an indirect function call implemented in lib/iomap.c, while on
  other architectures, these are simply aliases.

ioread64be(), ioread32be(), ioread16be()
iowrite64be(), iowrite32be(), iowrite16be()

  These behave in the same way as the ioread32()/iowrite32() family, but with
  reversed byte order, for accessing devices with big-endian MMIO registers.
  Device drivers that can operate on either big-endian or little-endian
  registers may have to implement a custom wrapper function that picks one or
  the other depending on which device was found.

  Note: On some architectures, the normal readl()/writel() functions
  traditionally assume that devices are the same endianness as the CPU, while
  using a hardware byte-reverse on the PCI bus when running a big-endian kernel.
  Drivers that use readl()/writel() this way are generally not portable, but
  tend to be limited to a particular SoC.

hi_lo_readq(), lo_hi_readq(), hi_lo_readq_relaxed(), lo_hi_readq_relaxed(),
ioread64_lo_hi(), ioread64_hi_lo(), ioread64be_lo_hi(), ioread64be_hi_lo(),
hi_lo_writeq(), lo_hi_writeq(), hi_lo_writeq_relaxed(), lo_hi_writeq_relaxed(),
iowrite64_lo_hi(), iowrite64_hi_lo(), iowrite64be_lo_hi(), iowrite64be_hi_lo()

  Some device drivers have 64-bit registers that cannot be accessed atomically
  on 32-bit architectures but allow two consecutive 32-bit accesses instead.
  Since it depends on the particular device which of the two halves has to be
  accessed first, a helper is provided for each combination of 64-bit accessors
  with either low/high or high/low word ordering. A device driver must include
  either <linux/io-64-nonatomic-lo-hi.h> or <linux/io-64-nonatomic-hi-lo.h> to
  get the function definitions along with helpers that redirect the normal
  readq()/writeq() to them on architectures that do not provide 64-bit access
  natively.

__raw_readq(), __raw_readl(), __raw_readw(), __raw_readb(),
__raw_writeq(), __raw_writel(), __raw_writew(), __raw_writeb()

  These are low-level MMIO accessors without barriers or byteorder changes and
  architecture specific behavior. Accesses are usually atomic in the sense that
  a four-byte __raw_readl() does not get split into individual byte loads, but
  multiple consecutive accesses can be combined on the bus. In portable code, it
  is only safe to use these to access memory behind a device bus but not MMIO
  registers, as there are no ordering guarantees with regard to other MMIO
  accesses or even spinlocks. The byte order is generally the same as for normal
  memory, so unlike the other functions, these can be used to copy data between
  kernel memory and device memory.

inl(), inw(), inb(), outl(), outw(), outb()

  PCI I/O port resources traditionally require separate helpers as they are
  implemented using special instructions on the x86 architecture. On most other
  architectures, these are mapped to readl()/writel() style accessors
  internally, usually pointing to a fixed area in virtual memory. Instead of an
  ``__iomem`` pointer, the address is a 32-bit integer token to identify a port
  number. PCI requires I/O port access to be non-posted, meaning that an outb()
  must complete before the following code executes, while a normal writeb() may
  still be in progress. On architectures that correctly implement this, I/O port
  access is therefore ordered against spinlocks. Many non-x86 PCI host bridge
  implementations and CPU architectures however fail to implement non-posted I/O
  space on PCI, so they can end up being posted on such hardware.

  In some architectures, the I/O port number space has a 1:1 mapping to
  ``__iomem`` pointers, but this is not recommended and device drivers should
  not rely on that for portability. Similarly, an I/O port number as described
  in a PCI base address register may not correspond to the port number as seen
  by a device driver. Portable drivers need to read the port number for the
  resource provided by the kernel.

  There are no direct 64-bit I/O port accessors, but pci_iomap() in combination
  with ioread64/iowrite64 can be used instead.

inl_p(), inw_p(), inb_p(), outl_p(), outw_p(), outb_p()

  On ISA devices that require specific timing, the _p versions of the I/O
  accessors add a small delay. On architectures that do not have ISA buses,
  these are aliases to the normal inb/outb helpers.

readsq, readsl, readsw, readsb
writesq, writesl, writesw, writesb
ioread64_rep, ioread32_rep, ioread16_rep, ioread8_rep
iowrite64_rep, iowrite32_rep, iowrite16_rep, iowrite8_rep
insl, insw, insb, outsl, outsw, outsb

  These are helpers that access the same address multiple times, usually to copy
  data between kernel memory byte stream and a FIFO buffer. Unlike the normal
  MMIO accessors, these do not perform a byteswap on big-endian kernels, so the
  first byte in the FIFO register corresponds to the first byte in the memory
  buffer regardless of the architecture.

Device memory mapping modes
===========================

Some architectures support multiple modes for mapping device memory.
ioremap_*() variants provide a common abstraction around these
architecture-specific modes, with a shared set of semantics.

ioremap() is the most common mapping type, and is applicable to typical device
memory (e.g. I/O registers). Other modes can offer weaker or stronger
guarantees, if supported by the architecture. From most to least common, they
are as follows:

ioremap()
---------

The default mode, suitable for most memory-mapped devices, e.g. control
registers. Memory mapped using ioremap() has the following characteristics:

* Uncached - CPU-side caches are bypassed, and all reads and writes are handled
  directly by the device
* No speculative operations - the CPU may not issue a read or write to this
  memory, unless the instruction that does so has been reached in committed
  program flow.
* No reordering - The CPU may not reorder accesses to this memory mapping with
  respect to each other. On some architectures, this relies on barriers in
  readl_relaxed()/writel_relaxed().
* No repetition - The CPU may not issue multiple reads or writes for a single
  program instruction.
* No write-combining - Each I/O operation results in one discrete read or write
  being issued to the device, and multiple writes are not combined into larger
  writes. This may or may not be enforced when using __raw I/O accessors or
  pointer dereferences.
* Non-executable - The CPU is not allowed to speculate instruction execution
  from this memory (it probably goes without saying, but you're also not
  allowed to jump into device memory).

On many platforms and buses (e.g. PCI), writes issued through ioremap()
mappings are posted, which means that the CPU does not wait for the write to
actually reach the target device before retiring the write instruction.

On many platforms, I/O accesses must be aligned with respect to the access
size; failure to do so will result in an exception or unpredictable results.

ioremap_wc()
------------

Maps I/O memory as normal memory with write combining. Unlike ioremap(),

* The CPU may speculatively issue reads from the device that the program
  didn't actually execute, and may choose to basically read whatever it wants.
* The CPU may reorder operations as long as the result is consistent from the
  program's point of view.
* The CPU may write to the same location multiple times, even when the program
  issued a single write.
* The CPU may combine several writes into a single larger write.

This mode is typically used for video framebuffers, where it can increase
performance of writes. It can also be used for other blocks of memory in
devices (e.g. buffers or shared memory), but care must be taken as accesses are
not guaranteed to be ordered with respect to normal ioremap() MMIO register
accesses without explicit barriers.

On a PCI bus, it is usually safe to use ioremap_wc() on MMIO areas marked as
``IORESOURCE_PREFETCH``, but it may not be used on those without the flag.
For on-chip devices, there is no corresponding flag, but a driver can use
ioremap_wc() on a device that is known to be safe.

ioremap_wt()
------------

Maps I/O memory as normal memory with write-through caching. Like ioremap_wc(),
but also,

* The CPU may cache writes issued to and reads from the device, and serve reads
  from that cache.

This mode is sometimes used for video framebuffers, where drivers still expect
writes to reach the device in a timely manner (and not be stuck in the CPU
cache), but reads may be served from the cache for efficiency. However, it is
rarely useful these days, as framebuffer drivers usually perform writes only,
for which ioremap_wc() is more efficient (as it doesn't needlessly trash the
cache). Most drivers should not use this.

ioremap_np()
------------

Like ioremap(), but explicitly requests non-posted write semantics. On some
architectures and buses, ioremap() mappings have posted write semantics, which
means that writes can appear to "complete" from the point of view of the
CPU before the written data actually arrives at the target device. Writes are
still ordered with respect to other writes and reads from the same device, but
due to the posted write semantics, this is not the case with respect to other
devices. ioremap_np() explicitly requests non-posted semantics, which means
that the write instruction will not appear to complete until the device has
received (and to some platform-specific extent acknowledged) the written data.

This mapping mode primarily exists to cater for platforms with bus fabrics that
require this particular mapping mode to work correctly. These platforms set the
``IORESOURCE_MEM_NONPOSTED`` flag for a resource that requires ioremap_np()
semantics and portable drivers should use an abstraction that automatically
selects it where appropriate (see the `Higher-level ioremap abstractions`_
section below).

The bare ioremap_np() is only available on some architectures; on others, it
always returns NULL. Drivers should not normally use it, unless they are
platform-specific or they derive benefit from non-posted writes where
supported, and can fall back to ioremap() otherwise. The normal approach to
ensure posted write completion is to do a dummy read after a write as
explained in `Accessing the device`_, which works with ioremap() on all
platforms.

ioremap_np() should never be used for PCI drivers. PCI memory space writes are
always posted, even on architectures that otherwise implement ioremap_np().
Using ioremap_np() for PCI BARs will at best result in posted write semantics,
and at worst result in complete breakage.

Note that non-posted write semantics are orthogonal to CPU-side ordering
guarantees. A CPU may still choose to issue other reads or writes before a
non-posted write instruction retires. See the previous section on MMIO access
functions for details on the CPU side of things.

ioremap_uc()
------------

ioremap_uc() behaves like ioremap() except that on the x86 architecture without
'PAT' mode, it marks memory as uncached even when the MTRR has designated
it as cacheable, see Documentation/x86/pat.rst.

Portable drivers should avoid the use of ioremap_uc().

ioremap_cache()
---------------

ioremap_cache() effectively maps I/O memory as normal RAM. CPU write-back
caches can be used, and the CPU is free to treat the device as if it were a
block of RAM. This should never be used for device memory which has side
effects of any kind, or which does not return the data previously written on
read.

It should also not be used for actual RAM, as the returned pointer is an
``__iomem`` token. memremap() can be used for mapping normal RAM that is outside
of the linear kernel memory area to a regular pointer.

Portable drivers should avoid the use of ioremap_cache().

Architecture example
--------------------

Here is how the above modes map to memory attribute settings on the ARM64
architecture:

+------------------------+--------------------------------------------+
| API                    | Memory region type and cacheability        |
+------------------------+--------------------------------------------+
| ioremap_np()           | Device-nGnRnE                              |
+------------------------+--------------------------------------------+
| ioremap()              | Device-nGnRE                               |
+------------------------+--------------------------------------------+
| ioremap_uc()           | (not implemented)                          |
+------------------------+--------------------------------------------+
| ioremap_wc()           | Normal-Non Cacheable                       |
+------------------------+--------------------------------------------+
| ioremap_wt()           | (not implemented; fallback to ioremap)     |
+------------------------+--------------------------------------------+
| ioremap_cache()        | Normal-Write-Back Cacheable                |
+------------------------+--------------------------------------------+

Higher-level ioremap abstractions
=================================

Instead of using the above raw ioremap() modes, drivers are encouraged to use
higher-level APIs. These APIs may implement platform-specific logic to
automatically choose an appropriate ioremap mode on any given bus, allowing for
a platform-agnostic driver to work on those platforms without any special
cases. At the time of this writing, the following ioremap() wrappers have such
logic:

devm_ioremap_resource()

  Can automatically select ioremap_np() over ioremap() according to platform
  requirements, if the ``IORESOURCE_MEM_NONPOSTED`` flag is set on the struct
  resource. Uses devres to automatically unmap the resource when the driver
  probe() function fails or a device in unbound from its driver.

  Documented in Documentation/driver-api/driver-model/devres.rst.

of_address_to_resource()

  Automatically sets the ``IORESOURCE_MEM_NONPOSTED`` flag for platforms that
  require non-posted writes for certain buses (see the nonposted-mmio and
  posted-mmio device tree properties).

of_iomap()

  Maps the resource described in a ``reg`` property in the device tree, doing
  all required translations. Automatically selects ioremap_np() according to
  platform requirements, as above.

pci_ioremap_bar(), pci_ioremap_wc_bar()

  Maps the resource described in a PCI base address without having to extract
  the physical address first.

pci_iomap(), pci_iomap_wc()

  Like pci_ioremap_bar()/pci_ioremap_bar(), but also works on I/O space when
  used together with ioread32()/iowrite32() and similar accessors

pcim_iomap()

  Like pci_iomap(), but uses devres to automatically unmap the resource when
  the driver probe() function fails or a device in unbound from its driver

  Documented in Documentation/driver-api/driver-model/devres.rst.

Not using these wrappers may make drivers unusable on certain platforms with
stricter rules for mapping I/O memory.

Generalizing Access to System and I/O Memory
============================================

.. kernel-doc:: include/linux/iosys-map.h
   :doc: overview

.. kernel-doc:: include/linux/iosys-map.h
   :internal:

Public Functions Provided
=========================

.. kernel-doc:: arch/x86/include/asm/io.h
   :internal:

.. kernel-doc:: lib/pci_iomap.c
   :export: