Merge tag 'standardize-docs' of git://git.lwn.net/linux

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

Dynamic DMA mapping Guide

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

		 David S. Miller <davem@redhat.com>

		 Richard Henderson <rth@cygnus.com>

		  Jakub Jelinek <jakub@redhat.com>

:Author: David S. Miller <davem@redhat.com>

:Author: Richard Henderson <rth@cygnus.com>

:Author: Jakub Jelinek <jakub@redhat.com>

This is a guide to device driver writers on how to use the DMA API

with example pseudo-code.  For a concise description of the API, see

DMA-API.txt.

CPU and DMA addresses

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

There are several kinds of addresses involved in the DMA API, and it's

important to understand the differences.

The kernel normally uses virtual addresses.  Any address returned by

kmalloc(), vmalloc(), and similar interfaces is a virtual address and can

be stored in a "void *".

be stored in a ``void *``.

The virtual memory system (TLB, page tables, etc.) translates virtual

addresses to CPU physical addresses, which are stored as "phys_addr_t" or

supports 64-bit addresses for main memory and PCI BARs, it may use an IOMMU

so devices only need to use 32-bit DMA addresses.

Here's a picture and some examples:

Here's a picture and some examples::

               CPU                  CPU                  Bus

             Virtual              Physical             Address

bus-specific DMA API, i.e., use the dma_map_*() interfaces rather than the

pci_map_*() interfaces.

First of all, you should make sure

First of all, you should make sure::

	#include <linux/dma-mapping.h>

everywhere you hold a DMA address returned from the DMA mapping functions.

What memory is DMA'able?

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

The first piece of information you must know is what kernel memory can

be used with the DMA mapping facilities.  There has been an unwritten

for you to DMA from/to.

DMA addressing limitations

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

Does your device have any DMA addressing limitations?  For example, is

your device only capable of driving the low order 24-bits of address?

because this shows that you did think about these issues wrt. your

device.

The query is performed via a call to dma_set_mask_and_coherent():

The query is performed via a call to dma_set_mask_and_coherent()::

	int dma_set_mask_and_coherent(struct device *dev, u64 mask);

queries can be used instead:

	The query for streaming mappings is performed via a call to

	dma_set_mask():

	dma_set_mask()::

		int dma_set_mask(struct device *dev, u64 mask);

	The query for consistent allocations is performed via a call

	to dma_set_coherent_mask():

	to dma_set_coherent_mask()::

		int dma_set_coherent_mask(struct device *dev, u64 mask);

even detected, you can ask them for the kernel messages to find out

exactly why.

The standard 32-bit addressing device would do something like this:

The standard 32-bit addressing device would do something like this::

	if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))) {

		dev_warn(dev, "mydev: No suitable DMA available\n");

more efficient than DAC addressing.

Here is how you would handle a 64-bit capable device which can drive

all 64-bits when accessing streaming DMA:

all 64-bits when accessing streaming DMA::

	int using_dac;

	}

If a card is capable of using 64-bit consistent allocations as well,

the case would look like this:

the case would look like this::

	int using_dac, consistent_using_dac;

dma_set_coherent_mask().

Finally, if your device can only drive the low 24-bits of

address you might do something like:

