Merge tag 'pci-v4.2-changes' of git://git.kernel.org/pub/scm/linux/kernel/git/helgaas/pci

address is not directly useful to a driver; it must use ioremap() to map

address is not directly useful to a driver; it must use ioremap() to map

the space and produce a virtual address.

the space and produce a virtual address.

I/O devices use a third kind of address: a "bus address" or "DMA address".

I/O devices use a third kind of address: a "bus address".  If a device has

If a device has registers at an MMIO address, or if it performs DMA to read

registers at an MMIO address, or if it performs DMA to read or write system

or write system memory, the addresses used by the device are bus addresses.

memory, the addresses used by the device are bus addresses.  In some

In some systems, bus addresses are identical to CPU physical addresses, but

systems, bus addresses are identical to CPU physical addresses, but in

in general they are not.  IOMMUs and host bridges can produce arbitrary

general they are not.  IOMMUs and host bridges can produce arbitrary

mappings between physical and bus addresses.

mappings between physical and bus addresses.

From a device's point of view, DMA uses the bus address space, but it may

be restricted to a subset of that space.  For example, even if a system

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

               CPU                  CPU                  Bus

cannot because DMA doesn't go through the CPU virtual memory system.

cannot because DMA doesn't go through the CPU virtual memory system.

In some simple systems, the device can do DMA directly to physical address

In some simple systems, the device can do DMA directly to physical address

Y.  But in many others, there is IOMMU hardware that translates bus

Y.  But in many others, there is IOMMU hardware that translates DMA

addresses to physical addresses, e.g., it translates Z to Y.  This is part

addresses to physical addresses, e.g., it translates Z to Y.  This is part

of the reason for the DMA API: the driver can give a virtual address X to

of the reason for the DMA API: the driver can give a virtual address X to

an interface like dma_map_single(), which sets up any required IOMMU

an interface like dma_map_single(), which sets up any required IOMMU

mapping and returns the bus address Z.  The driver then tells the device to

mapping and returns the DMA address Z.  The driver then tells the device to

do DMA to Z, and the IOMMU maps it to the buffer at address Y in system

do DMA to Z, and the IOMMU maps it to the buffer at address Y in system

RAM.

RAM.

#include <linux/dma-mapping.h>

#include <linux/dma-mapping.h>

is in your driver, which provides the definition of dma_addr_t.  This type

is in your driver, which provides the definition of dma_addr_t.  This type

can hold any valid DMA or bus address for the platform and should be used

can hold any valid DMA address for the platform and should be used

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

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

			 What memory is DMA'able?

			 What memory is DMA'able?

  Think of "consistent" as "synchronous" or "coherent".

  Think of "consistent" as "synchronous" or "coherent".

  The current default is to return consistent memory in the low 32

  The current default is to return consistent memory in the low 32

  bits of the bus space.  However, for future compatibility you should

  bits of the DMA space.  However, for future compatibility you should

  set the consistent mask even if this default is fine for your

  set the consistent mask even if this default is fine for your

  driver.

  driver.

can use to access it from the CPU and dma_handle which you pass to the

can use to access it from the CPU and dma_handle which you pass to the

card.

card.

The CPU virtual address and the DMA bus address are both

The CPU virtual address and the DMA address are both

guaranteed to be aligned to the smallest PAGE_SIZE order which

guaranteed to be aligned to the smallest PAGE_SIZE order which

is greater than or equal to the requested size.  This invariant

is greater than or equal to the requested size.  This invariant

exists (for example) to guarantee that if you allocate a chunk

exists (for example) to guarantee that if you allocate a chunk

              dma_map_sg call.

              dma_map_sg call.

Every dma_map_{single,sg}() call should have its dma_unmap_{single,sg}()

Every dma_map_{single,sg}() call should have its dma_unmap_{single,sg}()

counterpart, because the bus address space is a shared resource and

counterpart, because the DMA address space is a shared resource and

you could render the machine unusable by consuming all bus addresses.

you could render the machine unusable by consuming all DMA addresses.

If you need to use the same streaming DMA region multiple times and touch

If you need to use the same streaming DMA region multiple times and touch

the data in between the DMA transfers, the buffer needs to be synced

the data in between the DMA transfers, the buffer needs to be synced

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

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

provides dma_addr_t and the interfaces described below.

provides dma_addr_t and the interfaces described below.

A dma_addr_t can hold any valid DMA or bus address for the platform.  It

