Merge branch 'master' into for-linus

#

#

# Top-level generic files

# Top-level generic files

#

#

tags

/tags

TAGS

/TAGS

linux

/linux

vmlinux

/vmlinux

vmlinuz

/vmlinuz

System.map

/System.map

Module.markers

/Module.markers

Module.symvers

/Module.symvers

#

# git files that we don't want to ignore even it they are dot-files

#

!.gitignore

!.gitignore

!.mailmap

!.mailmap

        James E.J. Bottomley <James.Bottomley@HansenPartnership.com>

        James E.J. Bottomley <James.Bottomley@HansenPartnership.com>

This document describes the DMA API.  For a more gentle introduction

This document describes the DMA API.  For a more gentle introduction

phrased in terms of the pci_ equivalents (and actual examples) see

of the API (and actual examples) see

Documentation/PCI/PCI-DMA-mapping.txt.

Documentation/DMA-API-HOWTO.txt.

This API is split into two pieces.  Part I describes the API and the

This API is split into two pieces.  Part I describes the API.  Part II

corresponding pci_ API.  Part II describes the extensions to the API

describes the extensions to the API for supporting non-consistent

for supporting non-consistent memory machines.  Unless you know that

memory machines.  Unless you know that your driver absolutely has to

your driver absolutely has to support non-consistent platforms (this

support non-consistent platforms (this is usually only legacy

is usually only legacy platforms) you should only use the API

platforms) you should only use the API described in part I.

described in part I.

Part I - pci_ and dma_ Equivalent API 

Part I - dma_ API

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

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

To get the pci_ API, you must #include <linux/pci.h>

To get the dma_ API, you must #include <linux/dma-mapping.h>

To get the dma_ API, you must #include <linux/dma-mapping.h>

void *

void *

dma_alloc_coherent(struct device *dev, size_t size,

dma_alloc_coherent(struct device *dev, size_t size,

			     dma_addr_t *dma_handle, gfp_t flag)

			     dma_addr_t *dma_handle, gfp_t flag)

void *

pci_alloc_consistent(struct pci_dev *dev, size_t size,

			     dma_addr_t *dma_handle)

Consistent memory is memory for which a write by either the device or

Consistent memory is memory for which a write by either the device or

the processor can immediately be read by the processor or device

the processor can immediately be read by the processor or device

The flag parameter (dma_alloc_coherent only) allows the caller to

The flag parameter (dma_alloc_coherent only) allows the caller to

specify the GFP_ flags (see kmalloc) for the allocation (the

specify the GFP_ flags (see kmalloc) for the allocation (the

implementation may choose to ignore flags that affect the location of

implementation may choose to ignore flags that affect the location of

the returned memory, like GFP_DMA).  For pci_alloc_consistent, you

the returned memory, like GFP_DMA).

must assume GFP_ATOMIC behaviour.

void

void

dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,

dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,

			   dma_addr_t dma_handle)

			   dma_addr_t dma_handle)

void

pci_free_consistent(struct pci_dev *dev, size_t size, void *cpu_addr,

			   dma_addr_t dma_handle)

Free the region of consistent memory you previously allocated.  dev,

Free the region of consistent memory you previously allocated.  dev,

size and dma_handle must all be the same as those passed into the

size and dma_handle must all be the same as those passed into the

	dma_pool_create(const char *name, struct device *dev,

	dma_pool_create(const char *name, struct device *dev,

			size_t size, size_t align, size_t alloc);

			size_t size, size_t align, size_t alloc);

	struct pci_pool *

	pci_pool_create(const char *name, struct pci_device *dev,

			size_t size, size_t align, size_t alloc);

The pool create() routines initialize a pool of dma-coherent buffers

The pool create() routines initialize a pool of dma-coherent buffers

for use with a given device.  It must be called in a context which

for use with a given device.  It must be called in a context which

can sleep.

can sleep.

	void *dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,

	void *dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,

			dma_addr_t *dma_handle);

			dma_addr_t *dma_handle);

	void *pci_pool_alloc(struct pci_pool *pool, gfp_t gfp_flags,

			dma_addr_t *dma_handle);

This allocates memory from the pool; the returned memory will meet the size

This allocates memory from the pool; the returned memory will meet the size