address you might do something like::

	if (dma_set_mask(dev, DMA_BIT_MASK(24))) {

		dev_warn(dev, "mydev: 24-bit DMA addressing not available\n");

is important that the last call to dma_set_mask() be for the

most specific mask.

Here is pseudo-code showing how this might be done:

Here is pseudo-code showing how this might be done::

	#define PLAYBACK_ADDRESS_BITS	DMA_BIT_MASK(32)

	#define RECORD_ADDRESS_BITS	DMA_BIT_MASK(24)

and thus retaining the 16MB DMA addressing limitations of ISA.

Types of DMA mappings

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

There are two types of DMA mappings:

  to memory is immediately visible to the device, and vice

  versa.  Consistent mappings guarantee this.

  IMPORTANT: Consistent DMA memory does not preclude the usage of

  .. important::

	     Consistent DMA memory does not preclude the usage of

	     proper memory barriers.  The CPU may reorder stores to

	     consistent memory just as it may normal memory.  Example:

	     if it is important for the device to see the first word

	     of a descriptor updated before the second, you must do

	     something like:

	     something like::

		desc->word0 = address;

		wmb();

when the underlying buffers don't share cache lines with other data.

		 Using Consistent DMA mappings.

Using Consistent DMA mappings

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

To allocate and map large (PAGE_SIZE or so) consistent DMA regions,

you should do:

you should do::

	dma_addr_t dma_handle;

	cpu_addr = dma_alloc_coherent(dev, size, &dma_handle, gfp);

where device is a struct device *. This may be called in interrupt

where device is a ``struct device *``. This may be called in interrupt

context with the GFP_ATOMIC flag.

Size is the length of the region you want to allocate, in bytes.

which is smaller than or equal to 64 kilobytes, the extent of the

buffer you receive will not cross a 64K boundary.

To unmap and free such a DMA region, you call:

To unmap and free such a DMA region, you call::

	dma_free_coherent(dev, size, cpu_addr, dma_handle);

Also, it understands common hardware constraints for alignment,

like queue heads needing to be aligned on N byte boundaries.

Create a dma_pool like this:

Create a dma_pool like this::

	struct dma_pool *pool;

must not cross 4KByte boundaries (but at that time it may be better to

use dma_alloc_coherent() directly instead).

Allocate memory from a DMA pool like this:

Allocate memory from a DMA pool like this::

	cpu_addr = dma_pool_alloc(pool, flags, &dma_handle);

holding SMP locks), GFP_ATOMIC otherwise.  Like dma_alloc_coherent(),

this returns two values, cpu_addr and dma_handle.

Free memory that was allocated from a dma_pool like this:

Free memory that was allocated from a dma_pool like this::

	dma_pool_free(pool, cpu_addr, dma_handle);

dma_handle are the values dma_pool_alloc() returned. This function

may be called in interrupt context.

Destroy a dma_pool by calling:

Destroy a dma_pool by calling::

	dma_pool_destroy(pool);

be called in interrupt context.

DMA Direction

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

The interfaces described in subsequent portions of this document

take a DMA direction argument, which is an integer and takes on

one of the following values:

one of the following values::

 DMA_BIDIRECTIONAL

 DMA_TO_DEVICE

with the DMA_FROM_DEVICE direction specifier.

Using Streaming DMA mappings

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

The streaming DMA mapping routines can be called from interrupt

context.  There are two versions of each map/unmap, one which will

map/unmap a single memory region, and one which will map/unmap a

scatterlist.

To map a single region, you do:

To map a single region, you do::

	struct device *dev = &my_dev->dev;

	dma_addr_t dma_handle;

		goto map_error_handling;

	}

and to unmap it:

and to unmap it::

	dma_unmap_single(dev, dma_handle, size, direction);

you cannot reference HIGHMEM memory in this way.  Thus, there is a

map/unmap interface pair akin to dma_{map,unmap}_single().  These

interfaces deal with page/offset pairs instead of CPU pointers.

Specifically:

Specifically::

	struct device *dev = &my_dev->dev;

	dma_addr_t dma_handle;

You should call dma_unmap_page() when the DMA activity is finished, e.g.,

from the interrupt which told you that the DMA transfer is done.

With scatterlists, you map a region gathered from several regions by:

With scatterlists, you map a region gathered from several regions by::

	int i, count = dma_map_sg(dev, sglist, nents, direction);

	struct scatterlist *sg;

and use sg_dma_address() and sg_dma_len() macros where you previously

accessed sg->address and sg->length as shown above.

To unmap a scatterlist, just call:

To unmap a scatterlist, just call::

	dma_unmap_sg(dev, sglist, nents, direction);

Again, make sure DMA activity has already finished.

PLEASE NOTE:  The 'nents' argument to the dma_unmap_sg call must be

.. note::

	The 'nents' argument to the dma_unmap_sg call must be

	the _same_ one you passed into the dma_map_sg call,

	it should _NOT_ be the 'count' value _returned_ from the

	dma_map_sg call.

correct copy of the DMA buffer.

So, firstly, just map it with dma_map_{single,sg}(), and after each DMA

transfer call either:

transfer call either::

	dma_sync_single_for_cpu(dev, dma_handle, size, direction);

or:

or::

	dma_sync_sg_for_cpu(dev, sglist, nents, direction);