A dma_addr_t can hold any valid DMA address for the platform.  It can be

can be given to a device to use as a DMA source or target.  A CPU cannot

given to a device to use as a DMA source or target.  A CPU cannot reference

reference a dma_addr_t directly because there may be translation between

a dma_addr_t directly because there may be translation between its physical

its physical address space and the bus address space.

address space and the DMA address space.

Part Ia - Using large DMA-coherent buffers

Part Ia - Using large DMA-coherent buffers

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

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

address space) or NULL if the allocation failed.

address space) or NULL if the allocation failed.

It also returns a <dma_handle> which may be cast to an unsigned integer the

It also returns a <dma_handle> which may be cast to an unsigned integer the

same width as the bus and given to the device as the bus address base of

same width as the bus and given to the device as the DMA address base of

the region.

the region.

Note: consistent memory can be expensive on some platforms, and the

Note: consistent memory can be expensive on some platforms, and the

		      enum dma_data_direction direction)

		      enum dma_data_direction 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 bus address of the memory.

device and returns the DMA address of the memory.

The direction for both APIs may be converted freely by casting.

The direction for both APIs may be converted freely by casting.

However the dma_ API uses a strongly typed enumerator for its

However the dma_ API uses a strongly typed enumerator for its

this API should be obtained from sources which guarantee it to be

this API should be obtained from sources which guarantee it to be

physically contiguous (like kmalloc).

physically contiguous (like kmalloc).

Further, the bus address of the memory must be within the

Further, the DMA address of the memory must be within the

dma_mask of the device (the dma_mask is a bit mask of the

dma_mask of the device (the dma_mask is a bit mask of the

addressable region for the device, i.e., if the bus address of

addressable region for the device, i.e., if the DMA address of

the memory ANDed with the dma_mask is still equal to the bus

the memory ANDed with the dma_mask is still equal to the DMA

address, then the device can perform DMA to the memory).  To

address, then the device can perform DMA to the memory).  To

ensure that the memory allocated by kmalloc is within the dma_mask,

ensure that the memory allocated by kmalloc is within the dma_mask,

the driver may specify various platform-dependent flags to restrict

the driver may specify various platform-dependent flags to restrict

the bus address range of the allocation (e.g., on x86, GFP_DMA

the DMA address range of the allocation (e.g., on x86, GFP_DMA

guarantees to be within the first 16MB of available bus addresses,

guarantees to be within the first 16MB of available DMA addresses,

as required by ISA devices).

as required by ISA devices).

Note also that the above constraints on physical contiguity and

Note also that the above constraints on physical contiguity and

dma_mask may not apply if the platform has an IOMMU (a device which

dma_mask may not apply if the platform has an IOMMU (a device which

maps an I/O bus address to a physical memory address).  However, to be

maps an I/O DMA address to a physical memory address).  However, to be

portable, device driver writers may *not* assume that such an IOMMU

portable, device driver writers may *not* assume that such an IOMMU

exists.

exists.

	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)

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

Returns: the number of DMA address 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

physically or virtually adjacent and an IOMMU maps them with a single

physically or virtually adjacent and an IOMMU maps them with a single

entry).

entry).

API.

API.

Note: <nents> must be the number you passed in, *not* the number of

Note: <nents> must be the number you passed in, *not* the number of

bus address entries returned.

DMA address entries returned.

void

void