and alignment requirements specified at creation time.  Pass GFP_ATOMIC to

and alignment requirements specified at creation time.  Pass GFP_ATOMIC to

prevent blocking, or if it's permitted (not in_interrupt, not holding SMP locks),

prevent blocking, or if it's permitted (not in_interrupt, not holding SMP locks),

	void dma_pool_free(struct dma_pool *pool, void *vaddr,

	void dma_pool_free(struct dma_pool *pool, void *vaddr,

			dma_addr_t addr);

			dma_addr_t addr);

	void pci_pool_free(struct pci_pool *pool, void *vaddr,

			dma_addr_t addr);

This puts memory back into the pool.  The pool is what was passed to

This puts memory back into the pool.  The pool is what was passed to

the pool allocation routine; the cpu (vaddr) and dma addresses are what

the pool allocation routine; the cpu (vaddr) and dma addresses are what

were returned when that routine allocated the memory being freed.

were returned when that routine allocated the memory being freed.

	void dma_pool_destroy(struct dma_pool *pool);

	void dma_pool_destroy(struct dma_pool *pool);

	void pci_pool_destroy(struct pci_pool *pool);

The pool destroy() routines free the resources of the pool.  They must be

The pool destroy() routines free the resources of the pool.  They must be

called in a context which can sleep.  Make sure you've freed all allocated

called in a context which can sleep.  Make sure you've freed all allocated

memory back to the pool before you destroy it.

memory back to the pool before you destroy it.

int

int

dma_supported(struct device *dev, u64 mask)

dma_supported(struct device *dev, u64 mask)

int

pci_dma_supported(struct pci_dev *hwdev, u64 mask)

Checks to see if the device can support DMA to the memory described by

Checks to see if the device can support DMA to the memory described by

mask.

mask.

int

int

dma_set_mask(struct device *dev, u64 mask)

dma_set_mask(struct device *dev, u64 mask)

Checks to see if the mask is possible and updates the device

parameters if it is.

Returns: 0 if successful and a negative error if not.

int

int

pci_set_dma_mask(struct pci_device *dev, u64 mask)

dma_set_coherent_mask(struct device *dev, u64 mask)

Checks to see if the mask is possible and updates the device

Checks to see if the mask is possible and updates the device

parameters if it is.

parameters if it is.

dma_addr_t

dma_addr_t

dma_map_single(struct device *dev, void *cpu_addr, size_t size,

dma_map_single(struct device *dev, void *cpu_addr, size_t size,

		      enum dma_data_direction direction)

		      enum dma_data_direction direction)

dma_addr_t

pci_map_single(struct pci_dev *hwdev, void *cpu_addr, size_t size,

		      int direction)

Maps a piece of processor virtual memory so it can be accessed by the

Maps a piece of processor virtual memory so it can be accessed by the

device and returns the physical handle of the memory.

device and returns the physical handle of the memory.

However the dma_ API uses a strongly typed enumerator for its

However the dma_ API uses a strongly typed enumerator for its

direction:

direction:

DMA_NONE		= PCI_DMA_NONE		no direction (used for

DMA_NONE		no direction (used for debugging)

						debugging)

DMA_TO_DEVICE		data is going from the memory to the device

DMA_TO_DEVICE		= PCI_DMA_TODEVICE	data is going from the

DMA_FROM_DEVICE		data is coming from the device to the memory

						memory to the device

DMA_BIDIRECTIONAL	direction isn't known

DMA_FROM_DEVICE		= PCI_DMA_FROMDEVICE	data is coming from

						the device to the

						memory

DMA_BIDIRECTIONAL	= PCI_DMA_BIDIRECTIONAL	direction isn't known

Notes:  Not all memory regions in a machine can be mapped by this

Notes:  Not all memory regions in a machine can be mapped by this

API.  Further, regions that appear to be physically contiguous in

API.  Further, regions that appear to be physically contiguous in

void

void

dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size,

dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size,

		 enum dma_data_direction direction)

		 enum dma_data_direction direction)

void

pci_unmap_single(struct pci_dev *hwdev, dma_addr_t dma_addr,

		 size_t size, int direction)

Unmaps the region previously mapped.  All the parameters passed in

Unmaps the region previously mapped.  All the parameters passed in

must be identical to those passed in (and returned) by the mapping

