Re: [PATCH] Update Documentation/pci.txt v7
On Tue, Jan 02, 2007 at 01:45:05PM -0800, Greg KH wrote: > On Mon, Dec 25, 2006 at 01:08:31AM -0700, Grant Grundler wrote: > > On Mon, Dec 25, 2006 at 01:06:35AM -0700, Grant Grundler wrote: > > > On Sat, Dec 23, 2006 at 11:07:26PM -0700, Grant Grundler wrote: > > > > "final" patch v7 and commit log entry appended below. :) > > > > > > v8 adds 2cd round of feedback from Randy Dunlap. > > > > Obviously the subject line is stale...it's really v8 now. > > It's just way past my bedtime again. > > Care to resend the latest version to me now? I'm lost in a maze of > different versions of this patch :) Here is the archived version (click on "get diff" link): http://lkml.org/lkml/2006/12/25/2 Andrew (akpm) already picked it up: | The patch titled | Update Documentation/pci.txt | has been added to the -mm tree. Its filename is | update-documentation-pcitxt.patch Maybe it's easier for you to grab the patch directly from akpm? thanks for checking again! grant - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Update Documentation/pci.txt v7
On Mon, Dec 25, 2006 at 01:08:31AM -0700, Grant Grundler wrote: > On Mon, Dec 25, 2006 at 01:06:35AM -0700, Grant Grundler wrote: > > On Sat, Dec 23, 2006 at 11:07:26PM -0700, Grant Grundler wrote: > > > "final" patch v7 and commit log entry appended below. :) > > > > v8 adds 2cd round of feedback from Randy Dunlap. > > Obviously the subject line is stale...it's really v8 now. > It's just way past my bedtime again. Care to resend the latest version to me now? I'm lost in a maze of different versions of this patch :) thanks, greg k-h - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Update Documentation/pci.txt v7
On Mon, Dec 25, 2006 at 01:08:31AM -0700, Grant Grundler wrote: On Mon, Dec 25, 2006 at 01:06:35AM -0700, Grant Grundler wrote: On Sat, Dec 23, 2006 at 11:07:26PM -0700, Grant Grundler wrote: final patch v7 and commit log entry appended below. :) v8 adds 2cd round of feedback from Randy Dunlap. Obviously the subject line is stale...it's really v8 now. It's just way past my bedtime again. Care to resend the latest version to me now? I'm lost in a maze of different versions of this patch :) thanks, greg k-h - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Update Documentation/pci.txt v7
On Tue, Jan 02, 2007 at 01:45:05PM -0800, Greg KH wrote: On Mon, Dec 25, 2006 at 01:08:31AM -0700, Grant Grundler wrote: On Mon, Dec 25, 2006 at 01:06:35AM -0700, Grant Grundler wrote: On Sat, Dec 23, 2006 at 11:07:26PM -0700, Grant Grundler wrote: final patch v7 and commit log entry appended below. :) v8 adds 2cd round of feedback from Randy Dunlap. Obviously the subject line is stale...it's really v8 now. It's just way past my bedtime again. Care to resend the latest version to me now? I'm lost in a maze of different versions of this patch :) Here is the archived version (click on get diff link): http://lkml.org/lkml/2006/12/25/2 Andrew (akpm) already picked it up: | The patch titled | Update Documentation/pci.txt | has been added to the -mm tree. Its filename is | update-documentation-pcitxt.patch Maybe it's easier for you to grab the patch directly from akpm? thanks for checking again! grant - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Update Documentation/pci.txt v7
Grant Grundler wrote: On Sat, Dec 23, 2006 at 11:07:26PM -0700, Grant Grundler wrote: "final" patch v7 and commit log entry appended below. :) v8 adds 2cd round of feedback from Randy Dunlap. Going once...twice... ;) Full pci.txt text is easier to review at: http://www.parisc-linux.org/~grundler/Documentation/ Same place. grant Rewrite Documentation/pci.txt: o restructure document to match how API is used when writing init code. o update to reflect changes in struct pci_driver function pointers. o removed language on "new style vs old style" device discovery. "Old style" is now deprecated. Don't use it. Left description in to document existing driver behaviors. o add section "Legacy I/O Port free driver" by Kenji Kaneshige http://lkml.org/lkml/2006/11/22/25 (renamed to "pci_enable_device_bars() and Legacy I/O Port space") Thank you for updating this. It looks much better. Thank you again, Kenji Kaneshige - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Update Documentation/pci.txt v7
On Mon, Dec 25, 2006 at 01:06:35AM -0700, Grant Grundler wrote: > On Sat, Dec 23, 2006 at 11:07:26PM -0700, Grant Grundler wrote: > > "final" patch v7 and commit log entry appended below. :) > > v8 adds 2cd round of feedback from Randy Dunlap. Obviously the subject line is stale...it's really v8 now. It's just way past my bedtime again. grant > Going once...twice... ;) > > > Full pci.txt text is easier to review at: > > http://www.parisc-linux.org/~grundler/Documentation/ > > Same place. > > grant > > > Rewrite Documentation/pci.txt: > o restructure document to match how API is used when writing init code. > o update to reflect changes in struct pci_driver function pointers. > o removed language on "new style vs old style" device discovery. > "Old style" is now deprecated. Don't use it. Left description in > to document existing driver behaviors. > o add section "Legacy I/O Port free driver" by Kenji Kaneshige > http://lkml.org/lkml/2006/11/22/25 > (renamed to "pci_enable_device_bars() and Legacy I/O Port space") > o add "MMIO space and write posting" section to help avoid common pitfall > when converting drivers from IO Port space to MMIO space. > Orignally posted http://lkml.org/lkml/2006/2/27/24 > o many typo/grammer/spelling corrections from Randy Dunlap > o two more spelling corrections from Stephan Richter > o fix CodingStyle as per Randy Dunlap > > > Signed-off-by: Grant Grundler <[EMAIL PROTECTED]> > > > diff --git a/Documentation/pci.txt b/Documentation/pci.txt > index 2b395e4..0d33d80 100644 > --- a/Documentation/pci.txt > +++ b/Documentation/pci.txt > @@ -1,142 +1,231 @@ > - How To Write Linux PCI Drivers > > -by Martin Mares <[EMAIL PROTECTED]> on 07-Feb-2000 > + How To Write Linux PCI Drivers > + > + by Martin Mares <[EMAIL PROTECTED]> on 07-Feb-2000 > + updated by Grant Grundler <[EMAIL PROTECTED]> on 23-Dec-2006 > > > > -The world of PCI is vast and it's full of (mostly unpleasant) surprises. > -Different PCI devices have different requirements and different bugs -- > -because of this, the PCI support layer in Linux kernel is not as trivial > -as one would wish. This short pamphlet tries to help all potential driver > -authors find their way through the deep forests of PCI handling. > +The world of PCI is vast and full of (mostly unpleasant) surprises. > +Since each CPU architecture implements different chip-sets and PCI devices > +have different requirements (erm, "features"), the result is the PCI support > +in the Linux kernel is not as trivial as one would wish. This short paper > +tries to introduce all potential driver authors to Linux APIs for > +PCI device drivers. > + > +A more complete resource is the third edition of "Linux Device Drivers" > +by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. > +LDD3 is available for free (under Creative Commons License) from: > + > + http://lwn.net/Kernel/LDD3/ > + > +However, keep in mind that all documents are subject to "bit rot". > +Refer to the source code if things are not working as described here. > + > +Please send questions/comments/patches about Linux PCI API to the > +"Linux PCI" <[EMAIL PROTECTED]> mailing list. > + > > > 0. Structure of PCI drivers > ~~~ > -There exist two kinds of PCI drivers: new-style ones (which leave most of > -probing for devices to the PCI layer and support online insertion and removal > -of devices [thus supporting PCI, hot-pluggable PCI and CardBus in a single > -driver]) and old-style ones which just do all the probing themselves. Unless > -you have a very good reason to do so, please don't use the old way of probing > -in any new code. After the driver finds the devices it wishes to operate > -on (either the old or the new way), it needs to perform the following steps: > +PCI drivers "discover" PCI devices in a system via pci_register_driver(). > +Actually, it's the other way around. When the PCI generic code discovers > +a new device, the driver with a matching "description" will be notified. > +Details on this below. > + > +pci_register_driver() leaves most of the probing for devices to > +the PCI layer and supports online insertion/removal of devices [thus > +supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. > +pci_register_driver() call requires passing in a table of function > +pointers and thus dictates the high level structure of a driver. > + > +Once the driver knows about a PCI device and takes ownership, the > +driver generally needs to perform the following initialization: > > Enable the device > - Access device configuration space > - Discover resources (addresses and IRQ numbers) provided by the device > - Allocate these resources > - Communicate with the device > + Request MMIO/IOP resources > + Set
Re: [PATCH] Update Documentation/pci.txt v7
On Sat, Dec 23, 2006 at 11:07:26PM -0700, Grant Grundler wrote: > "final" patch v7 and commit log entry appended below. :) v8 adds 2cd round of feedback from Randy Dunlap. Going once...twice... ;) > Full pci.txt text is easier to review at: > http://www.parisc-linux.org/~grundler/Documentation/ Same place. grant Rewrite Documentation/pci.txt: o restructure document to match how API is used when writing init code. o update to reflect changes in struct pci_driver function pointers. o removed language on "new style vs old style" device discovery. "Old style" is now deprecated. Don't use it. Left description in to document existing driver behaviors. o add section "Legacy I/O Port free driver" by Kenji Kaneshige http://lkml.org/lkml/2006/11/22/25 (renamed to "pci_enable_device_bars() and Legacy I/O Port space") o add "MMIO space and write posting" section to help avoid common pitfall when converting drivers from IO Port space to MMIO space. Orignally posted http://lkml.org/lkml/2006/2/27/24 o many typo/grammer/spelling corrections from Randy Dunlap o two more spelling corrections from Stephan Richter o fix CodingStyle as per Randy Dunlap Signed-off-by: Grant Grundler <[EMAIL PROTECTED]> diff --git a/Documentation/pci.txt b/Documentation/pci.txt index 2b395e4..0d33d80 100644 --- a/Documentation/pci.txt +++ b/Documentation/pci.txt @@ -1,142 +1,231 @@ -How To Write Linux PCI Drivers - by Martin Mares <[EMAIL PROTECTED]> on 07-Feb-2000 + How To Write Linux PCI Drivers + + by Martin Mares <[EMAIL PROTECTED]> on 07-Feb-2000 + updated by Grant Grundler <[EMAIL PROTECTED]> on 23-Dec-2006 -The world of PCI is vast and it's full of (mostly unpleasant) surprises. -Different PCI devices have different requirements and different bugs -- -because of this, the PCI support layer in Linux kernel is not as trivial -as one would wish. This short pamphlet tries to help all potential driver -authors find their way through the deep forests of PCI handling. +The world of PCI is vast and full of (mostly unpleasant) surprises. +Since each CPU architecture implements different chip-sets and PCI devices +have different requirements (erm, "features"), the result is the PCI support +in the Linux kernel is not as trivial as one would wish. This short paper +tries to introduce all potential driver authors to Linux APIs for +PCI device drivers. + +A more complete resource is the third edition of "Linux Device Drivers" +by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. +LDD3 is available for free (under Creative Commons License) from: + + http://lwn.net/Kernel/LDD3/ + +However, keep in mind that all documents are subject to "bit rot". +Refer to the source code if things are not working as described here. + +Please send questions/comments/patches about Linux PCI API to the +"Linux PCI" <[EMAIL PROTECTED]> mailing list. + 0. Structure of PCI drivers ~~~ -There exist two kinds of PCI drivers: new-style ones (which leave most of -probing for devices to the PCI layer and support online insertion and removal -of devices [thus supporting PCI, hot-pluggable PCI and CardBus in a single -driver]) and old-style ones which just do all the probing themselves. Unless -you have a very good reason to do so, please don't use the old way of probing -in any new code. After the driver finds the devices it wishes to operate -on (either the old or the new way), it needs to perform the following steps: +PCI drivers "discover" PCI devices in a system via pci_register_driver(). +Actually, it's the other way around. When the PCI generic code discovers +a new device, the driver with a matching "description" will be notified. +Details on this below. + +pci_register_driver() leaves most of the probing for devices to +the PCI layer and supports online insertion/removal of devices [thus +supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. +pci_register_driver() call requires passing in a table of function +pointers and thus dictates the high level structure of a driver. + +Once the driver knows about a PCI device and takes ownership, the +driver generally needs to perform the following initialization: Enable the device - Access device configuration space - Discover resources (addresses and IRQ numbers) provided by the device - Allocate these resources - Communicate with the device + Request MMIO/IOP resources + Set the DMA mask size (for both coherent and streaming DMA) + Allocate and initialize shared control data (pci_allocate_coherent()) + Access device configuration space (if needed) + Register IRQ handler (request_irq()) + Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) + Enable DMA/processing engines + +When done using
Re: [PATCH] Update Documentation/pci.txt v7
On Sun, Dec 24, 2006 at 11:16:22AM -0800, Randy Dunlap wrote:
> On Sat, 23 Dec 2006 23:07:26 -0700 Grant Grundler wrote:
>
> > +10. Legacy I/O port free driver
> > +~~~
>
> That subject (and patches with similar subject) confuses me.
> It's difficult to associate the adjectives correctly.
Agreed. This was the original section name and I didn't
have a better idea.
> I suppose it just needs some hyphens/dashes, like:
>
> 10. Legacy-I/O-port-free driver
>
> but that's ETOOMUCH. Maybe ?
>
> 10. Stop using legacy I/O space
Yeah, that is good too.
I changed it to "10. pci_enable_device_bars() and Legacy I/O Port space".
The goal of this section is to introduce the new PCI function
and why one should use it.
...
> > +Thus, timing sensitive code should add readl() where the CPU is
> > +expected to wait before doing other work. The classic "bit banging"
> > +sequence works fine for I/O Port space:
> > +
> > + for (i=8; --i; val >>= 1) {
>
> Please use: i = 8;
> to match CodingStyle. (and below)
DefinitelySorry, I thought someone already asked me to change this.
I thought I did. Changed now in both cases.
> Rest looks good to me.
v8 will be posted shortly.
thanks Randy!
grant
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Update Documentation/pci.txt v7
On Sun, Dec 24, 2006 at 11:16:22AM -0800, Randy Dunlap wrote:
On Sat, 23 Dec 2006 23:07:26 -0700 Grant Grundler wrote:
+10. Legacy I/O port free driver
+~~~
That subject (and patches with similar subject) confuses me.
It's difficult to associate the adjectives correctly.
Agreed. This was the original section name and I didn't
have a better idea.
I suppose it just needs some hyphens/dashes, like:
10. Legacy-I/O-port-free driver
but that's ETOOMUCH. Maybe ?
10. Stop using legacy I/O space
Yeah, that is good too.
I changed it to 10. pci_enable_device_bars() and Legacy I/O Port space.
The goal of this section is to introduce the new PCI function
and why one should use it.
...
+Thus, timing sensitive code should add readl() where the CPU is
+expected to wait before doing other work. The classic bit banging
+sequence works fine for I/O Port space:
+
+ for (i=8; --i; val = 1) {
Please use: i = 8;
to match CodingStyle. (and below)
DefinitelySorry, I thought someone already asked me to change this.
I thought I did. Changed now in both cases.
Rest looks good to me.
v8 will be posted shortly.
thanks Randy!
grant
-
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Update Documentation/pci.txt v7
On Sat, Dec 23, 2006 at 11:07:26PM -0700, Grant Grundler wrote: final patch v7 and commit log entry appended below. :) v8 adds 2cd round of feedback from Randy Dunlap. Going once...twice... ;) Full pci.txt text is easier to review at: http://www.parisc-linux.org/~grundler/Documentation/ Same place. grant Rewrite Documentation/pci.txt: o restructure document to match how API is used when writing init code. o update to reflect changes in struct pci_driver function pointers. o removed language on new style vs old style device discovery. Old style is now deprecated. Don't use it. Left description in to document existing driver behaviors. o add section Legacy I/O Port free driver by Kenji Kaneshige http://lkml.org/lkml/2006/11/22/25 (renamed to pci_enable_device_bars() and Legacy I/O Port space) o add MMIO space and write posting section to help avoid common pitfall when converting drivers from IO Port space to MMIO space. Orignally posted http://lkml.org/lkml/2006/2/27/24 o many typo/grammer/spelling corrections from Randy Dunlap o two more spelling corrections from Stephan Richter o fix CodingStyle as per Randy Dunlap Signed-off-by: Grant Grundler [EMAIL PROTECTED] diff --git a/Documentation/pci.txt b/Documentation/pci.txt index 2b395e4..0d33d80 100644 --- a/Documentation/pci.txt +++ b/Documentation/pci.txt @@ -1,142 +1,231 @@ -How To Write Linux PCI Drivers - by Martin Mares [EMAIL PROTECTED] on 07-Feb-2000 + How To Write Linux PCI Drivers + + by Martin Mares [EMAIL PROTECTED] on 07-Feb-2000 + updated by Grant Grundler [EMAIL PROTECTED] on 23-Dec-2006 -The world of PCI is vast and it's full of (mostly unpleasant) surprises. -Different PCI devices have different requirements and different bugs -- -because of this, the PCI support layer in Linux kernel is not as trivial -as one would wish. This short pamphlet tries to help all potential driver -authors find their way through the deep forests of PCI handling. +The world of PCI is vast and full of (mostly unpleasant) surprises. +Since each CPU architecture implements different chip-sets and PCI devices +have different requirements (erm, features), the result is the PCI support +in the Linux kernel is not as trivial as one would wish. This short paper +tries to introduce all potential driver authors to Linux APIs for +PCI device drivers. + +A more complete resource is the third edition of Linux Device Drivers +by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. +LDD3 is available for free (under Creative Commons License) from: + + http://lwn.net/Kernel/LDD3/ + +However, keep in mind that all documents are subject to bit rot. +Refer to the source code if things are not working as described here. + +Please send questions/comments/patches about Linux PCI API to the +Linux PCI [EMAIL PROTECTED] mailing list. + 0. Structure of PCI drivers ~~~ -There exist two kinds of PCI drivers: new-style ones (which leave most of -probing for devices to the PCI layer and support online insertion and removal -of devices [thus supporting PCI, hot-pluggable PCI and CardBus in a single -driver]) and old-style ones which just do all the probing themselves. Unless -you have a very good reason to do so, please don't use the old way of probing -in any new code. After the driver finds the devices it wishes to operate -on (either the old or the new way), it needs to perform the following steps: +PCI drivers discover PCI devices in a system via pci_register_driver(). +Actually, it's the other way around. When the PCI generic code discovers +a new device, the driver with a matching description will be notified. +Details on this below. + +pci_register_driver() leaves most of the probing for devices to +the PCI layer and supports online insertion/removal of devices [thus +supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. +pci_register_driver() call requires passing in a table of function +pointers and thus dictates the high level structure of a driver. + +Once the driver knows about a PCI device and takes ownership, the +driver generally needs to perform the following initialization: Enable the device - Access device configuration space - Discover resources (addresses and IRQ numbers) provided by the device - Allocate these resources - Communicate with the device + Request MMIO/IOP resources + Set the DMA mask size (for both coherent and streaming DMA) + Allocate and initialize shared control data (pci_allocate_coherent()) + Access device configuration space (if needed) + Register IRQ handler (request_irq()) + Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) + Enable DMA/processing engines + +When done using the device, and perhaps the module
Re: [PATCH] Update Documentation/pci.txt v7
On Mon, Dec 25, 2006 at 01:06:35AM -0700, Grant Grundler wrote: On Sat, Dec 23, 2006 at 11:07:26PM -0700, Grant Grundler wrote: final patch v7 and commit log entry appended below. :) v8 adds 2cd round of feedback from Randy Dunlap. Obviously the subject line is stale...it's really v8 now. It's just way past my bedtime again. grant Going once...twice... ;) Full pci.txt text is easier to review at: http://www.parisc-linux.org/~grundler/Documentation/ Same place. grant Rewrite Documentation/pci.txt: o restructure document to match how API is used when writing init code. o update to reflect changes in struct pci_driver function pointers. o removed language on new style vs old style device discovery. Old style is now deprecated. Don't use it. Left description in to document existing driver behaviors. o add section Legacy I/O Port free driver by Kenji Kaneshige http://lkml.org/lkml/2006/11/22/25 (renamed to pci_enable_device_bars() and Legacy I/O Port space) o add MMIO space and write posting section to help avoid common pitfall when converting drivers from IO Port space to MMIO space. Orignally posted http://lkml.org/lkml/2006/2/27/24 o many typo/grammer/spelling corrections from Randy Dunlap o two more spelling corrections from Stephan Richter o fix CodingStyle as per Randy Dunlap Signed-off-by: Grant Grundler [EMAIL PROTECTED] diff --git a/Documentation/pci.txt b/Documentation/pci.txt index 2b395e4..0d33d80 100644 --- a/Documentation/pci.txt +++ b/Documentation/pci.txt @@ -1,142 +1,231 @@ - How To Write Linux PCI Drivers -by Martin Mares [EMAIL PROTECTED] on 07-Feb-2000 + How To Write Linux PCI Drivers + + by Martin Mares [EMAIL PROTECTED] on 07-Feb-2000 + updated by Grant Grundler [EMAIL PROTECTED] on 23-Dec-2006 -The world of PCI is vast and it's full of (mostly unpleasant) surprises. -Different PCI devices have different requirements and different bugs -- -because of this, the PCI support layer in Linux kernel is not as trivial -as one would wish. This short pamphlet tries to help all potential driver -authors find their way through the deep forests of PCI handling. +The world of PCI is vast and full of (mostly unpleasant) surprises. +Since each CPU architecture implements different chip-sets and PCI devices +have different requirements (erm, features), the result is the PCI support +in the Linux kernel is not as trivial as one would wish. This short paper +tries to introduce all potential driver authors to Linux APIs for +PCI device drivers. + +A more complete resource is the third edition of Linux Device Drivers +by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. +LDD3 is available for free (under Creative Commons License) from: + + http://lwn.net/Kernel/LDD3/ + +However, keep in mind that all documents are subject to bit rot. +Refer to the source code if things are not working as described here. + +Please send questions/comments/patches about Linux PCI API to the +Linux PCI [EMAIL PROTECTED] mailing list. + 0. Structure of PCI drivers ~~~ -There exist two kinds of PCI drivers: new-style ones (which leave most of -probing for devices to the PCI layer and support online insertion and removal -of devices [thus supporting PCI, hot-pluggable PCI and CardBus in a single -driver]) and old-style ones which just do all the probing themselves. Unless -you have a very good reason to do so, please don't use the old way of probing -in any new code. After the driver finds the devices it wishes to operate -on (either the old or the new way), it needs to perform the following steps: +PCI drivers discover PCI devices in a system via pci_register_driver(). +Actually, it's the other way around. When the PCI generic code discovers +a new device, the driver with a matching description will be notified. +Details on this below. + +pci_register_driver() leaves most of the probing for devices to +the PCI layer and supports online insertion/removal of devices [thus +supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. +pci_register_driver() call requires passing in a table of function +pointers and thus dictates the high level structure of a driver. + +Once the driver knows about a PCI device and takes ownership, the +driver generally needs to perform the following initialization: Enable the device - Access device configuration space - Discover resources (addresses and IRQ numbers) provided by the device - Allocate these resources - Communicate with the device + Request MMIO/IOP resources + Set the DMA mask size (for both coherent and streaming DMA) + Allocate and initialize shared control data (pci_allocate_coherent()) +
Re: [PATCH] Update Documentation/pci.txt v7
Grant Grundler wrote: On Sat, Dec 23, 2006 at 11:07:26PM -0700, Grant Grundler wrote: final patch v7 and commit log entry appended below. :) v8 adds 2cd round of feedback from Randy Dunlap. Going once...twice... ;) Full pci.txt text is easier to review at: http://www.parisc-linux.org/~grundler/Documentation/ Same place. grant Rewrite Documentation/pci.txt: o restructure document to match how API is used when writing init code. o update to reflect changes in struct pci_driver function pointers. o removed language on new style vs old style device discovery. Old style is now deprecated. Don't use it. Left description in to document existing driver behaviors. o add section Legacy I/O Port free driver by Kenji Kaneshige http://lkml.org/lkml/2006/11/22/25 (renamed to pci_enable_device_bars() and Legacy I/O Port space) Thank you for updating this. It looks much better. Thank you again, Kenji Kaneshige - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Update Documentation/pci.txt v7
On Sat, 23 Dec 2006 23:07:26 -0700 Grant Grundler wrote:
> +10. Legacy I/O port free driver
> +~~~
That subject (and patches with similar subject) confuses me.
It's difficult to associate the adjectives correctly.
I suppose it just needs some hyphens/dashes, like:
10. Legacy-I/O-port-free driver
but that's ETOOMUCH. Maybe ?
10. Stop using legacy I/O space
> +Large servers may not be able to provide I/O port resources to all PCI
> +devices. I/O Port space is only 64KB on Intel Architecture[1] and is
> +likely also fragmented since the I/O base register of PCI-to-PCI
> +bridge will usually be aligned to a 4KB boundary[2]. On such systems,
> +pci_enable_device() and pci_request_region() will fail when
> +attempting to enable I/O Port regions that don't have I/O Port
> +resources assigned.
> +11. MMIO Space and "Write Posting"
> +~~
> +Converting a driver from using I/O Port space to using MMIO space
> +often requires some additional changes. Specifically, "write posting"
> +needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
> +already do this. I/O Port space guarantees write transactions reach the PCI
> +device before the CPU can continue. Writes to MMIO space allow the CPU
> +to continue before the transaction reaches the PCI device. HW weenies
> +call this "Write Posting" because the write completion is "posted" to
> +the CPU before the transaction has reached its destination.
> +
> +Thus, timing sensitive code should add readl() where the CPU is
> +expected to wait before doing other work. The classic "bit banging"
> +sequence works fine for I/O Port space:
> +
> + for (i=8; --i; val >>= 1) {
Please use: i = 8;
to match CodingStyle. (and below)
> + outb(val & 1, ioport_reg); /* write bit */
> + udelay(10);
> + }
> +
> +The same sequence for MMIO space should be:
> +
> + for (i=8; --i; val >>= 1) {
> + writeb(val & 1, mmio_reg); /* write bit */
> + readb(safe_mmio_reg); /* flush posted write */
> + udelay(10);
> + }
Rest looks good to me.
---
~Randy
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] Update Documentation/pci.txt v7
On Sat, 23 Dec 2006 23:07:26 -0700 Grant Grundler wrote:
+10. Legacy I/O port free driver
+~~~
That subject (and patches with similar subject) confuses me.
It's difficult to associate the adjectives correctly.
I suppose it just needs some hyphens/dashes, like:
10. Legacy-I/O-port-free driver
but that's ETOOMUCH. Maybe ?
10. Stop using legacy I/O space
+Large servers may not be able to provide I/O port resources to all PCI
+devices. I/O Port space is only 64KB on Intel Architecture[1] and is
+likely also fragmented since the I/O base register of PCI-to-PCI
+bridge will usually be aligned to a 4KB boundary[2]. On such systems,
+pci_enable_device() and pci_request_region() will fail when
+attempting to enable I/O Port regions that don't have I/O Port
+resources assigned.
+11. MMIO Space and Write Posting
+~~
+Converting a driver from using I/O Port space to using MMIO space
+often requires some additional changes. Specifically, write posting
+needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
+already do this. I/O Port space guarantees write transactions reach the PCI
+device before the CPU can continue. Writes to MMIO space allow the CPU
+to continue before the transaction reaches the PCI device. HW weenies
+call this Write Posting because the write completion is posted to
+the CPU before the transaction has reached its destination.
+
+Thus, timing sensitive code should add readl() where the CPU is
+expected to wait before doing other work. The classic bit banging
+sequence works fine for I/O Port space:
+
+ for (i=8; --i; val = 1) {
Please use: i = 8;
to match CodingStyle. (and below)
+ outb(val 1, ioport_reg); /* write bit */
+ udelay(10);
+ }
+
+The same sequence for MMIO space should be:
+
+ for (i=8; --i; val = 1) {
+ writeb(val 1, mmio_reg); /* write bit */
+ readb(safe_mmio_reg); /* flush posted write */
+ udelay(10);
+ }
Rest looks good to me.
---
~Randy
-
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
[PATCH] Update Documentation/pci.txt v7
[ dropped e1000-devel and linux-scsi from CC list] On Mon, Dec 18, 2006 at 12:11:33AM -0700, Grant Grundler wrote: > Full version of pci.txt (v6 is 677 lines): > http://www.parisc-linux.org/~grundler/Documentation/pci.txt-06 > > I've appended patch v6 (823 lines!) and commit log entry is below. "final" patch v7 and commit log entry appended below. :) Full pci.txt text is easier to review at: http://www.parisc-linux.org/~grundler/Documentation/ This incoporates all changes, grammer and spelling corrections suggested by Randy Dunlap (thank you again!). Also some additional spelling correction by Stephan Richter (also thank you!) and other misc changes (white space, section numbering for chap 3, replace "aka" with "a.k.a.", etc). thanks, grant Rewrite Documentation/pci.txt: o restructure document to match how API is used when writing init code. o update to reflect changes in struct pci_driver function pointers. o removed language on "new style vs old style" device discovery. "Old style" is now deprecated. Don't use it. Left description in to document existing driver behaviors. o add section "Legacy I/O Port free driver" by Kenji Kaneshige http://lkml.org/lkml/2006/11/22/25 o add "MMIO space and write posting" section to help avoid common pitfall when converting drivers from IO Port space to MMIO space. Orignally posted http://lkml.org/lkml/2006/2/27/24 o many typo/grammer/spelling corrections from Randy Dunlap o two more spelling corrections from Stephan Richter Signed-off-by: Grant Grundler <[EMAIL PROTECTED]> diff --git a/Documentation/pci.txt b/Documentation/pci.txt index 2b395e4..397e3fb 100644 --- a/Documentation/pci.txt +++ b/Documentation/pci.txt @@ -1,142 +1,231 @@ -How To Write Linux PCI Drivers - by Martin Mares <[EMAIL PROTECTED]> on 07-Feb-2000 + How To Write Linux PCI Drivers + + by Martin Mares <[EMAIL PROTECTED]> on 07-Feb-2000 + updated by Grant Grundler <[EMAIL PROTECTED]> on 23-Dec-2006 -The world of PCI is vast and it's full of (mostly unpleasant) surprises. -Different PCI devices have different requirements and different bugs -- -because of this, the PCI support layer in Linux kernel is not as trivial -as one would wish. This short pamphlet tries to help all potential driver -authors find their way through the deep forests of PCI handling. +The world of PCI is vast and full of (mostly unpleasant) surprises. +Since each CPU architecture implements different chip-sets and PCI devices +have different requirements (erm, "features"), the result is the PCI support +in the Linux kernel is not as trivial as one would wish. This short paper +tries to introduce all potential driver authors to Linux APIs for +PCI device drivers. + +A more complete resource is the third edition of "Linux Device Drivers" +by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. +LDD3 is available for free (under Creative Commons License) from: + + http://lwn.net/Kernel/LDD3/ + +However, keep in mind that all documents are subject to "bit rot". +Refer to the source code if things are not working as described here. + +Please send questions/comments/patches about Linux PCI API to the +"Linux PCI" <[EMAIL PROTECTED]> mailing list. + 0. Structure of PCI drivers ~~~ -There exist two kinds of PCI drivers: new-style ones (which leave most of -probing for devices to the PCI layer and support online insertion and removal -of devices [thus supporting PCI, hot-pluggable PCI and CardBus in a single -driver]) and old-style ones which just do all the probing themselves. Unless -you have a very good reason to do so, please don't use the old way of probing -in any new code. After the driver finds the devices it wishes to operate -on (either the old or the new way), it needs to perform the following steps: +PCI drivers "discover" PCI devices in a system via pci_register_driver(). +Actually, it's the other way around. When the PCI generic code discovers +a new device, the driver with a matching "description" will be notified. +Details on this below. + +pci_register_driver() leaves most of the probing for devices to +the PCI layer and supports online insertion/removal of devices [thus +supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. +pci_register_driver() call requires passing in a table of function +pointers and thus dictates the high level structure of a driver. + +Once the driver knows about a PCI device and takes ownership, the +driver generally needs to perform the following initialization: Enable the device - Access device configuration space - Discover resources (addresses and IRQ numbers) provided by the device - Allocate these resources - Communicate with the device + Request MMIO/IOP resources + Set the DMA mask
[PATCH] Update Documentation/pci.txt v7
[ dropped e1000-devel and linux-scsi from CC list] On Mon, Dec 18, 2006 at 12:11:33AM -0700, Grant Grundler wrote: Full version of pci.txt (v6 is 677 lines): http://www.parisc-linux.org/~grundler/Documentation/pci.txt-06 I've appended patch v6 (823 lines!) and commit log entry is below. final patch v7 and commit log entry appended below. :) Full pci.txt text is easier to review at: http://www.parisc-linux.org/~grundler/Documentation/ This incoporates all changes, grammer and spelling corrections suggested by Randy Dunlap (thank you again!). Also some additional spelling correction by Stephan Richter (also thank you!) and other misc changes (white space, section numbering for chap 3, replace aka with a.k.a., etc). thanks, grant Rewrite Documentation/pci.txt: o restructure document to match how API is used when writing init code. o update to reflect changes in struct pci_driver function pointers. o removed language on new style vs old style device discovery. Old style is now deprecated. Don't use it. Left description in to document existing driver behaviors. o add section Legacy I/O Port free driver by Kenji Kaneshige http://lkml.org/lkml/2006/11/22/25 o add MMIO space and write posting section to help avoid common pitfall when converting drivers from IO Port space to MMIO space. Orignally posted http://lkml.org/lkml/2006/2/27/24 o many typo/grammer/spelling corrections from Randy Dunlap o two more spelling corrections from Stephan Richter Signed-off-by: Grant Grundler [EMAIL PROTECTED] diff --git a/Documentation/pci.txt b/Documentation/pci.txt index 2b395e4..397e3fb 100644 --- a/Documentation/pci.txt +++ b/Documentation/pci.txt @@ -1,142 +1,231 @@ -How To Write Linux PCI Drivers - by Martin Mares [EMAIL PROTECTED] on 07-Feb-2000 + How To Write Linux PCI Drivers + + by Martin Mares [EMAIL PROTECTED] on 07-Feb-2000 + updated by Grant Grundler [EMAIL PROTECTED] on 23-Dec-2006 -The world of PCI is vast and it's full of (mostly unpleasant) surprises. -Different PCI devices have different requirements and different bugs -- -because of this, the PCI support layer in Linux kernel is not as trivial -as one would wish. This short pamphlet tries to help all potential driver -authors find their way through the deep forests of PCI handling. +The world of PCI is vast and full of (mostly unpleasant) surprises. +Since each CPU architecture implements different chip-sets and PCI devices +have different requirements (erm, features), the result is the PCI support +in the Linux kernel is not as trivial as one would wish. This short paper +tries to introduce all potential driver authors to Linux APIs for +PCI device drivers. + +A more complete resource is the third edition of Linux Device Drivers +by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. +LDD3 is available for free (under Creative Commons License) from: + + http://lwn.net/Kernel/LDD3/ + +However, keep in mind that all documents are subject to bit rot. +Refer to the source code if things are not working as described here. + +Please send questions/comments/patches about Linux PCI API to the +Linux PCI [EMAIL PROTECTED] mailing list. + 0. Structure of PCI drivers ~~~ -There exist two kinds of PCI drivers: new-style ones (which leave most of -probing for devices to the PCI layer and support online insertion and removal -of devices [thus supporting PCI, hot-pluggable PCI and CardBus in a single -driver]) and old-style ones which just do all the probing themselves. Unless -you have a very good reason to do so, please don't use the old way of probing -in any new code. After the driver finds the devices it wishes to operate -on (either the old or the new way), it needs to perform the following steps: +PCI drivers discover PCI devices in a system via pci_register_driver(). +Actually, it's the other way around. When the PCI generic code discovers +a new device, the driver with a matching description will be notified. +Details on this below. + +pci_register_driver() leaves most of the probing for devices to +the PCI layer and supports online insertion/removal of devices [thus +supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. +pci_register_driver() call requires passing in a table of function +pointers and thus dictates the high level structure of a driver. + +Once the driver knows about a PCI device and takes ownership, the +driver generally needs to perform the following initialization: Enable the device - Access device configuration space - Discover resources (addresses and IRQ numbers) provided by the device - Allocate these resources - Communicate with the device + Request MMIO/IOP resources + Set the DMA mask size (for both coherent and streaming DMA)