dma_sync_single_for_cpu(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,

phys_addr is the CPU physical address to which the memory is currently

phys_addr is the CPU physical address to which the memory is currently

assigned (this will be ioremapped so the CPU can access the region).

assigned (this will be ioremapped so the CPU can access the region).

device_addr is the bus address the device needs to be programmed

device_addr is the DMA address the device needs to be programmed

with to actually address this memory (this will be handed out as the

with to actually address this memory (this will be handed out as the

dma_addr_t in dma_alloc_coherent()).

dma_addr_t in dma_alloc_coherent()).

* AppliedMicro X-Gene v1 PCIe MSI controller

Required properties:

- compatible: should be "apm,xgene1-msi" to identify

	      X-Gene v1 PCIe MSI controller block.

- msi-controller: indicates that this is X-Gene v1 PCIe MSI controller node

- reg: physical base address (0x79000000) and length (0x900000) for controller

       registers. These registers include the MSI termination address and data

       registers as well as the MSI interrupt status registers.

- reg-names: not required

- interrupts: A list of 16 interrupt outputs of the controller, starting from

	      interrupt number 0x10 to 0x1f.

- interrupt-names: not required

Each PCIe node needs to have property msi-parent that points to msi controller node

Examples:

SoC DTSI:

	+ MSI node:

	msi@79000000 {

		compatible = "apm,xgene1-msi";

		msi-controller;

		reg = <0x00 0x79000000 0x0 0x900000>;

		interrupts = 	<0x0 0x10 0x4>

				<0x0 0x11 0x4>

				<0x0 0x12 0x4>

				<0x0 0x13 0x4>

				<0x0 0x14 0x4>

				<0x0 0x15 0x4>

				<0x0 0x16 0x4>

				<0x0 0x17 0x4>

				<0x0 0x18 0x4>

				<0x0 0x19 0x4>

				<0x0 0x1a 0x4>

				<0x0 0x1b 0x4>

				<0x0 0x1c 0x4>

				<0x0 0x1d 0x4>

				<0x0 0x1e 0x4>

				<0x0 0x1f 0x4>;

	};

	+ PCIe controller node with msi-parent property pointing to MSI node:

	pcie0: pcie@1f2b0000 {

		status = "disabled";

		device_type = "pci";

		compatible = "apm,xgene-storm-pcie", "apm,xgene-pcie";

		#interrupt-cells = <1>;

		#size-cells = <2>;

		#address-cells = <3>;

		reg = < 0x00 0x1f2b0000 0x0 0x00010000   /* Controller registers */

			0xe0 0xd0000000 0x0 0x00040000>; /* PCI config space */

		reg-names = "csr", "cfg";

		ranges = <0x01000000 0x00 0x00000000 0xe0 0x10000000 0x00 0x00010000   /* io */

			  0x02000000 0x00 0x80000000 0xe1 0x80000000 0x00 0x80000000>; /* mem */

		dma-ranges = <0x42000000 0x80 0x00000000 0x80 0x00000000 0x00 0x80000000

			      0x42000000 0x00 0x00000000 0x00 0x00000000 0x80 0x00000000>;

		interrupt-map-mask = <0x0 0x0 0x0 0x7>;

		interrupt-map = <0x0 0x0 0x0 0x1 &gic 0x0 0xc2 0x1

				 0x0 0x0 0x0 0x2 &gic 0x0 0xc3 0x1

				 0x0 0x0 0x0 0x3 &gic 0x0 0xc4 0x1

				 0x0 0x0 0x0 0x4 &gic 0x0 0xc5 0x1>;

		dma-coherent;

		clocks = <&pcie0clk 0>;

		msi-parent= <&msi>;

	};

S:	Maintained

S:	Maintained

F:	drivers/pci/host/*spear*

F:	drivers/pci/host/*spear*

PCI MSI DRIVER FOR APPLIEDMICRO XGENE

M:	Duc Dang <dhdang@apm.com>

L:	linux-pci@vger.kernel.org

L:	linux-arm-kernel@lists.infradead.org

S:	Maintained

F:	Documentation/devicetree/bindings/pci/xgene-pci-msi.txt

F:	drivers/pci/host/pci-xgene-msi.c

PCMCIA SUBSYSTEM

PCMCIA SUBSYSTEM

P:	Linux PCMCIA Team

P:	Linux PCMCIA Team

L:	linux-pcmcia@lists.infradead.org

L:	linux-pcmcia@lists.infradead.org

/* implement the pci_ DMA API in terms of the generic device dma_ one */

/* implement the pci_ DMA API in terms of the generic device dma_ one */

#include <asm-generic/pci-dma-compat.h>

#include <asm-generic/pci-dma-compat.h>

static inline void pci_dma_burst_advice(struct pci_dev *pdev,

					enum pci_dma_burst_strategy *strat,

					unsigned long *strategy_parameter)

{

	unsigned long cacheline_size;

	u8 byte;

	pci_read_config_byte(pdev, PCI_CACHE_LINE_SIZE, &byte);

	if (byte == 0)

		cacheline_size = 1024;

	else

		cacheline_size = (int) byte * 4;

	*strat = PCI_DMA_BURST_BOUNDARY;

	*strategy_parameter = cacheline_size;

}

#endif

#endif

/* TODO: integrate with include/asm-generic/pci.h ? */

/* TODO: integrate with include/asm-generic/pci.h ? */