Then, if you wish to let the device get at the DMA area again,

finish accessing the data with the CPU, and then before actually

giving the buffer to the hardware call either:

giving the buffer to the hardware call either::

	dma_sync_single_for_device(dev, dma_handle, size, direction);

or:

or::

	dma_sync_sg_for_device(dev, sglist, nents, direction);

as appropriate.

PLEASE NOTE:  The 'nents' argument to dma_sync_sg_for_cpu() and

.. note::

	      The 'nents' argument to dma_sync_sg_for_cpu() and

	      dma_sync_sg_for_device() must be the same passed to

	      dma_map_sg(). It is _NOT_ the count returned by

	      dma_map_sg().

dma_sync_*() routines at all.

Here is pseudo code which shows a situation in which you would need

to use the dma_sync_*() interfaces.

to use the dma_sync_*() interfaces::

	my_card_setup_receive_buffer(struct my_card *cp, char *buffer, int len)

	{

as it is impossible to correctly support them.

Handling Errors

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

DMA address space is limited on some architectures and an allocation

failure can be determined by:

- checking if dma_alloc_coherent() returns NULL or dma_map_sg returns 0

- checking the dma_addr_t returned from dma_map_single() and dma_map_page()

  by using dma_mapping_error():

  by using dma_mapping_error()::

	dma_addr_t dma_handle;

  of a multiple page mapping attempt. These example are applicable to

  dma_map_page() as well.

Example 1:

Example 1::

	dma_addr_t dma_handle1;

	dma_addr_t dma_handle2;

		dma_unmap_single(dma_handle1);

	map_error_handling1:

Example 2: (if buffers are allocated in a loop, unmap all mapped buffers when

	    mapping error is detected in the middle)

Example 2::

	/*

	 * if buffers are allocated in a loop, unmap all mapped buffers when

	 * mapping error is detected in the middle

	 */

	dma_addr_t dma_addr;

	dma_addr_t array[DMA_BUFFERS];

passes the command to the driver again later.

Optimizing Unmap State Space Consumption

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

On many platforms, dma_unmap_{single,page}() is simply a nop.

Therefore, keeping track of the mapping address and length is a waste

transform some example code.

1) Use DEFINE_DMA_UNMAP_{ADDR,LEN} in state saving structures.

   Example, before:

   Example, before::

	struct ring_state {

		struct sk_buff *skb;

		__u32 len;

	};

   after:

   after::

	struct ring_state {

		struct sk_buff *skb;

	};

2) Use dma_unmap_{addr,len}_set() to set these values.

   Example, before:

   Example, before::

	ringp->mapping = FOO;

	ringp->len = BAR;

   after:

   after::

	dma_unmap_addr_set(ringp, mapping, FOO);

	dma_unmap_len_set(ringp, len, BAR);

3) Use dma_unmap_{addr,len}() to access these values.

   Example, before:

   Example, before::

	dma_unmap_single(dev, ringp->mapping, ringp->len,

			 DMA_FROM_DEVICE);

   after:

   after::

	dma_unmap_single(dev,

			 dma_unmap_addr(ringp, mapping),

need the address in order to perform the unmap operation.

Platform Issues

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

If you are just writing drivers for Linux and do not maintain

an architecture port for the kernel, you can safely skip down

   objects).

Closing

=======

This document, and the API itself, would not be in its current

form without the feedback and suggestions from numerous individuals.

We would like to specifically mention, in no particular order, the

following people:

following people::

	Russell King <rmk@arm.linux.org.uk>

	Leo Dagum <dagum@barrel.engr.sgi.com>

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

DMA with ISA and LPC devices

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

                      Pierre Ossman <drzeus@drzeus.cx>

:Author: Pierre Ossman <drzeus@drzeus.cx>

This document describes how to do DMA transfers using the old ISA DMA

controller. Even though ISA is more or less dead today the LPC bus

uses the same DMA system so it will be around for quite some time.

Part I - Headers and dependencies

---------------------------------

Headers and dependencies

------------------------

To do ISA style DMA you need to include two headers:

To do ISA style DMA you need to include two headers::

	#include <linux/dma-mapping.h>

	#include <asm/dma.h>

Kconfig to be dependent on ISA_DMA_API (not ISA) so that nobody tries