must be identical to those passed in (and returned) by the mapping

dma_map_page(struct device *dev, struct page *page,

dma_map_page(struct device *dev, struct page *page,

		    unsigned long offset, size_t size,

		    unsigned long offset, size_t size,

		    enum dma_data_direction direction)

		    enum dma_data_direction direction)

dma_addr_t

pci_map_page(struct pci_dev *hwdev, struct page *page,

		    unsigned long offset, size_t size, int direction)

void

void

dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size,

dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size,

	       enum dma_data_direction direction)

	       enum dma_data_direction direction)

void

pci_unmap_page(struct pci_dev *hwdev, dma_addr_t dma_address,

	       size_t size, int direction)

API for mapping and unmapping for pages.  All the notes and warnings

API for mapping and unmapping for pages.  All the notes and warnings

for the other mapping APIs apply here.  Also, although the <offset>

for the other mapping APIs apply here.  Also, although the <offset>

int

int

dma_mapping_error(struct device *dev, dma_addr_t dma_addr)

dma_mapping_error(struct device *dev, dma_addr_t dma_addr)

int

pci_dma_mapping_error(struct pci_dev *hwdev, dma_addr_t dma_addr)

In some circumstances dma_map_single and dma_map_page will fail to create

In some circumstances dma_map_single and dma_map_page will fail to create

a mapping. A driver can check for these errors by testing the returned

a mapping. A driver can check for these errors by testing the returned

dma address with dma_mapping_error(). A non-zero return value means the mapping

dma address with dma_mapping_error(). A non-zero return value means the mapping

	int

	int

	dma_map_sg(struct device *dev, struct scatterlist *sg,

	dma_map_sg(struct device *dev, struct scatterlist *sg,

		int nents, enum dma_data_direction direction)

		int nents, enum dma_data_direction direction)

	int

	pci_map_sg(struct pci_dev *hwdev, struct scatterlist *sg,

		int nents, int direction)

Returns: the number of physical segments mapped (this may be shorter

Returns: the number of physical segments mapped (this may be shorter

than <nents> passed in if some elements of the scatter/gather list are

than <nents> passed in if some elements of the scatter/gather list are

	void

	void

	dma_unmap_sg(struct device *dev, struct scatterlist *sg,

	dma_unmap_sg(struct device *dev, struct scatterlist *sg,

		int nhwentries, enum dma_data_direction direction)

		int nhwentries, enum dma_data_direction direction)

	void

	pci_unmap_sg(struct pci_dev *hwdev, struct scatterlist *sg,

		int nents, int direction)

Unmap the previously mapped scatter/gather list.  All the parameters

Unmap the previously mapped scatter/gather list.  All the parameters

must be the same as those and passed in to the scatter/gather mapping

must be the same as those and passed in to the scatter/gather mapping

physical entries returned.

physical entries returned.

void

void

dma_sync_single(struct device *dev, dma_addr_t dma_handle, size_t size,

dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle, size_t size,

			enum dma_data_direction direction)

			enum dma_data_direction direction)

void

void

pci_dma_sync_single(struct pci_dev *hwdev, dma_addr_t dma_handle,

dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle, size_t size,

			   size_t size, int direction)

			   enum dma_data_direction direction)

void

void

dma_sync_sg(struct device *dev, struct scatterlist *sg, int nelems,

dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nelems,

		    enum dma_data_direction direction)

		    enum dma_data_direction direction)

void

void

pci_dma_sync_sg(struct pci_dev *hwdev, struct scatterlist *sg,

dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nelems,

		       int nelems, int direction)

		       enum dma_data_direction direction)

Synchronise a single contiguous or scatter/gather mapping.  All the

Synchronise a single contiguous or scatter/gather mapping for the cpu

parameters must be the same as those passed into the single mapping

and device. With the sync_sg API, all the parameters must be the same

API.

as those passed into the single mapping API. With the sync_single API,

you can use dma_handle and size parameters that aren't identical to

those passed into the single mapping API to do a partial sync.

Notes:  You must do this:

Notes:  You must do this:

Part II - Advanced dma_ usage

Part II - Advanced dma_ usage

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

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

Warning: These pieces of the DMA API have no PCI equivalent.  They

Warning: These pieces of the DMA API should not be used in the

