On Wed, Sep 12, 2018 at 06:11:49PM -0600, Logan Gunthorpe wrote: > Add a restructured text file describing how to write drivers > with support for P2P DMA transactions. The document describes > how to use the APIs that were added in the previous few > commits. > > Also adds an index for the PCI documentation tree even though this > is the only PCI document that has been converted to restructured text > at this time. > > Signed-off-by: Logan Gunthorpe <logang@xxxxxxxxxxxx> Acked-by: Bjorn Helgaas <bhelgaas@xxxxxxxxxx> > +With the client list in hand, the orchestrator may then call > +:c:func:`pci_p2pmem_find()` to obtain a published P2P memory provider > +that is supported (behind the same root port) as all the clients. If more > +than one provider is supported, the one nearest to all the clients will > +be chosen first. If there are more than one provider is an equal distance s/If there are more/If more/ > +away, the one returned will be chosen at random. This function returns the PCI s/the one returned will be chosen at random/one will be chosen arbitrarily/ ? (I doubt it's really random) > +device to use for the provider with a reference taken and therefore > +when it's no longer needed it should be returned with pci_dev_put(). > +Struct Page Caveats > +------------------- > + > +Driver writers should be very careful about not passing these special > +struct pages to code that isn't prepared for it. At this time, the kernel > +interfaces do not have any checks for ensuring this. This obviously > +precludes passing these pages to userspace. Sounds like landmines here since the reader probably can't translate "code that isn't prepared for it" into a list of interfaces that are off-limits. But that's a VM issue that is above my pay grade, so I'm not suggesting any change; just pointing out something that makes me wonder "hmmm..., how would I act on this?" > +P2P memory is also technically IO memory but should never have any side > +effects behind it. Thus, the order of loads and stores should not be important > +and ioreadX(), iowriteX() and friends should not be necessary. > +However, as the memory is not cache coherent, if access ever needs to > +be protected by a spinlock then :c:func:`mmiowb()` must be used before > +unlocking the lock. (See ACQUIRES VS I/O ACCESSES in > +Documentation/memory-barriers.txt)
