aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DMA-mapping.txt103
-rw-r--r--Documentation/pci.txt8
-rw-r--r--Documentation/power/pci.txt37
3 files changed, 4 insertions, 144 deletions
diff --git a/Documentation/DMA-mapping.txt b/Documentation/DMA-mapping.txt
index 028614cdd062..e07f2530326b 100644
--- a/Documentation/DMA-mapping.txt
+++ b/Documentation/DMA-mapping.txt
@@ -664,109 +664,6 @@ It is that simple.
664Well, not for some odd devices. See the next section for information 664Well, not for some odd devices. See the next section for information
665about that. 665about that.
666 666
667 DAC Addressing for Address Space Hungry Devices
668
669There exists a class of devices which do not mesh well with the PCI
670DMA mapping API. By definition these "mappings" are a finite
671resource. The number of total available mappings per bus is platform
672specific, but there will always be a reasonable amount.
673
674What is "reasonable"? Reasonable means that networking and block I/O
675devices need not worry about using too many mappings.
676
677As an example of a problematic device, consider compute cluster cards.
678They can potentially need to access gigabytes of memory at once via
679DMA. Dynamic mappings are unsuitable for this kind of access pattern.
680
681To this end we've provided a small API by which a device driver
682may use DAC cycles to directly address all of physical memory.
683Not all platforms support this, but most do. It is easy to determine
684whether the platform will work properly at probe time.
685
686First, understand that there may be a SEVERE performance penalty for
687using these interfaces on some platforms. Therefore, you MUST only
688use these interfaces if it is absolutely required. %99 of devices can
689use the normal APIs without any problems.
690
691Note that for streaming type mappings you must either use these
692interfaces, or the dynamic mapping interfaces above. You may not mix
693usage of both for the same device. Such an act is illegal and is
694guaranteed to put a banana in your tailpipe.
695
696However, consistent mappings may in fact be used in conjunction with
697these interfaces. Remember that, as defined, consistent mappings are
698always going to be SAC addressable.
699
700The first thing your driver needs to do is query the PCI platform
701layer if it is capable of handling your devices DAC addressing
702capabilities:
703
704 int pci_dac_dma_supported(struct pci_dev *hwdev, u64 mask);
705
706You may not use the following interfaces if this routine fails.
707
708Next, DMA addresses using this API are kept track of using the
709dma64_addr_t type. It is guaranteed to be big enough to hold any
710DAC address the platform layer will give to you from the following
711routines. If you have consistent mappings as well, you still
712use plain dma_addr_t to keep track of those.
713
714All mappings obtained here will be direct. The mappings are not
715translated, and this is the purpose of this dialect of the DMA API.
716
717All routines work with page/offset pairs. This is the _ONLY_ way to
718portably refer to any piece of memory. If you have a cpu pointer
719(which may be validly DMA'd too) you may easily obtain the page
720and offset using something like this:
721
722 struct page *page = virt_to_page(ptr);
723 unsigned long offset = offset_in_page(ptr);
724
725Here are the interfaces:
726
727 dma64_addr_t pci_dac_page_to_dma(struct pci_dev *pdev,
728 struct page *page,
729 unsigned long offset,
730 int direction);
731
732The DAC address for the tuple PAGE/OFFSET are returned. The direction
733argument is the same as for pci_{map,unmap}_single(). The same rules
734for cpu/device access apply here as for the streaming mapping
735interfaces. To reiterate:
736
737 The cpu may touch the buffer before pci_dac_page_to_dma.
738 The device may touch the buffer after pci_dac_page_to_dma
739 is made, but the cpu may NOT.
740
741When the DMA transfer is complete, invoke:
742
743 void pci_dac_dma_sync_single_for_cpu(struct pci_dev *pdev,
744 dma64_addr_t dma_addr,
745 size_t len, int direction);
746
747This must be done before the CPU looks at the buffer again.
748This interface behaves identically to pci_dma_sync_{single,sg}_for_cpu().
749
750And likewise, if you wish to let the device get back at the buffer after
751the cpu has read/written it, invoke:
752
753 void pci_dac_dma_sync_single_for_device(struct pci_dev *pdev,
754 dma64_addr_t dma_addr,
755 size_t len, int direction);
756
757before letting the device access the DMA area again.
758
759If you need to get back to the PAGE/OFFSET tuple from a dma64_addr_t
760the following interfaces are provided:
761
762 struct page *pci_dac_dma_to_page(struct pci_dev *pdev,
763 dma64_addr_t dma_addr);
764 unsigned long pci_dac_dma_to_offset(struct pci_dev *pdev,
765 dma64_addr_t dma_addr);
766
767This is possible with the DAC interfaces purely because they are
768not translated in any way.
769
770 Optimizing Unmap State Space Consumption 667 Optimizing Unmap State Space Consumption
771 668
772On many platforms, pci_unmap_{single,page}() is simply a nop. 669On many platforms, pci_unmap_{single,page}() is simply a nop.
diff --git a/Documentation/pci.txt b/Documentation/pci.txt
index d38261b67905..7754f5aea4e9 100644
--- a/Documentation/pci.txt
+++ b/Documentation/pci.txt
@@ -113,9 +113,6 @@ initialization with a pointer to a structure describing the driver
113 (Please see Documentation/power/pci.txt for descriptions 113 (Please see Documentation/power/pci.txt for descriptions
114 of PCI Power Management and the related functions.) 114 of PCI Power Management and the related functions.)
115 115
116 enable_wake Enable device to generate wake events from a low power
117 state.
118
119 shutdown Hook into reboot_notifier_list (kernel/sys.c). 116 shutdown Hook into reboot_notifier_list (kernel/sys.c).
120 Intended to stop any idling DMA operations. 117 Intended to stop any idling DMA operations.
121 Useful for enabling wake-on-lan (NIC) or changing 118 Useful for enabling wake-on-lan (NIC) or changing
@@ -299,7 +296,10 @@ If the PCI device can use the PCI Memory-Write-Invalidate transaction,
299call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval 296call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval
300and also ensures that the cache line size register is set correctly. 297and also ensures that the cache line size register is set correctly.
301Check the return value of pci_set_mwi() as not all architectures 298Check the return value of pci_set_mwi() as not all architectures
302or chip-sets may support Memory-Write-Invalidate. 299or chip-sets may support Memory-Write-Invalidate. Alternatively,
300if Mem-Wr-Inval would be nice to have but is not required, call
301pci_try_set_mwi() to have the system do its best effort at enabling
302Mem-Wr-Inval.
303 303
304 304
3053.2 Request MMIO/IOP resources 3053.2 Request MMIO/IOP resources
diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.txt
index e00b099a4b86..dd8fe43888d3 100644
--- a/Documentation/power/pci.txt
+++ b/Documentation/power/pci.txt
@@ -164,7 +164,6 @@ struct pci_driver:
164 164
165 int (*suspend) (struct pci_dev *dev, pm_message_t state); 165 int (*suspend) (struct pci_dev *dev, pm_message_t state);
166 int (*resume) (struct pci_dev *dev); 166 int (*resume) (struct pci_dev *dev);
167 int (*enable_wake) (struct pci_dev *dev, pci_power_t state, int enable);
168 167
169 168
170suspend 169suspend
@@ -251,42 +250,6 @@ The driver should update the current_state field in its pci_dev structure in
251this function, except for PM-capable devices when pci_set_power_state is used. 250this function, except for PM-capable devices when pci_set_power_state is used.
252 251
253 252
254enable_wake
255-----------
256
257Usage:
258
259if (dev->driver && dev->driver->enable_wake)
260 dev->driver->enable_wake(dev,state,enable);
261
262This callback is generally only relevant for devices that support the PCI PM
263spec and have the ability to generate a PME# (Power Management Event Signal)
264to wake the system up. (However, it is possible that a device may support
265some non-standard way of generating a wake event on sleep.)
266
267Bits 15:11 of the PMC (Power Mgmt Capabilities) Register in a device's
268PM Capabilities describe what power states the device supports generating a
269wake event from:
270
271+------------------+
272| Bit | State |
273+------------------+
274| 11 | D0 |
275| 12 | D1 |
276| 13 | D2 |
277| 14 | D3hot |
278| 15 | D3cold |
279+------------------+
280
281A device can use this to enable wake events:
282
283 pci_enable_wake(dev,state,enable);
284
285Note that to enable PME# from D3cold, a value of 4 should be passed to
286pci_enable_wake (since it uses an index into a bitmask). If a driver gets
287a request to enable wake events from D3, two calls should be made to
288pci_enable_wake (one for both D3hot and D3cold).
289
290 253
291A reference implementation 254A reference implementation
292------------------------- 255-------------------------