docs: driver-model: convert docs to ReST and rename to *.rst

  will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the

  callbacks need to embed the gpio_chip in its state container and obtain a

  pointer to the container using container_of().

  (See Documentation/driver-model/design-patterns.txt)

  (See Documentation/driver-model/design-patterns.rst)

- gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip,

  as discussed above regarding different types of cascaded irqchips. The

==============

Driver Binding

==============

Driver binding is the process of associating a device with a device

driver that can control it. Bus drivers have typically handled this

When a driver is removed, the list of devices that it supports is

iterated over, and the driver's remove callback is called for each

one. The device is removed from that list and the symlinks removed.

=========

Bus Types

=========

Definition

~~~~~~~~~~

Each bus type in the kernel (PCI, USB, etc) should declare one static

object of this type. They must initialize the name field, and may

optionally initialize the match callback.

optionally initialize the match callback::

   struct bus_type pci_bus_type = {

          .name	= "pci",

lists as they please, but conversion to the bus-specific type may be

necessary.

The LDM core provides helper functions for iterating over each list.

The LDM core provides helper functions for iterating over each list::

int bus_for_each_dev(struct bus_type * bus, struct device * start, void * data,

  int bus_for_each_dev(struct bus_type * bus, struct device * start,

		       void * data,

		       int (*fn)(struct device *, void *));

  int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,

There is a top-level directory named 'bus'.

Each bus gets a directory in the bus directory, along with two default

directories:

directories::

	/sys/bus/pci/

	|-- devices

	`-- drivers

Drivers registered with the bus get a directory in the bus's drivers

directory:

directory::

	/sys/bus/pci/

	|-- devices

Each device that is discovered on a bus of that type gets a symlink in

the bus's devices directory to the device's directory in the physical

hierarchy:

hierarchy::

	/sys/bus/pci/

	|-- devices

Exporting Attributes

~~~~~~~~~~~~~~~~~~~~

::

  struct bus_attribute {

	struct attribute	attr;

	ssize_t (*show)(struct bus_type *, char * buf);

Bus drivers can export attributes using the BUS_ATTR_RW macro that works

similarly to the DEVICE_ATTR_RW macro for devices. For example, a

definition like this:

definition like this::

	static BUS_ATTR_RW(debug);

is equivalent to declaring:

is equivalent to declaring::

	static bus_attribute bus_attr_debug;

This can then be used to add and remove the attribute from the bus's

sysfs directory using:

sysfs directory using::

	int bus_create_file(struct bus_type *, struct bus_attribute *);

	void bus_remove_file(struct bus_type *, struct bus_attribute *);

==============

Device Classes

==============

Introduction

~~~~~~~~~~~~

Programming Interface

~~~~~~~~~~~~~~~~~~~~~

The device class structure looks like: 

The device class structure looks like::

  typedef int (*devclass_add)(struct device *);

See the kerneldoc for the struct class.

A typical device class definition would look like: 

A typical device class definition would look like::

  struct device_class input_devclass = {

        .name		= "input",

Each device class structure should be exported in a header file so it

can be used by drivers, extensions and interfaces.

Device classes are registered and unregistered with the core using: 

Device classes are registered and unregistered with the core using::

  int devclass_register(struct device_class * cls);

  void devclass_unregister(struct device_class * cls);

There is a top-level sysfs directory named 'class'.

Each class gets a directory in the class directory, along with two

default subdirectories:

default subdirectories::

        class/

        `-- input

Drivers registered with the class get a symlink in the drivers/ directory

that points to the driver's directory (under its bus directory):

that points to the driver's directory (under its bus directory)::

   class/

   `-- input

Each device gets a symlink in the devices/ directory that points to the

device's directory in the physical hierarchy:

device's directory in the physical hierarchy::

   class/

   `-- input

Exporting Attributes

~~~~~~~~~~~~~~~~~~~~

::

  struct devclass_attribute {

        struct attribute        attr;

        ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off);

Class drivers can export attributes using the DEVCLASS_ATTR macro that works

similarly to the DEVICE_ATTR macro for devices. For example, a definition

like this:

like this::

  static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);

is equivalent to declaring:

is equivalent to declaring::

  static devclass_attribute devclass_attr_debug;

The bus driver can add and remove the attribute from the class's

sysfs directory using:

sysfs directory using::

  int devclass_create_file(struct device_class *, struct devclass_attribute *);

  void devclass_remove_file(struct device_class *, struct devclass_attribute *);

When a device is added to a device class, the core attempts to add it

to every interface that is registered with the device class.

=============================

Device Driver Design Patterns

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

=============================

This document describes a few common design patterns found in device drivers.

It is likely that subsystem maintainers will ask driver developers to

means that the probe() function and all callbacks need to be reentrant.

The most common way to achieve this is to use the state container design

pattern. It usually has this form:

pattern. It usually has this form::

  struct foo {

      spinlock_t lock; /* Example member */

state around to all functions that need access to the state and its members.

For example, if the driver is registering an interrupt handler, you would

pass around a pointer to struct foo like this:

pass around a pointer to struct foo like this::

  static irqreturn_t foo_handler(int irq, void *arg)

  {

2. container_of()

~~~~~~~~~~~~~~~~~

Continuing on the above example we add an offloaded work:

Continuing on the above example we add an offloaded work::

  struct foo {

      spinlock_t lock;