From grundler@lackof.org Thu Jun 1 10:16:09 2006 Date: Thu, 1 Jun 2006 11:15:59 -0600 From: Grant Grundler To: Rajesh Shah Cc: "bibo,mao" , akpm@osdl.org, Greg KH , linux-kernel@vger.kernel.org, linux-pci@atrey.karlin.mff.cuni.cz, kaneshige.kenji@jp.fujitsu.com Subject: PCI: clean up pci documentation to be more specific Message-ID: <20060601171559.GA16288@colo.lackof.org> On Thu, Jun 01, 2006 at 02:46:11AM -0700, Rajesh Shah wrote: > This patch assumes that pci_request_region() will always be called > after pci_enable_device() and pci_release_region() will always > be called before pci_disable_device(). We cannot make this > assumption,since it's perfectly legal to disable a device > first and then release it's regions. So, I think that patch > needs to change. Patch below clarifies comments in Documentation/pci.txt. Signed-off-by: Grant Grundler Signed-off-by: Greg Kroah-Hartman --- Documentation/pci.txt | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) --- gregkh-2.6.orig/Documentation/pci.txt +++ gregkh-2.6/Documentation/pci.txt @@ -213,9 +213,17 @@ have been remapped by the kernel. See Documentation/IO-mapping.txt for how to access device memory. - You still need to call request_region() for I/O regions and -request_mem_region() for memory regions to make sure nobody else is using the -same device. + The device driver needs to call pci_request_region() to make sure +no other device is already using the same resource. The driver is expected +to determine MMIO and IO Port resource availability _before_ calling +pci_enable_device(). Conversely, drivers should call pci_release_region() +_after_ calling pci_disable_device(). The idea is to prevent two devices +colliding on the same address range. + +Generic flavors of pci_request_region() are request_mem_region() +(for MMIO ranges) and request_region() (for IO Port ranges). +Use these for address resources that are not described by "normal" PCI +interfaces (e.g. BAR). All interrupt handlers should be registered with SA_SHIRQ and use the devid to map IRQs to devices (remember that all PCI interrupts are shared).