diff options
author | Linus Torvalds <torvalds@woody.linux-foundation.org> | 2007-07-12 16:40:57 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@woody.linux-foundation.org> | 2007-07-12 16:40:57 -0400 |
commit | 21ba0f88ae56da82a3a15fe54d729208b64c4f4b (patch) | |
tree | 17ce67f276fe3ea7284c3dc730bdd6a2ec7dfe2f /Documentation | |
parent | dc690d8ef842b464f1c429a376ca16cb8dbee6ae (diff) | |
parent | 36e235901f90fb83215be43cbd8f1ca14661ea40 (diff) |
Merge master.kernel.org:/pub/scm/linux/kernel/git/gregkh/pci-2.6
* master.kernel.org:/pub/scm/linux/kernel/git/gregkh/pci-2.6: (34 commits)
PCI: Only build PCI syscalls on architectures that want them
PCI: limit pci_get_bus_and_slot to domain 0
PCI: hotplug: acpiphp: avoid acpiphp "cannot get bridge info" PCI hotplug failure
PCI: hotplug: acpiphp: remove hot plug parameter write to PCI host bridge
PCI: hotplug: acpiphp: fix slot poweroff problem on systems without _PS3
PCI: hotplug: pciehp: wait for 1 second after power off slot
PCI: pci_set_power_state(): check for PM capabilities earlier
PCI: cpci_hotplug: Convert to use the kthread API
PCI: add pci_try_set_mwi
PCI: pcie: remove SPIN_LOCK_UNLOCKED
PCI: ROUND_UP macro cleanup in drivers/pci
PCI: remove pci_dac_dma_... APIs
PCI: pci-x-pci-express-read-control-interfaces cleanups
PCI: Fix typo in include/linux/pci.h
PCI: pci_ids, remove double or more empty lines
PCI: pci_ids, add atheros and 3com_2 vendors
PCI: pci_ids, reorder some entries
PCI: i386: traps, change VENDOR to DEVICE
PCI: ATM: lanai, change VENDOR to DEVICE
PCI: Change all drivers to use pci_device->revision
...
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/DMA-mapping.txt | 103 | ||||
-rw-r--r-- | Documentation/pci.txt | 8 | ||||
-rw-r--r-- | Documentation/power/pci.txt | 37 |
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. | |||
664 | Well, not for some odd devices. See the next section for information | 664 | Well, not for some odd devices. See the next section for information |
665 | about that. | 665 | about that. |
666 | 666 | ||
667 | DAC Addressing for Address Space Hungry Devices | ||
668 | |||
669 | There exists a class of devices which do not mesh well with the PCI | ||
670 | DMA mapping API. By definition these "mappings" are a finite | ||
671 | resource. The number of total available mappings per bus is platform | ||
672 | specific, but there will always be a reasonable amount. | ||
673 | |||
674 | What is "reasonable"? Reasonable means that networking and block I/O | ||
675 | devices need not worry about using too many mappings. | ||
676 | |||
677 | As an example of a problematic device, consider compute cluster cards. | ||
678 | They can potentially need to access gigabytes of memory at once via | ||
679 | DMA. Dynamic mappings are unsuitable for this kind of access pattern. | ||
680 | |||
681 | To this end we've provided a small API by which a device driver | ||
682 | may use DAC cycles to directly address all of physical memory. | ||
683 | Not all platforms support this, but most do. It is easy to determine | ||
684 | whether the platform will work properly at probe time. | ||
685 | |||
686 | First, understand that there may be a SEVERE performance penalty for | ||
687 | using these interfaces on some platforms. Therefore, you MUST only | ||
688 | use these interfaces if it is absolutely required. %99 of devices can | ||
689 | use the normal APIs without any problems. | ||
690 | |||
691 | Note that for streaming type mappings you must either use these | ||
692 | interfaces, or the dynamic mapping interfaces above. You may not mix | ||
693 | usage of both for the same device. Such an act is illegal and is | ||
694 | guaranteed to put a banana in your tailpipe. | ||
695 | |||
696 | However, consistent mappings may in fact be used in conjunction with | ||
697 | these interfaces. Remember that, as defined, consistent mappings are | ||
698 | always going to be SAC addressable. | ||
699 | |||
700 | The first thing your driver needs to do is query the PCI platform | ||
701 | layer if it is capable of handling your devices DAC addressing | ||
702 | capabilities: | ||
703 | |||
704 | int pci_dac_dma_supported(struct pci_dev *hwdev, u64 mask); | ||
705 | |||
706 | You may not use the following interfaces if this routine fails. | ||
707 | |||
708 | Next, DMA addresses using this API are kept track of using the | ||
709 | dma64_addr_t type. It is guaranteed to be big enough to hold any | ||
710 | DAC address the platform layer will give to you from the following | ||
711 | routines. If you have consistent mappings as well, you still | ||
712 | use plain dma_addr_t to keep track of those. | ||
713 | |||
714 | All mappings obtained here will be direct. The mappings are not | ||
715 | translated, and this is the purpose of this dialect of the DMA API. | ||
716 | |||
717 | All routines work with page/offset pairs. This is the _ONLY_ way to | ||
718 | portably 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 | ||
720 | and offset using something like this: | ||
721 | |||
722 | struct page *page = virt_to_page(ptr); | ||
723 | unsigned long offset = offset_in_page(ptr); | ||
724 | |||
725 | Here 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 | |||
732 | The DAC address for the tuple PAGE/OFFSET are returned. The direction | ||
733 | argument is the same as for pci_{map,unmap}_single(). The same rules | ||
734 | for cpu/device access apply here as for the streaming mapping | ||
735 | interfaces. 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 | |||
741 | When 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 | |||
747 | This must be done before the CPU looks at the buffer again. | ||
748 | This interface behaves identically to pci_dma_sync_{single,sg}_for_cpu(). | ||
749 | |||
750 | And likewise, if you wish to let the device get back at the buffer after | ||
751 | the 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 | |||
757 | before letting the device access the DMA area again. | ||
758 | |||
759 | If you need to get back to the PAGE/OFFSET tuple from a dma64_addr_t | ||
760 | the 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 | |||
767 | This is possible with the DAC interfaces purely because they are | ||
768 | not translated in any way. | ||
769 | |||
770 | Optimizing Unmap State Space Consumption | 667 | Optimizing Unmap State Space Consumption |
771 | 668 | ||
772 | On many platforms, pci_unmap_{single,page}() is simply a nop. | 669 | On 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, | |||
299 | call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval | 296 | call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval |
300 | and also ensures that the cache line size register is set correctly. | 297 | and also ensures that the cache line size register is set correctly. |
301 | Check the return value of pci_set_mwi() as not all architectures | 298 | Check the return value of pci_set_mwi() as not all architectures |
302 | or chip-sets may support Memory-Write-Invalidate. | 299 | or chip-sets may support Memory-Write-Invalidate. Alternatively, |
300 | if Mem-Wr-Inval would be nice to have but is not required, call | ||
301 | pci_try_set_mwi() to have the system do its best effort at enabling | ||
302 | Mem-Wr-Inval. | ||
303 | 303 | ||
304 | 304 | ||
305 | 3.2 Request MMIO/IOP resources | 305 | 3.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 | ||
170 | suspend | 169 | suspend |
@@ -251,42 +250,6 @@ The driver should update the current_state field in its pci_dev structure in | |||
251 | this function, except for PM-capable devices when pci_set_power_state is used. | 250 | this function, except for PM-capable devices when pci_set_power_state is used. |
252 | 251 | ||
253 | 252 | ||
254 | enable_wake | ||
255 | ----------- | ||
256 | |||
257 | Usage: | ||
258 | |||
259 | if (dev->driver && dev->driver->enable_wake) | ||
260 | dev->driver->enable_wake(dev,state,enable); | ||
261 | |||
262 | This callback is generally only relevant for devices that support the PCI PM | ||
263 | spec and have the ability to generate a PME# (Power Management Event Signal) | ||
264 | to wake the system up. (However, it is possible that a device may support | ||
265 | some non-standard way of generating a wake event on sleep.) | ||
266 | |||
267 | Bits 15:11 of the PMC (Power Mgmt Capabilities) Register in a device's | ||
268 | PM Capabilities describe what power states the device supports generating a | ||
269 | wake 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 | |||
281 | A device can use this to enable wake events: | ||
282 | |||
283 | pci_enable_wake(dev,state,enable); | ||
284 | |||
285 | Note that to enable PME# from D3cold, a value of 4 should be passed to | ||
286 | pci_enable_wake (since it uses an index into a bitmask). If a driver gets | ||
287 | a request to enable wake events from D3, two calls should be made to | ||
288 | pci_enable_wake (one for both D3hot and D3cold). | ||
289 | |||
290 | 253 | ||
291 | A reference implementation | 254 | A reference implementation |
292 | ------------------------- | 255 | ------------------------- |