should also not be used in the majority of cases, since they cater for

majority of cases, since they cater for unlikely corner cases that

unlikely corner cases that don't belong in usual drivers.

don't belong in usual drivers.

If you don't understand how cache line coherency works between a

If you don't understand how cache line coherency works between a

processor and an I/O device, you should not be using this part of the

processor and an I/O device, you should not be using this part of the

into the width returned by this call.  It will also always be a power

into the width returned by this call.  It will also always be a power

of two for easy alignment.

of two for easy alignment.

void

dma_sync_single_range(struct device *dev, dma_addr_t dma_handle,

		      unsigned long offset, size_t size,

		      enum dma_data_direction direction)

Does a partial sync, starting at offset and continuing for size.  You

must be careful to observe the cache alignment and width when doing

anything like this.  You must also be extra careful about accessing

memory you intend to sync partially.

void

void

dma_cache_sync(struct device *dev, void *vaddr, size_t size,

dma_cache_sync(struct device *dev, void *vaddr, size_t size,

	       enum dma_data_direction direction)

	       enum dma_data_direction direction)

				The ECC bytes must be placed immidiately after the data

				The ECC bytes must be placed immidiately after the data

				bytes in order to make the syndrome generator work. This

				bytes in order to make the syndrome generator work. This

				is contrary to the usual layout used by software ECC. The

				is contrary to the usual layout used by software ECC. The

				seperation of data and out of band area is not longer

				separation of data and out of band area is not longer

				possible. The nand driver code handles this layout and

				possible. The nand driver code handles this layout and

				the remaining free bytes in the oob area are managed by 

				the remaining free bytes in the oob area are managed by 

				the autoplacement code. Provide a matching oob-layout

				the autoplacement code. Provide a matching oob-layout

				bad blocks. They have factory marked good blocks. The marker pattern

				bad blocks. They have factory marked good blocks. The marker pattern

				is erased when the block is erased to be reused. So in case of

				is erased when the block is erased to be reused. So in case of

				powerloss before writing the pattern back to the chip this block 

				powerloss before writing the pattern back to the chip this block 

				would be lost and added to the bad blocks. Therefor we scan the 

				would be lost and added to the bad blocks. Therefore we scan the 

				chip(s) when we detect them the first time for good blocks and 

				chip(s) when we detect them the first time for good blocks and 

				store this information in a bad block table before erasing any 

				store this information in a bad block table before erasing any 

				of the blocks.

				of the blocks.

		manufacturers specifications. This applies similar to the spare area. 

		manufacturers specifications. This applies similar to the spare area. 

	</para>

	</para>

	<para>

	<para>

		Therefor NAND aware filesystems must either write in page size chunks

		Therefore NAND aware filesystems must either write in page size chunks

		or hold a writebuffer to collect smaller writes until they sum up to 

		or hold a writebuffer to collect smaller writes until they sum up to 

		pagesize. Available NAND aware filesystems: JFFS2, YAFFS. 		

		pagesize. Available NAND aware filesystems: JFFS2, YAFFS. 		

	</para>

	</para>

captured or output, applications can request frame skipping or

captured or output, applications can request frame skipping or

duplicating on the driver side. This is especially useful when using

duplicating on the driver side. This is especially useful when using

the &func-read; or &func-write;, which are not augmented by timestamps

the &func-read; or &func-write;, which are not augmented by timestamps

or sequence counters, and to avoid unneccessary data copying.</para>

or sequence counters, and to avoid unnecessary data copying.</para>

    <para>Finally these ioctls can be used to determine the number of

    <para>Finally these ioctls can be used to determine the number of

buffers used internally by a driver in read/write mode. For

buffers used internally by a driver in read/write mode. For

duplicating on the driver side. This is especially useful when using

duplicating on the driver side. This is especially useful when using

the <function>read()</function> or <function>write()</function>, which

the <function>read()</function> or <function>write()</function>, which

are not augmented by timestamps or sequence counters, and to avoid

are not augmented by timestamps or sequence counters, and to avoid

unneccessary data copying.</para>

unnecessary data copying.</para>

    <para>Further these ioctls can be used to determine the number of

    <para>Further these ioctls can be used to determine the number of

buffers used internally by a driver in read/write mode. For

buffers used internally by a driver in read/write mode. For