Dynamic DMA mapping
|
Dynamic DMA mapping
|
===================
|
===================
|
|
|
David S. Miller
|
David S. Miller
|
Richard Henderson
|
Richard Henderson
|
Jakub Jelinek
|
Jakub Jelinek
|
|
|
Most of the 64bit platforms have special hardware that translates bus
|
Most of the 64bit platforms have special hardware that translates bus
|
addresses (DMA addresses) into physical addresses. This is similar to
|
addresses (DMA addresses) into physical addresses. This is similar to
|
how page tables and/or a TLB translates virtual addresses to physical
|
how page tables and/or a TLB translates virtual addresses to physical
|
addresses on a CPU. This is needed so that e.g. PCI devices can
|
addresses on a CPU. This is needed so that e.g. PCI devices can
|
access with a Single Address Cycle (32bit DMA address) any page in the
|
access with a Single Address Cycle (32bit DMA address) any page in the
|
64bit physical address space. Previously in Linux those 64bit
|
64bit physical address space. Previously in Linux those 64bit
|
platforms had to set artificial limits on the maximum RAM size in the
|
platforms had to set artificial limits on the maximum RAM size in the
|
system, so that the virt_to_bus() static scheme works (the DMA address
|
system, so that the virt_to_bus() static scheme works (the DMA address
|
translation tables were simply filled on bootup to map each bus
|
translation tables were simply filled on bootup to map each bus
|
address to the physical page __pa(bus_to_virt())).
|
address to the physical page __pa(bus_to_virt())).
|
|
|
So that Linux can use the dynamic DMA mapping, it needs some help from the
|
So that Linux can use the dynamic DMA mapping, it needs some help from the
|
drivers, namely it has to take into account that DMA addresses should be
|
drivers, namely it has to take into account that DMA addresses should be
|
mapped only for the time they are actually used and unmapped after the DMA
|
mapped only for the time they are actually used and unmapped after the DMA
|
transfer.
|
transfer.
|
|
|
The following API will work of course even on platforms where no such
|
The following API will work of course even on platforms where no such
|
hardware exists, see e.g. include/asm-i386/pci.h for how it is implemented on
|
hardware exists, see e.g. include/asm-i386/pci.h for how it is implemented on
|
top of the virt_to_bus interface.
|
top of the virt_to_bus interface.
|
|
|
First of all, you should make sure
|
First of all, you should make sure
|
|
|
#include
|
#include
|
|
|
is in your driver. This file will obtain for you the definition of the
|
is in your driver. This file will obtain for you the definition of the
|
dma_addr_t (which can hold any valid DMA address for the platform)
|
dma_addr_t (which can hold any valid DMA address for the platform)
|
type which should be used everywhere you hold a DMA (bus) address
|
type which should be used everywhere you hold a DMA (bus) address
|
returned from the DMA mapping functions.
|
returned from the DMA mapping functions.
|
|
|
What memory is DMA'able?
|
What memory is DMA'able?
|
|
|
The first piece of information you must know is what kernel memory can
|
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
|
be used with the DMA mapping facilities. There has been an unwritten
|
set of rules regarding this, and this text is an attempt to finally
|
set of rules regarding this, and this text is an attempt to finally
|
write them down.
|
write them down.
|
|
|
If you acquired your memory via the page allocator
|
If you acquired your memory via the page allocator
|
(i.e. __get_free_page*()) or the generic memory allocators
|
(i.e. __get_free_page*()) or the generic memory allocators
|
(i.e. kmalloc() or kmem_cache_alloc()) then you may DMA to/from
|
(i.e. kmalloc() or kmem_cache_alloc()) then you may DMA to/from
|
that memory using the addresses returned from those routines.
|
that memory using the addresses returned from those routines.
|
|
|
This means specifically that you may _not_ use the memory/addresses
|
This means specifically that you may _not_ use the memory/addresses
|
returned from vmalloc() for DMA. It is possible to DMA to the
|
returned from vmalloc() for DMA. It is possible to DMA to the
|
_underlying_ memory mapped into a vmalloc() area, but this requires
|
_underlying_ memory mapped into a vmalloc() area, but this requires
|
walking page tables to get the physical addresses, and then
|
walking page tables to get the physical addresses, and then
|
translating each of those pages back to a kernel address using
|
translating each of those pages back to a kernel address using
|
something like __va(). [ EDIT: Update this when we integrate
|
something like __va(). [ EDIT: Update this when we integrate
|
Gerd Knorr's generic code which does this. ]
|
Gerd Knorr's generic code which does this. ]
|
|
|
This rule also means that you may not use kernel image addresses
|
This rule also means that you may not use kernel image addresses
|
(ie. items in the kernel's data/text/bss segment, or your driver's)
|
(ie. items in the kernel's data/text/bss segment, or your driver's)
|
nor may you use kernel stack addresses for DMA. Both of these items
|
nor may you use kernel stack addresses for DMA. Both of these items
|
might be mapped somewhere entirely different than the rest of physical
|
might be mapped somewhere entirely different than the rest of physical
|
memory.
|
memory.
|
|
|
Also, this means that you cannot take the return of a kmap()
|
Also, this means that you cannot take the return of a kmap()
|
call and DMA to/from that. This is similar to vmalloc().
|
call and DMA to/from that. This is similar to vmalloc().
|
|
|
What about block I/O and networking buffers? The block I/O and
|
What about block I/O and networking buffers? The block I/O and
|
networking subsystems make sure that the buffers they use are valid
|
networking subsystems make sure that the buffers they use are valid
|
for you to DMA from/to.
|
for you to DMA from/to.
|
|
|
DMA addressing limitations
|
DMA addressing limitations
|
|
|
Does your device have any DMA addressing limitations? For example, is
|
Does your device have any DMA addressing limitations? For example, is
|
your device only capable of driving the low order 24-bits of address
|
your device only capable of driving the low order 24-bits of address
|
on the PCI bus for SAC DMA transfers? If so, you need to inform the
|
on the PCI bus for SAC DMA transfers? If so, you need to inform the
|
PCI layer of this fact.
|
PCI layer of this fact.
|
|
|
By default, the kernel assumes that your device can address the full
|
By default, the kernel assumes that your device can address the full
|
32-bits in a SAC cycle. For a 64-bit DAC capable device, this needs
|
32-bits in a SAC cycle. For a 64-bit DAC capable device, this needs
|
to be increased. And for a device with limitations, as discussed in
|
to be increased. And for a device with limitations, as discussed in
|
the previous paragraph, it needs to be decreased.
|
the previous paragraph, it needs to be decreased.
|
|
|
For correct operation, you must interrogate the PCI layer in your
|
For correct operation, you must interrogate the PCI layer in your
|
device probe routine to see if the PCI controller on the machine can
|
device probe routine to see if the PCI controller on the machine can
|
properly support the DMA addressing limitation your device has. It is
|
properly support the DMA addressing limitation your device has. It is
|
good style to do this even if your device holds the default setting,
|
good style to do this even if your device holds the default setting,
|
because this shows that you did think about these issues wrt. your
|
because this shows that you did think about these issues wrt. your
|
device.
|
device.
|
|
|
The query is performed via a call to pci_set_dma_mask():
|
The query is performed via a call to pci_set_dma_mask():
|
|
|
int pci_set_dma_mask(struct pci_dev *pdev, u64 device_mask);
|
int pci_set_dma_mask(struct pci_dev *pdev, u64 device_mask);
|
|
|
Here, pdev is a pointer to the PCI device struct of your device, and
|
Here, pdev is a pointer to the PCI device struct of your device, and
|
device_mask is a bit mask describing which bits of a PCI address your
|
device_mask is a bit mask describing which bits of a PCI address your
|
device supports. It returns zero if your card can perform DMA
|
device supports. It returns zero if your card can perform DMA
|
properly on the machine given the address mask you provided.
|
properly on the machine given the address mask you provided.
|
|
|
If it returns non-zero, your device can not perform DMA properly on
|
If it returns non-zero, your device can not perform DMA properly on
|
this platform, and attempting to do so will result in undefined
|
this platform, and attempting to do so will result in undefined
|
behavior. You must either use a different mask, or not use DMA.
|
behavior. You must either use a different mask, or not use DMA.
|
|
|
This means that in the failure case, you have three options:
|
This means that in the failure case, you have three options:
|
|
|
1) Use another DMA mask, if possible (see below).
|
1) Use another DMA mask, if possible (see below).
|
2) Use some non-DMA mode for data transfer, if possible.
|
2) Use some non-DMA mode for data transfer, if possible.
|
3) Ignore this device and do not initialize it.
|
3) Ignore this device and do not initialize it.
|
|
|
It is recommended that your driver print a kernel KERN_WARNING message
|
It is recommended that your driver print a kernel KERN_WARNING message
|
when you end up performing either #2 or #3. In this manner, if a user
|
when you end up performing either #2 or #3. In this manner, if a user
|
of your driver reports that performance is bad or that the device is not
|
of your driver reports that performance is bad or that the device is not
|
even detected, you can ask them for the kernel messages to find out
|
even detected, you can ask them for the kernel messages to find out
|
exactly why.
|
exactly why.
|
|
|
The standard 32-bit addressing PCI device would do something like
|
The standard 32-bit addressing PCI device would do something like
|
this:
|
this:
|
|
|
if (pci_set_dma_mask(pdev, 0xffffffff)) {
|
if (pci_set_dma_mask(pdev, 0xffffffff)) {
|
printk(KERN_WARNING
|
printk(KERN_WARNING
|
"mydev: No suitable DMA available.\n");
|
"mydev: No suitable DMA available.\n");
|
goto ignore_this_device;
|
goto ignore_this_device;
|
}
|
}
|
|
|
Another common scenario is a 64-bit capable device. The approach
|
Another common scenario is a 64-bit capable device. The approach
|
here is to try for 64-bit DAC addressing, but back down to a
|
here is to try for 64-bit DAC addressing, but back down to a
|
32-bit mask should that fail. The PCI platform code may fail the
|
32-bit mask should that fail. The PCI platform code may fail the
|
64-bit mask not because the platform is not capable of 64-bit
|
64-bit mask not because the platform is not capable of 64-bit
|
addressing. Rather, it may fail in this case simply because
|
addressing. Rather, it may fail in this case simply because
|
32-bit SAC addressing is done more efficiently than DAC addressing.
|
32-bit SAC addressing is done more efficiently than DAC addressing.
|
Sparc64 is one platform which behaves in this way.
|
Sparc64 is one platform which behaves in this way.
|
|
|
Here is how you would handle a 64-bit capable device which can drive
|
Here is how you would handle a 64-bit capable device which can drive
|
all 64-bits during a DAC cycle:
|
all 64-bits during a DAC cycle:
|
|
|
int using_dac;
|
int using_dac;
|
|
|
if (!pci_set_dma_mask(pdev, 0xffffffffffffffff)) {
|
if (!pci_set_dma_mask(pdev, 0xffffffffffffffff)) {
|
using_dac = 1;
|
using_dac = 1;
|
} else if (!pci_set_dma_mask(pdev, 0xffffffff)) {
|
} else if (!pci_set_dma_mask(pdev, 0xffffffff)) {
|
using_dac = 0;
|
using_dac = 0;
|
} else {
|
} else {
|
printk(KERN_WARNING
|
printk(KERN_WARNING
|
"mydev: No suitable DMA available.\n");
|
"mydev: No suitable DMA available.\n");
|
goto ignore_this_device;
|
goto ignore_this_device;
|
}
|
}
|
|
|
If your 64-bit device is going to be an enormous consumer of DMA
|
If your 64-bit device is going to be an enormous consumer of DMA
|
mappings, this can be problematic since the DMA mappings are a
|
mappings, this can be problematic since the DMA mappings are a
|
finite resource on many platforms. Please see the "DAC Addressing
|
finite resource on many platforms. Please see the "DAC Addressing
|
for Address Space Hungry Devices" section near the end of this
|
for Address Space Hungry Devices" section near the end of this
|
document for how to handle this case.
|
document for how to handle this case.
|
|
|
Finally, if your device can only drive the low 24-bits of
|
Finally, if your device can only drive the low 24-bits of
|
address during PCI bus mastering you might do something like:
|
address during PCI bus mastering you might do something like:
|
|
|
if (pci_set_dma_mask(pdev, 0x00ffffff)) {
|
if (pci_set_dma_mask(pdev, 0x00ffffff)) {
|
printk(KERN_WARNING
|
printk(KERN_WARNING
|
"mydev: 24-bit DMA addressing not available.\n");
|
"mydev: 24-bit DMA addressing not available.\n");
|
goto ignore_this_device;
|
goto ignore_this_device;
|
}
|
}
|
|
|
When pci_set_dma_mask() is successful, and returns zero, the PCI layer
|
When pci_set_dma_mask() is successful, and returns zero, the PCI layer
|
saves away this mask you have provided. The PCI layer will use this
|
saves away this mask you have provided. The PCI layer will use this
|
information later when you make DMA mappings.
|
information later when you make DMA mappings.
|
|
|
There is a case which we are aware of at this time, which is worth
|
There is a case which we are aware of at this time, which is worth
|
mentioning in this documentation. If your device supports multiple
|
mentioning in this documentation. If your device supports multiple
|
functions (for example a sound card provides playback and record
|
functions (for example a sound card provides playback and record
|
functions) and the various different functions have _different_
|
functions) and the various different functions have _different_
|
DMA addressing limitations, you may wish to probe each mask and
|
DMA addressing limitations, you may wish to probe each mask and
|
only provide the functionality which the machine can handle. It
|
only provide the functionality which the machine can handle. It
|
is important that the last call to pci_set_dma_mask() be for the
|
is important that the last call to pci_set_dma_mask() be for the
|
most specific mask.
|
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 0xffffffff
|
#define PLAYBACK_ADDRESS_BITS 0xffffffff
|
#define RECORD_ADDRESS_BITS 0x00ffffff
|
#define RECORD_ADDRESS_BITS 0x00ffffff
|
|
|
struct my_sound_card *card;
|
struct my_sound_card *card;
|
struct pci_dev *pdev;
|
struct pci_dev *pdev;
|
|
|
...
|
...
|
if (pci_set_dma_mask(pdev, PLAYBACK_ADDRESS_BITS)) {
|
if (pci_set_dma_mask(pdev, PLAYBACK_ADDRESS_BITS)) {
|
card->playback_enabled = 1;
|
card->playback_enabled = 1;
|
} else {
|
} else {
|
card->playback_enabled = 0;
|
card->playback_enabled = 0;
|
printk(KERN_WARN "%s: Playback disabled due to DMA limitations.\n",
|
printk(KERN_WARN "%s: Playback disabled due to DMA limitations.\n",
|
card->name);
|
card->name);
|
}
|
}
|
if (pci_set_dma_mask(pdev, RECORD_ADDRESS_BITS)) {
|
if (pci_set_dma_mask(pdev, RECORD_ADDRESS_BITS)) {
|
card->record_enabled = 1;
|
card->record_enabled = 1;
|
} else {
|
} else {
|
card->record_enabled = 0;
|
card->record_enabled = 0;
|
printk(KERN_WARN "%s: Record disabled due to DMA limitations.\n",
|
printk(KERN_WARN "%s: Record disabled due to DMA limitations.\n",
|
card->name);
|
card->name);
|
}
|
}
|
|
|
A sound card was used as an example here because this genre of PCI
|
A sound card was used as an example here because this genre of PCI
|
devices seems to be littered with ISA chips given a PCI front end,
|
devices seems to be littered with ISA chips given a PCI front end,
|
and thus retaining the 16MB DMA addressing limitations of ISA.
|
and thus retaining the 16MB DMA addressing limitations of ISA.
|
|
|
Types of DMA mappings
|
Types of DMA mappings
|
|
|
There are two types of DMA mappings:
|
There are two types of DMA mappings:
|
|
|
- Consistent DMA mappings which are usually mapped at driver
|
- Consistent DMA mappings which are usually mapped at driver
|
initialization, unmapped at the end and for which the hardware should
|
initialization, unmapped at the end and for which the hardware should
|
guarantee that the device and the CPU can access the data
|
guarantee that the device and the CPU can access the data
|
in parallel and will see updates made by each other without any
|
in parallel and will see updates made by each other without any
|
explicit software flushing.
|
explicit software flushing.
|
|
|
Think of "consistent" as "synchronous" or "coherent".
|
Think of "consistent" as "synchronous" or "coherent".
|
|
|
Consistent DMA mappings are always SAC addressable. That is
|
Consistent DMA mappings are always SAC addressable. That is
|
to say, consistent DMA addresses given to the driver will always
|
to say, consistent DMA addresses given to the driver will always
|
be in the low 32-bits of the PCI bus space.
|
be in the low 32-bits of the PCI bus space.
|
|
|
Good examples of what to use consistent mappings for are:
|
Good examples of what to use consistent mappings for are:
|
|
|
- Network card DMA ring descriptors.
|
- Network card DMA ring descriptors.
|
- SCSI adapter mailbox command data structures.
|
- SCSI adapter mailbox command data structures.
|
- Device firmware microcode executed out of
|
- Device firmware microcode executed out of
|
main memory.
|
main memory.
|
|
|
The invariant these examples all require is that any CPU store
|
The invariant these examples all require is that any CPU store
|
to memory is immediately visible to the device, and vice
|
to memory is immediately visible to the device, and vice
|
versa. Consistent mappings guarantee this.
|
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
|
proper memory barriers. The CPU may reorder stores to
|
consistent memory just as it may normal memory. Example:
|
consistent memory just as it may normal memory. Example:
|
if it is important for the device to see the first word
|
if it is important for the device to see the first word
|
of a descriptor updated before the second, you must do
|
of a descriptor updated before the second, you must do
|
something like:
|
something like:
|
|
|
desc->word0 = address;
|
desc->word0 = address;
|
wmb();
|
wmb();
|
desc->word1 = DESC_VALID;
|
desc->word1 = DESC_VALID;
|
|
|
in order to get correct behavior on all platforms.
|
in order to get correct behavior on all platforms.
|
|
|
- Streaming DMA mappings which are usually mapped for one DMA transfer,
|
- Streaming DMA mappings which are usually mapped for one DMA transfer,
|
unmapped right after it (unless you use pci_dma_sync below) and for which
|
unmapped right after it (unless you use pci_dma_sync below) and for which
|
hardware can optimize for sequential accesses.
|
hardware can optimize for sequential accesses.
|
|
|
This of "streaming" as "asynchronous" or "outside the coherency
|
This of "streaming" as "asynchronous" or "outside the coherency
|
domain".
|
domain".
|
|
|
Good examples of what to use streaming mappings for are:
|
Good examples of what to use streaming mappings for are:
|
|
|
- Networking buffers transmitted/received by a device.
|
- Networking buffers transmitted/received by a device.
|
- Filesystem buffers written/read by a SCSI device.
|
- Filesystem buffers written/read by a SCSI device.
|
|
|
The interfaces for using this type of mapping were designed in
|
The interfaces for using this type of mapping were designed in
|
such a way that an implementation can make whatever performance
|
such a way that an implementation can make whatever performance
|
optimizations the hardware allows. To this end, when using
|
optimizations the hardware allows. To this end, when using
|
such mappings you must be explicit about what you want to happen.
|
such mappings you must be explicit about what you want to happen.
|
|
|
Neither type of DMA mapping has alignment restrictions that come
|
Neither type of DMA mapping has alignment restrictions that come
|
from PCI, although some devices may have such restrictions.
|
from PCI, although some devices may have such restrictions.
|
|
|
Using Consistent DMA mappings.
|
Using Consistent DMA mappings.
|
|
|
To allocate and map large (PAGE_SIZE or so) consistent DMA regions,
|
To allocate and map large (PAGE_SIZE or so) consistent DMA regions,
|
you should do:
|
you should do:
|
|
|
dma_addr_t dma_handle;
|
dma_addr_t dma_handle;
|
|
|
cpu_addr = pci_alloc_consistent(dev, size, &dma_handle);
|
cpu_addr = pci_alloc_consistent(dev, size, &dma_handle);
|
|
|
where dev is a struct pci_dev *. You should pass NULL for PCI like buses
|
where dev is a struct pci_dev *. You should pass NULL for PCI like buses
|
where devices don't have struct pci_dev (like ISA, EISA). This may be
|
where devices don't have struct pci_dev (like ISA, EISA). This may be
|
called in interrupt context.
|
called in interrupt context.
|
|
|
This argument is needed because the DMA translations may be bus
|
This argument is needed because the DMA translations may be bus
|
specific (and often is private to the bus which the device is attached
|
specific (and often is private to the bus which the device is attached
|
to).
|
to).
|
|
|
Size is the length of the region you want to allocate, in bytes.
|
Size is the length of the region you want to allocate, in bytes.
|
|
|
This routine will allocate RAM for that region, so it acts similarly to
|
This routine will allocate RAM for that region, so it acts similarly to
|
__get_free_pages (but takes size instead of a page order). If your
|
__get_free_pages (but takes size instead of a page order). If your
|
driver needs regions sized smaller than a page, you may prefer using
|
driver needs regions sized smaller than a page, you may prefer using
|
the pci_pool interface, described below.
|
the pci_pool interface, described below.
|
|
|
The consistent DMA mapping interfaces, for non-NULL dev, will always
|
The consistent DMA mapping interfaces, for non-NULL dev, will always
|
return a DMA address which is SAC (Single Address Cycle) addressable.
|
return a DMA address which is SAC (Single Address Cycle) addressable.
|
Even if the device indicates (via PCI dma mask) that it may address
|
Even if the device indicates (via PCI dma mask) that it may address
|
the upper 32-bits and thus perform DAC cycles, consistent allocation
|
the upper 32-bits and thus perform DAC cycles, consistent allocation
|
will still only return 32-bit PCI addresses for DMA. This is true
|
will still only return 32-bit PCI addresses for DMA. This is true
|
of the pci_pool interface as well.
|
of the pci_pool interface as well.
|
|
|
In fact, as mentioned above, all consistent memory provided by the
|
In fact, as mentioned above, all consistent memory provided by the
|
kernel DMA APIs are always SAC addressable.
|
kernel DMA APIs are always SAC addressable.
|
|
|
pci_alloc_consistent returns two values: the virtual address which you
|
pci_alloc_consistent returns two values: the virtual address which you
|
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 return address and the DMA bus master address are both
|
The cpu return address and the DMA bus master 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
|
which is smaller than or equal to 64 kilobytes, the extent of the
|
which is smaller than or equal to 64 kilobytes, the extent of the
|
buffer you receive will not cross a 64K boundary.
|
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:
|
|
|
pci_free_consistent(dev, size, cpu_addr, dma_handle);
|
pci_free_consistent(dev, size, cpu_addr, dma_handle);
|
|
|
where dev, size are the same as in the above call and cpu_addr and
|
where dev, size are the same as in the above call and cpu_addr and
|
dma_handle are the values pci_alloc_consistent returned to you.
|
dma_handle are the values pci_alloc_consistent returned to you.
|
This function may not be called in interrupt context.
|
This function may not be called in interrupt context.
|
|
|
If your driver needs lots of smaller memory regions, you can write
|
If your driver needs lots of smaller memory regions, you can write
|
custom code to subdivide pages returned by pci_alloc_consistent,
|
custom code to subdivide pages returned by pci_alloc_consistent,
|
or you can use the pci_pool API to do that. A pci_pool is like
|
or you can use the pci_pool API to do that. A pci_pool is like
|
a kmem_cache, but it uses pci_alloc_consistent not __get_free_pages.
|
a kmem_cache, but it uses pci_alloc_consistent not __get_free_pages.
|
Also, it understands common hardware constraints for alignment,
|
Also, it understands common hardware constraints for alignment,
|
like queue heads needing to be aligned on N byte boundaries.
|
like queue heads needing to be aligned on N byte boundaries.
|
|
|
Create a pci_pool like this:
|
Create a pci_pool like this:
|
|
|
struct pci_pool *pool;
|
struct pci_pool *pool;
|
|
|
pool = pci_pool_create(name, dev, size, align, alloc, flags);
|
pool = pci_pool_create(name, dev, size, align, alloc, flags);
|
|
|
The "name" is for diagnostics (like a kmem_cache name); dev and size
|
The "name" is for diagnostics (like a kmem_cache name); dev and size
|
are as above. The device's hardware alignment requirement for this
|
are as above. The device's hardware alignment requirement for this
|
type of data is "align" (which is expressed in bytes, and must be a
|
type of data is "align" (which is expressed in bytes, and must be a
|
power of two). The flags are SLAB_ flags as you'd pass to
|
power of two). The flags are SLAB_ flags as you'd pass to
|
kmem_cache_create. Not all flags are understood, but SLAB_POISON may
|
kmem_cache_create. Not all flags are understood, but SLAB_POISON may
|
help you find driver bugs. If you call this in a non- sleeping
|
help you find driver bugs. If you call this in a non- sleeping
|
context (f.e. in_interrupt is true or while holding SMP locks), pass
|
context (f.e. in_interrupt is true or while holding SMP locks), pass
|
SLAB_ATOMIC. If your device has no boundary crossing restrictions,
|
SLAB_ATOMIC. If your device has no boundary crossing restrictions,
|
pass 0 for alloc; passing 4096 says memory allocated from this pool
|
pass 0 for alloc; passing 4096 says memory allocated from this pool
|
must not cross 4KByte boundaries (but at that time it may be better to
|
must not cross 4KByte boundaries (but at that time it may be better to
|
go for pci_alloc_consistent directly instead).
|
go for pci_alloc_consistent directly instead).
|
|
|
Allocate memory from a pci pool like this:
|
Allocate memory from a pci pool like this:
|
|
|
cpu_addr = pci_pool_alloc(pool, flags, &dma_handle);
|
cpu_addr = pci_pool_alloc(pool, flags, &dma_handle);
|
|
|
flags are SLAB_KERNEL if blocking is permitted (not in_interrupt nor
|
flags are SLAB_KERNEL if blocking is permitted (not in_interrupt nor
|
holding SMP locks), SLAB_ATOMIC otherwise. Like pci_alloc_consistent,
|
holding SMP locks), SLAB_ATOMIC otherwise. Like pci_alloc_consistent,
|
this returns two values, cpu_addr and dma_handle.
|
this returns two values, cpu_addr and dma_handle.
|
|
|
Free memory that was allocated from a pci_pool like this:
|
Free memory that was allocated from a pci_pool like this:
|
|
|
pci_pool_free(pool, cpu_addr, dma_handle);
|
pci_pool_free(pool, cpu_addr, dma_handle);
|
|
|
where pool is what you passed to pci_pool_alloc, and cpu_addr and
|
where pool is what you passed to pci_pool_alloc, and cpu_addr and
|
dma_handle are the values pci_pool_alloc returned. This function
|
dma_handle are the values pci_pool_alloc returned. This function
|
may be called in interrupt context.
|
may be called in interrupt context.
|
|
|
Destroy a pci_pool by calling:
|
Destroy a pci_pool by calling:
|
|
|
pci_pool_destroy(pool);
|
pci_pool_destroy(pool);
|
|
|
Make sure you've called pci_pool_free for all memory allocated
|
Make sure you've called pci_pool_free for all memory allocated
|
from a pool before you destroy the pool. This function may not
|
from a pool before you destroy the pool. This function may not
|
be called in interrupt context.
|
be called in interrupt context.
|
|
|
DMA Direction
|
DMA Direction
|
|
|
The interfaces described in subsequent portions of this document
|
The interfaces described in subsequent portions of this document
|
take a DMA direction argument, which is an integer and takes on
|
take a DMA direction argument, which is an integer and takes on
|
one of the following values:
|
one of the following values:
|
|
|
PCI_DMA_BIDIRECTIONAL
|
PCI_DMA_BIDIRECTIONAL
|
PCI_DMA_TODEVICE
|
PCI_DMA_TODEVICE
|
PCI_DMA_FROMDEVICE
|
PCI_DMA_FROMDEVICE
|
PCI_DMA_NONE
|
PCI_DMA_NONE
|
|
|
One should provide the exact DMA direction if you know it.
|
One should provide the exact DMA direction if you know it.
|
|
|
PCI_DMA_TODEVICE means "from main memory to the PCI device"
|
PCI_DMA_TODEVICE means "from main memory to the PCI device"
|
PCI_DMA_FROMDEVICE means "from the PCI device to main memory"
|
PCI_DMA_FROMDEVICE means "from the PCI device to main memory"
|
It is the direction in which the data moves during the DMA
|
It is the direction in which the data moves during the DMA
|
transfer.
|
transfer.
|
|
|
You are _strongly_ encouraged to specify this as precisely
|
You are _strongly_ encouraged to specify this as precisely
|
as you possibly can.
|
as you possibly can.
|
|
|
If you absolutely cannot know the direction of the DMA transfer,
|
If you absolutely cannot know the direction of the DMA transfer,
|
specify PCI_DMA_BIDIRECTIONAL. It means that the DMA can go in
|
specify PCI_DMA_BIDIRECTIONAL. It means that the DMA can go in
|
either direction. The platform guarantees that you may legally
|
either direction. The platform guarantees that you may legally
|
specify this, and that it will work, but this may be at the
|
specify this, and that it will work, but this may be at the
|
cost of performance for example.
|
cost of performance for example.
|
|
|
The value PCI_DMA_NONE is to be used for debugging. One can
|
The value PCI_DMA_NONE is to be used for debugging. One can
|
hold this in a data structure before you come to know the
|
hold this in a data structure before you come to know the
|
precise direction, and this will help catch cases where your
|
precise direction, and this will help catch cases where your
|
direction tracking logic has failed to set things up properly.
|
direction tracking logic has failed to set things up properly.
|
|
|
Another advantage of specifying this value precisely (outside of
|
Another advantage of specifying this value precisely (outside of
|
potential platform-specific optimizations of such) is for debugging.
|
potential platform-specific optimizations of such) is for debugging.
|
Some platforms actually have a write permission boolean which DMA
|
Some platforms actually have a write permission boolean which DMA
|
mappings can be marked with, much like page protections in the user
|
mappings can be marked with, much like page protections in the user
|
program address space. Such platforms can and do report errors in the
|
program address space. Such platforms can and do report errors in the
|
kernel logs when the PCI controller hardware detects violation of the
|
kernel logs when the PCI controller hardware detects violation of the
|
permission setting.
|
permission setting.
|
|
|
Only streaming mappings specify a direction, consistent mappings
|
Only streaming mappings specify a direction, consistent mappings
|
implicitly have a direction attribute setting of
|
implicitly have a direction attribute setting of
|
PCI_DMA_BIDIRECTIONAL.
|
PCI_DMA_BIDIRECTIONAL.
|
|
|
The SCSI subsystem provides mechanisms for you to easily obtain
|
The SCSI subsystem provides mechanisms for you to easily obtain
|
the direction to use, in the SCSI command:
|
the direction to use, in the SCSI command:
|
|
|
scsi_to_pci_dma_dir(SCSI_DIRECTION)
|
scsi_to_pci_dma_dir(SCSI_DIRECTION)
|
|
|
Where SCSI_DIRECTION is obtained from the 'sc_data_direction'
|
Where SCSI_DIRECTION is obtained from the 'sc_data_direction'
|
member of the SCSI command your driver is working on. The
|
member of the SCSI command your driver is working on. The
|
mentioned interface above returns a value suitable for passing
|
mentioned interface above returns a value suitable for passing
|
into the streaming DMA mapping interfaces below.
|
into the streaming DMA mapping interfaces below.
|
|
|
For Networking drivers, it's a rather simple affair. For transmit
|
For Networking drivers, it's a rather simple affair. For transmit
|
packets, map/unmap them with the PCI_DMA_TODEVICE direction
|
packets, map/unmap them with the PCI_DMA_TODEVICE direction
|
specifier. For receive packets, just the opposite, map/unmap them
|
specifier. For receive packets, just the opposite, map/unmap them
|
with the PCI_DMA_FROMDEVICE direction specifier.
|
with the PCI_DMA_FROMDEVICE direction specifier.
|
|
|
Using Streaming DMA mappings
|
Using Streaming DMA mappings
|
|
|
The streaming DMA mapping routines can be called from interrupt
|
The streaming DMA mapping routines can be called from interrupt
|
context. There are two versions of each map/unmap, one which will
|
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
|
map/unmap a single memory region, and one which will map/unmap a
|
scatterlist.
|
scatterlist.
|
|
|
To map a single region, you do:
|
To map a single region, you do:
|
|
|
struct pci_dev *pdev = mydev->pdev;
|
struct pci_dev *pdev = mydev->pdev;
|
dma_addr_t dma_handle;
|
dma_addr_t dma_handle;
|
void *addr = buffer->ptr;
|
void *addr = buffer->ptr;
|
size_t size = buffer->len;
|
size_t size = buffer->len;
|
|
|
dma_handle = pci_map_single(dev, addr, size, direction);
|
dma_handle = pci_map_single(dev, addr, size, direction);
|
|
|
and to unmap it:
|
and to unmap it:
|
|
|
pci_unmap_single(dev, dma_handle, size, direction);
|
pci_unmap_single(dev, dma_handle, size, direction);
|
|
|
You should call pci_unmap_single when the DMA activity is finished, e.g.
|
You should call pci_unmap_single when the DMA activity is finished, e.g.
|
from the interrupt which told you that the DMA transfer is done.
|
from the interrupt which told you that the DMA transfer is done.
|
|
|
Using cpu pointers like this for single mappings has a disadvantage,
|
Using cpu pointers like this for single mappings has a disadvantage,
|
you cannot reference HIGHMEM memory in this way. Thus, there is a
|
you cannot reference HIGHMEM memory in this way. Thus, there is a
|
map/unmap interface pair akin to pci_{map,unmap}_single. These
|
map/unmap interface pair akin to pci_{map,unmap}_single. These
|
interfaces deal with page/offset pairs instead of cpu pointers.
|
interfaces deal with page/offset pairs instead of cpu pointers.
|
Specifically:
|
Specifically:
|
|
|
struct pci_dev *pdev = mydev->pdev;
|
struct pci_dev *pdev = mydev->pdev;
|
dma_addr_t dma_handle;
|
dma_addr_t dma_handle;
|
struct page *page = buffer->page;
|
struct page *page = buffer->page;
|
unsigned long offset = buffer->offset;
|
unsigned long offset = buffer->offset;
|
size_t size = buffer->len;
|
size_t size = buffer->len;
|
|
|
dma_handle = pci_map_page(dev, page, offset, size, direction);
|
dma_handle = pci_map_page(dev, page, offset, size, direction);
|
|
|
...
|
...
|
|
|
pci_unmap_page(dev, dma_handle, size, direction);
|
pci_unmap_page(dev, dma_handle, size, direction);
|
|
|
Here, "offset" means byte offset within the given page.
|
Here, "offset" means byte offset within the given page.
|
|
|
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 = pci_map_sg(dev, sglist, nents, direction);
|
int i, count = pci_map_sg(dev, sglist, nents, direction);
|
struct scatterlist *sg;
|
struct scatterlist *sg;
|
|
|
for (i = 0, sg = sglist; i < count; i++, sg++) {
|
for (i = 0, sg = sglist; i < count; i++, sg++) {
|
hw_address[i] = sg_dma_address(sg);
|
hw_address[i] = sg_dma_address(sg);
|
hw_len[i] = sg_dma_len(sg);
|
hw_len[i] = sg_dma_len(sg);
|
}
|
}
|
|
|
where nents is the number of entries in the sglist.
|
where nents is the number of entries in the sglist.
|
|
|
The implementation is free to merge several consecutive sglist entries
|
The implementation is free to merge several consecutive sglist entries
|
into one (e.g. if DMA mapping is done with PAGE_SIZE granularity, any
|
into one (e.g. if DMA mapping is done with PAGE_SIZE granularity, any
|
consecutive sglist entries can be merged into one provided the first one
|
consecutive sglist entries can be merged into one provided the first one
|
ends and the second one starts on a page boundary - in fact this is a huge
|
ends and the second one starts on a page boundary - in fact this is a huge
|
advantage for cards which either cannot do scatter-gather or have very
|
advantage for cards which either cannot do scatter-gather or have very
|
limited number of scatter-gather entries) and returns the actual number
|
limited number of scatter-gather entries) and returns the actual number
|
of sg entries it mapped them to.
|
of sg entries it mapped them to.
|
|
|
Then you should loop count times (note: this can be less than nents times)
|
Then you should loop count times (note: this can be less than nents times)
|
and use sg_dma_address() and sg_dma_len() macros where you previously
|
and use sg_dma_address() and sg_dma_len() macros where you previously
|
accessed sg->address and sg->length as shown above.
|
accessed sg->address and sg->length as shown above.
|
|
|
To unmap a scatterlist, just call:
|
To unmap a scatterlist, just call:
|
|
|
pci_unmap_sg(dev, sglist, nents, direction);
|
pci_unmap_sg(dev, sglist, nents, direction);
|
|
|
Again, make sure DMA activity has already finished.
|
Again, make sure DMA activity has already finished.
|
|
|
PLEASE NOTE: The 'nents' argument to the pci_unmap_sg call must be
|
PLEASE NOTE: The 'nents' argument to the pci_unmap_sg call must be
|
the _same_ one you passed into the pci_map_sg call,
|
the _same_ one you passed into the pci_map_sg call,
|
it should _NOT_ be the 'count' value _returned_ from the
|
it should _NOT_ be the 'count' value _returned_ from the
|
pci_map_sg call.
|
pci_map_sg call.
|
|
|
Every pci_map_{single,sg} call should have its pci_unmap_{single,sg}
|
Every pci_map_{single,sg} call should have its pci_unmap_{single,sg}
|
counterpart, because the bus address space is a shared resource (although
|
counterpart, because the bus address space is a shared resource (although
|
in some ports the mapping is per each BUS so less devices contend for the
|
in some ports the mapping is per each BUS so less devices contend for the
|
same bus address space) and you could render the machine unusable by eating
|
same bus address space) and you could render the machine unusable by eating
|
all bus addresses.
|
all bus 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, just map it with
|
the data in between the DMA transfers, just map it with
|
pci_map_{single,sg}, and after each DMA transfer call either:
|
pci_map_{single,sg}, and after each DMA transfer call either:
|
|
|
pci_dma_sync_single(dev, dma_handle, size, direction);
|
pci_dma_sync_single(dev, dma_handle, size, direction);
|
|
|
or:
|
or:
|
|
|
pci_dma_sync_sg(dev, sglist, nents, direction);
|
pci_dma_sync_sg(dev, sglist, nents, direction);
|
|
|
as appropriate.
|
as appropriate.
|
|
|
After the last DMA transfer call one of the DMA unmap routines
|
After the last DMA transfer call one of the DMA unmap routines
|
pci_unmap_{single,sg}. If you don't touch the data from the first pci_map_*
|
pci_unmap_{single,sg}. If you don't touch the data from the first pci_map_*
|
call till pci_unmap_*, then you don't have to call the pci_dma_sync_*
|
call till pci_unmap_*, then you don't have to call the pci_dma_sync_*
|
routines at all.
|
routines at all.
|
|
|
Here is pseudo code which shows a situation in which you would need
|
Here is pseudo code which shows a situation in which you would need
|
to use the pci_dma_sync_*() interfaces.
|
to use the pci_dma_sync_*() interfaces.
|
|
|
my_card_setup_receive_buffer(struct my_card *cp, char *buffer, int len)
|
my_card_setup_receive_buffer(struct my_card *cp, char *buffer, int len)
|
{
|
{
|
dma_addr_t mapping;
|
dma_addr_t mapping;
|
|
|
mapping = pci_map_single(cp->pdev, buffer, len, PCI_DMA_FROMDEVICE);
|
mapping = pci_map_single(cp->pdev, buffer, len, PCI_DMA_FROMDEVICE);
|
|
|
cp->rx_buf = buffer;
|
cp->rx_buf = buffer;
|
cp->rx_len = len;
|
cp->rx_len = len;
|
cp->rx_dma = mapping;
|
cp->rx_dma = mapping;
|
|
|
give_rx_buf_to_card(cp);
|
give_rx_buf_to_card(cp);
|
}
|
}
|
|
|
...
|
...
|
|
|
my_card_interrupt_handler(int irq, void *devid, struct pt_regs *regs)
|
my_card_interrupt_handler(int irq, void *devid, struct pt_regs *regs)
|
{
|
{
|
struct my_card *cp = devid;
|
struct my_card *cp = devid;
|
|
|
...
|
...
|
if (read_card_status(cp) == RX_BUF_TRANSFERRED) {
|
if (read_card_status(cp) == RX_BUF_TRANSFERRED) {
|
struct my_card_header *hp;
|
struct my_card_header *hp;
|
|
|
/* Examine the header to see if we wish
|
/* Examine the header to see if we wish
|
* to accept the data. But synchronize
|
* to accept the data. But synchronize
|
* the DMA transfer with the CPU first
|
* the DMA transfer with the CPU first
|
* so that we see updated contents.
|
* so that we see updated contents.
|
*/
|
*/
|
pci_dma_sync_single(cp->pdev, cp->rx_dma, cp->rx_len,
|
pci_dma_sync_single(cp->pdev, cp->rx_dma, cp->rx_len,
|
PCI_DMA_FROMDEVICE);
|
PCI_DMA_FROMDEVICE);
|
|
|
/* Now it is safe to examine the buffer. */
|
/* Now it is safe to examine the buffer. */
|
hp = (struct my_card_header *) cp->rx_buf;
|
hp = (struct my_card_header *) cp->rx_buf;
|
if (header_is_ok(hp)) {
|
if (header_is_ok(hp)) {
|
pci_unmap_single(cp->pdev, cp->rx_dma, cp->rx_len,
|
pci_unmap_single(cp->pdev, cp->rx_dma, cp->rx_len,
|
PCI_DMA_FROMDEVICE);
|
PCI_DMA_FROMDEVICE);
|
pass_to_upper_layers(cp->rx_buf);
|
pass_to_upper_layers(cp->rx_buf);
|
make_and_setup_new_rx_buf(cp);
|
make_and_setup_new_rx_buf(cp);
|
} else {
|
} else {
|
/* Just give the buffer back to the card. */
|
/* Just give the buffer back to the card. */
|
give_rx_buf_to_card(cp);
|
give_rx_buf_to_card(cp);
|
}
|
}
|
}
|
}
|
}
|
}
|
|
|
Drivers converted fully to this interface should not use virt_to_bus any
|
Drivers converted fully to this interface should not use virt_to_bus any
|
longer, nor should they use bus_to_virt. Some drivers have to be changed a
|
longer, nor should they use bus_to_virt. Some drivers have to be changed a
|
little bit, because there is no longer an equivalent to bus_to_virt in the
|
little bit, because there is no longer an equivalent to bus_to_virt in the
|
dynamic DMA mapping scheme - you have to always store the DMA addresses
|
dynamic DMA mapping scheme - you have to always store the DMA addresses
|
returned by the pci_alloc_consistent, pci_pool_alloc, and pci_map_single
|
returned by the pci_alloc_consistent, pci_pool_alloc, and pci_map_single
|
calls (pci_map_sg stores them in the scatterlist itself if the platform
|
calls (pci_map_sg stores them in the scatterlist itself if the platform
|
supports dynamic DMA mapping in hardware) in your driver structures and/or
|
supports dynamic DMA mapping in hardware) in your driver structures and/or
|
in the card registers.
|
in the card registers.
|
|
|
All PCI drivers should be using these interfaces with no exceptions.
|
All PCI drivers should be using these interfaces with no exceptions.
|
It is planned to completely remove virt_to_bus() and bus_to_virt() as
|
It is planned to completely remove virt_to_bus() and bus_to_virt() as
|
they are entirely deprecated. Some ports already do not provide these
|
they are entirely deprecated. Some ports already do not provide these
|
as it is impossible to correctly support them.
|
as it is impossible to correctly support them.
|
|
|
64-bit DMA and DAC cycle support
|
64-bit DMA and DAC cycle support
|
|
|
Do you understand all of the text above? Great, then you already
|
Do you understand all of the text above? Great, then you already
|
know how to use 64-bit DMA addressing under Linux. Simply make
|
know how to use 64-bit DMA addressing under Linux. Simply make
|
the appropriate pci_set_dma_mask() calls based upon your cards
|
the appropriate pci_set_dma_mask() calls based upon your cards
|
capabilities, then use the mapping APIs above.
|
capabilities, then use the mapping APIs above.
|
|
|
It is that simple.
|
It is that simple.
|
|
|
Well, not for some odd devices. See the next section for information
|
Well, not for some odd devices. See the next section for information
|
about that.
|
about that.
|
|
|
DAC Addressing for Address Space Hungry Devices
|
DAC Addressing for Address Space Hungry Devices
|
|
|
There exists a class of devices which do not mesh well with the PCI
|
There exists a class of devices which do not mesh well with the PCI
|
DMA mapping API. By definition these "mappings" are a finite
|
DMA mapping API. By definition these "mappings" are a finite
|
resource. The number of total available mappings per bus is platform
|
resource. The number of total available mappings per bus is platform
|
specific, but there will always be a reasonable amount.
|
specific, but there will always be a reasonable amount.
|
|
|
What is "reasonable"? Reasonable means that networking and block I/O
|
What is "reasonable"? Reasonable means that networking and block I/O
|
devices need not worry about using too many mappings.
|
devices need not worry about using too many mappings.
|
|
|
As an example of a problematic device, consider compute cluster cards.
|
As an example of a problematic device, consider compute cluster cards.
|
They can potentially need to access gigabytes of memory at once via
|
They can potentially need to access gigabytes of memory at once via
|
DMA. Dynamic mappings are unsuitable for this kind of access pattern.
|
DMA. Dynamic mappings are unsuitable for this kind of access pattern.
|
|
|
To this end we've provided a small API by which a device driver
|
To this end we've provided a small API by which a device driver
|
may use DAC cycles to directly address all of physical memory.
|
may use DAC cycles to directly address all of physical memory.
|
Not all platforms support this, but most do. It is easy to determine
|
Not all platforms support this, but most do. It is easy to determine
|
whether the platform will work properly at probe time.
|
whether the platform will work properly at probe time.
|
|
|
First, understand that there may be a SEVERE performance penalty for
|
First, understand that there may be a SEVERE performance penalty for
|
using these interfaces on some platforms. Therefore, you MUST only
|
using these interfaces on some platforms. Therefore, you MUST only
|
use these interfaces if it is absolutely required. %99 of devices can
|
use these interfaces if it is absolutely required. %99 of devices can
|
use the normal APIs without any problems.
|
use the normal APIs without any problems.
|
|
|
Note that for streaming type mappings you must either use these
|
Note that for streaming type mappings you must either use these
|
interfaces, or the dynamic mapping interfaces above. You may not mix
|
interfaces, or the dynamic mapping interfaces above. You may not mix
|
usage of both for the same device. Such an act is illegal and is
|
usage of both for the same device. Such an act is illegal and is
|
guaranteed to put a banana in your tailpipe.
|
guaranteed to put a banana in your tailpipe.
|
|
|
However, consistent mappings may in fact be used in conjunction with
|
However, consistent mappings may in fact be used in conjunction with
|
these interfaces. Remember that, as defined, consistent mappings are
|
these interfaces. Remember that, as defined, consistent mappings are
|
always going to be SAC addressable.
|
always going to be SAC addressable.
|
|
|
The first thing your driver needs to do is query the PCI platform
|
The first thing your driver needs to do is query the PCI platform
|
layer with your devices DAC addressing capabilities:
|
layer with your devices DAC addressing capabilities:
|
|
|
int pci_dac_set_dma_mask(struct pci_dev *pdev, u64 mask);
|
int pci_dac_set_dma_mask(struct pci_dev *pdev, u64 mask);
|
|
|
This routine behaves identically to pci_set_dma_mask. You may not
|
This routine behaves identically to pci_set_dma_mask. You may not
|
use the following interfaces if this routine fails.
|
use the following interfaces if this routine fails.
|
|
|
Next, DMA addresses using this API are kept track of using the
|
Next, DMA addresses using this API are kept track of using the
|
dma64_addr_t type. It is guaranteed to be big enough to hold any
|
dma64_addr_t type. It is guaranteed to be big enough to hold any
|
DAC address the platform layer will give to you from the following
|
DAC address the platform layer will give to you from the following
|
routines. If you have consistent mappings as well, you still
|
routines. If you have consistent mappings as well, you still
|
use plain dma_addr_t to keep track of those.
|
use plain dma_addr_t to keep track of those.
|
|
|
All mappings obtained here will be direct. The mappings are not
|
All mappings obtained here will be direct. The mappings are not
|
translated, and this is the purpose of this dialect of the DMA API.
|
translated, and this is the purpose of this dialect of the DMA API.
|
|
|
All routines work with page/offset pairs. This is the _ONLY_ way to
|
All routines work with page/offset pairs. This is the _ONLY_ way to
|
portably refer to any piece of memory. If you have a cpu pointer
|
portably refer to any piece of memory. If you have a cpu pointer
|
(which may be validly DMA'd too) you may easily obtain the page
|
(which may be validly DMA'd too) you may easily obtain the page
|
and offset using something like this:
|
and offset using something like this:
|
|
|
struct page *page = virt_to_page(ptr);
|
struct page *page = virt_to_page(ptr);
|
unsigned long offset = ((unsigned long)ptr & ~PAGE_MASK);
|
unsigned long offset = ((unsigned long)ptr & ~PAGE_MASK);
|
|
|
Here are the interfaces:
|
Here are the interfaces:
|
|
|
dma64_addr_t pci_dac_page_to_dma(struct pci_dev *pdev,
|
dma64_addr_t pci_dac_page_to_dma(struct pci_dev *pdev,
|
struct page *page,
|
struct page *page,
|
unsigned long offset,
|
unsigned long offset,
|
int direction);
|
int direction);
|
|
|
The DAC address for the tuple PAGE/OFFSET are returned. The direction
|
The DAC address for the tuple PAGE/OFFSET are returned. The direction
|
argument is the same as for pci_{map,unmap}_single(). The same rules
|
argument is the same as for pci_{map,unmap}_single(). The same rules
|
for cpu/device access apply here as for the streaming mapping
|
for cpu/device access apply here as for the streaming mapping
|
interfaces. To reiterate:
|
interfaces. To reiterate:
|
|
|
The cpu may touch the buffer before pci_dac_page_to_dma.
|
The cpu may touch the buffer before pci_dac_page_to_dma.
|
The device may touch the buffer after pci_dac_page_to_dma
|
The device may touch the buffer after pci_dac_page_to_dma
|
is made, but the cpu may NOT.
|
is made, but the cpu may NOT.
|
|
|
When the DMA transfer is complete, invoke:
|
When the DMA transfer is complete, invoke:
|
|
|
void pci_dac_dma_sync_single(struct pci_dev *pdev,
|
void pci_dac_dma_sync_single(struct pci_dev *pdev,
|
dma64_addr_t dma_addr,
|
dma64_addr_t dma_addr,
|
size_t len, int direction);
|
size_t len, int direction);
|
|
|
This must be done before the CPU looks at the buffer again.
|
This must be done before the CPU looks at the buffer again.
|
This interface behaves identically to pci_dma_sync_{single,sg}().
|
This interface behaves identically to pci_dma_sync_{single,sg}().
|
|
|
If you need to get back to the PAGE/OFFSET tuple from a dma64_addr_t
|
If you need to get back to the PAGE/OFFSET tuple from a dma64_addr_t
|
the following interfaces are provided:
|
the following interfaces are provided:
|
|
|
struct page *pci_dac_dma_to_page(struct pci_dev *pdev,
|
struct page *pci_dac_dma_to_page(struct pci_dev *pdev,
|
dma64_addr_t dma_addr);
|
dma64_addr_t dma_addr);
|
unsigned long pci_dac_dma_to_offset(struct pci_dev *pdev,
|
unsigned long pci_dac_dma_to_offset(struct pci_dev *pdev,
|
dma64_addr_t dma_addr);
|
dma64_addr_t dma_addr);
|
|
|
This is possible with the DAC interfaces purely because they are
|
This is possible with the DAC interfaces purely because they are
|
not translated in any way.
|
not translated in any way.
|
|
|
Optimizing Unmap State Space Consumption
|
Optimizing Unmap State Space Consumption
|
|
|
On many platforms, pci_unmap_{single,page}() is simply a nop.
|
On many platforms, pci_unmap_{single,page}() is simply a nop.
|
Therefore, keeping track of the mapping address and length is a waste
|
Therefore, keeping track of the mapping address and length is a waste
|
of space. Instead of filling your drivers up with ifdefs and the like
|
of space. Instead of filling your drivers up with ifdefs and the like
|
to "work around" this (which would defeat the whole purpose of a
|
to "work around" this (which would defeat the whole purpose of a
|
portable API) the following facilities are provided.
|
portable API) the following facilities are provided.
|
|
|
Actually, instead of describing the macros one by one, we'll
|
Actually, instead of describing the macros one by one, we'll
|
transform some example code.
|
transform some example code.
|
|
|
1) Use DECLARE_PCI_UNMAP_{ADDR,LEN} in state saving structures.
|
1) Use DECLARE_PCI_UNMAP_{ADDR,LEN} in state saving structures.
|
Example, before:
|
Example, before:
|
|
|
struct ring_state {
|
struct ring_state {
|
struct sk_buff *skb;
|
struct sk_buff *skb;
|
dma_addr_t mapping;
|
dma_addr_t mapping;
|
__u32 len;
|
__u32 len;
|
};
|
};
|
|
|
after:
|
after:
|
|
|
struct ring_state {
|
struct ring_state {
|
struct sk_buff *skb;
|
struct sk_buff *skb;
|
DECLARE_PCI_UNMAP_ADDR(mapping)
|
DECLARE_PCI_UNMAP_ADDR(mapping)
|
DECLARE_PCI_UNMAP_LEN(len)
|
DECLARE_PCI_UNMAP_LEN(len)
|
};
|
};
|
|
|
NOTE: DO NOT put a semicolon at the end of the DECLARE_*()
|
NOTE: DO NOT put a semicolon at the end of the DECLARE_*()
|
macro.
|
macro.
|
|
|
2) Use pci_unmap_{addr,len}_set to set these values.
|
2) Use pci_unmap_{addr,len}_set to set these values.
|
Example, before:
|
Example, before:
|
|
|
ringp->mapping = FOO;
|
ringp->mapping = FOO;
|
ringp->len = BAR;
|
ringp->len = BAR;
|
|
|
after:
|
after:
|
|
|
pci_unmap_addr_set(ringp, mapping, FOO);
|
pci_unmap_addr_set(ringp, mapping, FOO);
|
pci_unmap_len_set(ringp, len, BAR);
|
pci_unmap_len_set(ringp, len, BAR);
|
|
|
3) Use pci_unmap_{addr,len} to access these values.
|
3) Use pci_unmap_{addr,len} to access these values.
|
Example, before:
|
Example, before:
|
|
|
pci_unmap_single(pdev, ringp->mapping, ringp->len,
|
pci_unmap_single(pdev, ringp->mapping, ringp->len,
|
PCI_DMA_FROMDEVICE);
|
PCI_DMA_FROMDEVICE);
|
|
|
after:
|
after:
|
|
|
pci_unmap_single(pdev,
|
pci_unmap_single(pdev,
|
pci_unmap_addr(ringp, mapping),
|
pci_unmap_addr(ringp, mapping),
|
pci_unmap_len(ringp, len),
|
pci_unmap_len(ringp, len),
|
PCI_DMA_FROMDEVICE);
|
PCI_DMA_FROMDEVICE);
|
|
|
It really should be self-explanatory. We treat the ADDR and LEN
|
It really should be self-explanatory. We treat the ADDR and LEN
|
separately, because it is possible for an implementation to only
|
separately, because it is possible for an implementation to only
|
need the address in order to perform the unmap operation.
|
need the address in order to perform the unmap operation.
|
|
|
Platform Issues
|
Platform Issues
|
|
|
If you are just writing drivers for Linux and do not maintain
|
If you are just writing drivers for Linux and do not maintain
|
an architecture port for the kernel, you can safely skip down
|
an architecture port for the kernel, you can safely skip down
|
to "Closing".
|
to "Closing".
|
|
|
1) Struct scatterlist requirements.
|
1) Struct scatterlist requirements.
|
|
|
Struct scatterlist must contain, at a minimum, the following
|
Struct scatterlist must contain, at a minimum, the following
|
members:
|
members:
|
|
|
char *address;
|
char *address;
|
struct page *page;
|
struct page *page;
|
unsigned int offset;
|
unsigned int offset;
|
unsigned int length;
|
unsigned int length;
|
|
|
The "address" member will disappear in 2.5.x
|
The "address" member will disappear in 2.5.x
|
|
|
This means that your pci_{map,unmap}_sg() and all other
|
This means that your pci_{map,unmap}_sg() and all other
|
interfaces dealing with scatterlists must be able to cope
|
interfaces dealing with scatterlists must be able to cope
|
properly with page being non NULL.
|
properly with page being non NULL.
|
|
|
A scatterlist is in one of two states. The base address is
|
A scatterlist is in one of two states. The base address is
|
either specified by "address" or by a "page+offset" pair.
|
either specified by "address" or by a "page+offset" pair.
|
If "address" is NULL, then "page+offset" is being used.
|
If "address" is NULL, then "page+offset" is being used.
|
If "page" is NULL, then "address" is being used.
|
If "page" is NULL, then "address" is being used.
|
|
|
In 2.5.x, all scatterlists will use "page+offset". But during
|
In 2.5.x, all scatterlists will use "page+offset". But during
|
2.4.x we still have to support the old method.
|
2.4.x we still have to support the old method.
|
|
|
2) More to come...
|
2) More to come...
|
|
|
Closing
|
Closing
|
|
|
This document, and the API itself, would not be in it's current
|
This document, and the API itself, would not be in it's current
|
form without the feedback and suggestions from numerous individuals.
|
form without the feedback and suggestions from numerous individuals.
|
We would like to specifically mention, in no particular order, the
|
We would like to specifically mention, in no particular order, the
|
following people:
|
following people:
|
|
|
Russell King
|
Russell King
|
Leo Dagum
|
Leo Dagum
|
Ralf Baechle
|
Ralf Baechle
|
Grant Grundler
|
Grant Grundler
|
Jay Estabrook
|
Jay Estabrook
|
Thomas Sailer
|
Thomas Sailer
|
Andrea Arcangeli
|
Andrea Arcangeli
|
Jens Axboe
|
Jens Axboe
|
David Mosberger-Tang
|
David Mosberger-Tang
|
|
|