to build your driver on unsupported platforms.

Part II - Buffer allocation

---------------------------

Buffer allocation

-----------------

The ISA DMA controller has some very strict requirements on which

memory it can access so extra care must be taken when allocating

(This scarcity also means that you should allocate the buffer as

early as possible and not release it until the driver is unloaded.)

Part III - Address translation

------------------------------

Address translation

-------------------

To translate the virtual address to a bus address, use the normal DMA

API. Do _not_ use isa_virt_to_phys() even though it does the same

been fixed. If your arch has problems then fix the DMA API instead of

reverting to the ISA functions.

Part IV - Channels

------------------

Channels

--------

A normal ISA DMA controller has 8 channels. The lower four are for

8-bit transfers and the upper four are for 16-bit transfers.

driver author but depends on what the hardware supports. Check your

specs or test different channels.

Part V - Transfer data

----------------------

Transfer data

-------------

Now for the good stuff, the actual DMA transfer. :)

the channel again. You should also check get_dma_residue() to make

sure that all data has been transferred.

Example:

Example::

	int flags, residue;

	release_dma_lock(flags);

Part VI - Suspend/resume

------------------------

Suspend/resume

--------------

It is the driver's responsibility to make sure that the machine isn't

suspended while a DMA transfer is in progress. Also, all DMA settings

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

DMA attributes

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

the time to try to allocate memory to in a way that gives better TLB

efficiency (AKA it's not worth trying to build the mapping out of larger

pages).  You might want to specify this if:

- You know that the accesses to this memory won't thrash the TLB.

  You might know that the accesses are likely to be sequential or

  that they aren't sequential but it's unlikely you'll ping-pong

  the mapping to have a short lifetime then it may be worth it to

  optimize allocation (avoid coming up with large pages) instead of

  getting the slight performance win of larger pages.

Setting this hint doesn't guarantee that you won't get huge pages, but it

means that we won't try quite as hard to get them.

NOTE: At the moment DMA_ATTR_ALLOC_SINGLE_PAGES is only implemented on ARM,

.. note:: At the moment DMA_ATTR_ALLOC_SINGLE_PAGES is only implemented on ARM,

	  though ARM64 patches will likely be posted soon.

DMA_ATTR_NO_WARN

So, this provides a way for drivers to avoid those error messages on calls

where allocation failures are not a problem, and shouldn't bother the logs.

NOTE: At the moment DMA_ATTR_NO_WARN is only implemented on PowerPC.

.. note:: At the moment DMA_ATTR_NO_WARN is only implemented on PowerPC.

DMA_ATTR_PRIVILEGED

------------------------------

-------------------

Some advanced peripherals such as remote processors and GPUs perform

accesses to DMA buffers in both privileged "supervisor" and unprivileged

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

The Linux IPMI Driver

			  ---------------------

			      Corey Minyard

			  <minyard@mvista.com>

			    <minyard@acm.org>

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

:Author: Corey Minyard <minyard@mvista.com> / <minyard@acm.org>

The Intelligent Platform Management Interface, or IPMI, is a

standard for controlling intelligent devices that monitor a system.

----------

The IPMI addressing works much like IP addresses, you have an overlay

to handle the different address types.  The overlay is:

to handle the different address types.  The overlay is::

  struct ipmi_addr

  {

The addr_type determines what the address really is.  The driver

currently understands two different types of addresses.

"System Interface" addresses are defined as:

"System Interface" addresses are defined as::

  struct ipmi_system_interface_addr

  {

IPMI_BMC_CHANNEL.

Messages that are destined to go out on the IPMB bus use the

IPMI_IPMB_ADDR_TYPE address type.  The format is

IPMI_IPMB_ADDR_TYPE address type.  The format is::

  struct ipmi_ipmb_addr

  {

Messages

--------

Messages are defined as:

Messages are defined as::

  struct ipmi_msg

  {

will have no place to put the message.

Messages coming up from the message handler in kernelland will come in

as:

as::

  struct ipmi_recv_msg

  {

Watching For Interfaces

^^^^^^^^^^^^^^^^^^^^^^^

When your code comes up, the IPMI driver may or may not have detected

if IPMI devices exist.  So you might have to defer your setup until

Creating the User

^^^^^^^^^^^^^^^^^

To use the message handler, you must first create a user using

ipmi_create_user.  The interface number specifies which SMI you want

Messaging

^^^^^^^^^

To send a message from kernel-land, the ipmi_request_settime() call does

pretty much all message handling.  Most of the parameter are

Events and Incoming Commands

^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The driver takes care of polling for IPMI events and receiving

commands (commands are messages that are not responses, they are

methods, depending on the system.

You can specify up to four interfaces on the module load line and

control some module parameters:

control some module parameters::

  modprobe ipmi_si.o type=<type1>,<type2>....

       ports=<port1>,<port2>... addrs=<addr1>,<addr2>...

obviously only useful for modules.

When compiled into the kernel, the parameters can be specified on the

kernel command line as:

kernel command line as::

  ipmi_si.type=<type1>,<type2>...

       ipmi_si.ports=<port1>,<port2>... ipmi_si.addrs=<addr1>,<addr2>...

interfaces can be added or removed after the kernel is up and running.

This is done using /sys/modules/ipmi_si/parameters/hotmod, which is a

write-only parameter.  You write a string to this interface.  The string

has the format:

has the format::

   <op1>[:op2[:op3...]]

The "op"s are:

The "op"s are::

   add|remove,kcs|bt|smic,mem|i/o,<address>[,<opt1>[,<opt2>[,...]]]

You can specify more than one interface on the line.  The "opt"s are:

You can specify more than one interface on the line.  The "opt"s are::

   rsp=<regspacing>

   rsi=<regsize>

   rsh=<regshift>

   irq=<irq>

   ipmb=<ipmb slave addr>

and these have the same meanings as discussed above.  Note that you

can also use this on the kernel command line for a more compact format

for specifying an interface.  Note that when removing an interface,

The SMBus driver allows up to 4 SMBus devices to be configured in the

system.  By default, the driver will only register with something it

finds in DMI or ACPI tables.  You can change this

at module load time (for a module) with:

at module load time (for a module) with::

  modprobe ipmi_ssif.o

	addr=<i2caddr1>[,<i2caddr2>[,...]]

driver what to use.

When compiled into the kernel, the addresses can be specified on the

kernel command line as:

kernel command line as::

  ipmb_ssif.addr=<i2caddr1>[,<i2caddr2>[...]]

	ipmi_ssif.adapter=<adapter1>[,<adapter2>[...]]

the address came from or the raw base device for the IPMI interface.

You can use the IPMI smi_watcher to catch the IPMI interfaces as they

come or go, and to grab the information, you can use the function

ipmi_get_smi_info(), which returns the following structure:

ipmi_get_smi_info(), which returns the following structure::

  struct ipmi_smi_info {

	enum ipmi_addr_src addr_src;

A watchdog timer is provided that implements the Linux-standard

watchdog timer interface.  It has three module parameters that can be

used to control it:

used to control it::

  modprobe ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type>

      preaction=<preaction type> preop=<preop type> start_now=x

if the CONFIG_WATCHDOG_NOWAYOUT option is enabled, or false if not.

When compiled into the kernel, the kernel command line is available

for configuring the watchdog:

for configuring the watchdog::

  ipmi_watchdog.timeout=<t> ipmi_watchdog.pretimeout=<t>

	ipmi_watchdog.action=<action type>

The field settings of the events are:

* Generator ID: 0x21 (kernel)

* EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format)

* Sensor Type: 0x20 (OS critical stop sensor)

* Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3)

* Event data 2: second byte of panic string

* Event data 3: third byte of panic string

See the IPMI spec for the details of the event layout.  This event is

always sent to the local management controller.  It will handle routing

the message to the right place

Other OEM events have the following format:

Record ID (bytes 0-1): Set by the SEL.

Record type (byte 2): 0xf0 (OEM non-timestamped)

byte 3: The slave address of the card saving the panic

byte 4: A sequence number (starting at zero)

* Record ID (bytes 0-1): Set by the SEL.

* Record type (byte 2): 0xf0 (OEM non-timestamped)

* byte 3: The slave address of the card saving the panic

* byte 4: A sequence number (starting at zero)

  The rest of the bytes (11 bytes) are the panic string.  If the panic string

  is longer than 11 bytes, multiple messages will be sent with increasing

  sequence numbers.