svn commit: r53377 - head/en_US.ISO8859-1/books/arch-handbook/pci

Benedict Reuschling <[email protected]>
Newsgroups gmane.os.freebsd.devel.cvs.doc
Message-ID <[email protected]> 
Author: bcr
Date: Thu Sep  5 20:22:58 2019
New Revision: 53377
URL: https://svnweb.freebsd.org/changeset/doc/53377

Log:
  Clean up the following igor warnings:
  - wrap long line
  - add blank line after previous line
  - use tabs instead of spaces
  - straggling <tag>
  
  Event:	    vBSDcon FreeBSD Hackathon

Modified:
  head/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml

Modified: head/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml	Thu Sep  5 19:40:43 2019	(r53376)
+++ head/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml	Thu Sep  5 20:22:58 2019	(r53377)
@@ -4,7 +4,9 @@
 
      $FreeBSD$
 -->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="pci">
+<chapter xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+  xml:id="pci">
   <title>PCI Devices</title>
 
   <indexterm><primary>PCI bus</primary></indexterm>
@@ -20,9 +22,10 @@
       to any of them.</para>
 
     <sect2>
-      <title>Sample Driver Source (<filename>mypci.c</filename>)</title>
+      <title>Sample Driver Source
+	(<filename>mypci.c</filename>)</title>
 
-<programlisting>/*
+      <programlisting>/*
  * Simple KLD to play with the PCI functions.
  *
  * Murray Stokely
@@ -232,7 +235,7 @@ DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass
     <sect2>
       <title><filename>Makefile</filename> for Sample Driver</title>
 
-<programlisting># Makefile for mypci driver
+      <programlisting># Makefile for mypci driver
 
 KMOD=	mypci
 SRCS=	mypci.c
@@ -251,13 +254,16 @@ SRCS+=	device_if.h bus_if.h pci_if.h
 
     <sect2>
       <title>Additional Resources</title>
+
       <itemizedlist>
-	<listitem><simpara><link xlink:href="http://www.pcisig.org/">PCI
-	  Special Interest Group</link></simpara></listitem>
+	<listitem>
+	  <simpara><link xlink:href="http://www.pcisig.org/">PCI
+	    Special Interest Group</link></simpara>
+	</listitem>
 
 	<listitem><simpara>PCI System Architecture, Fourth Edition by
-	  Tom Shanley, et al.</simpara></listitem>
-
+	    Tom Shanley, et al.</simpara>
+	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
@@ -265,7 +271,8 @@ SRCS+=	device_if.h bus_if.h pci_if.h
   <sect1 xml:id="pci-bus">
     <title>Bus Resources</title>
 
-    <indexterm><primary>PCI bus</primary><secondary>resources</secondary></indexterm>
+    <indexterm><primary>PCI
+      bus</primary><secondary>resources</secondary></indexterm>
     <para>FreeBSD provides an object-oriented mechanism for requesting
       resources from a parent bus.  Almost all devices will be a child
       member of some sort of bus (PCI, ISA, USB, SCSI, etc) and these
@@ -275,18 +282,20 @@ SRCS+=	device_if.h bus_if.h pci_if.h
     <sect2>
       <title>Base Address Registers</title>
 
-      <indexterm><primary>PCI bus</primary><secondary>Base Address Registers</secondary></indexterm>
+      <indexterm><primary>PCI bus</primary><secondary>Base Address
+	Registers</secondary></indexterm>
 
       <para>To do anything particularly useful with a PCI device you
-      will need to obtain the <emphasis>Base Address
-      Registers</emphasis> (BARs) from the PCI Configuration space.
-      The PCI-specific details of obtaining the BAR are abstracted in
-      the <function>bus_alloc_resource()</function> function.</para>
+	will need to obtain the <emphasis>Base Address
+	  Registers</emphasis> (BARs) from the PCI Configuration
+	    space.  The PCI-specific details of obtaining the BAR are
+	abstracted in the <function>bus_alloc_resource()</function>
+	function.</para>
 
       <para>For example, a typical driver might have something similar
-      to this in the <function>attach()</function> function:</para>
+	to this in the <function>attach()</function> function:</para>
 
-<programlisting>    sc-&gt;bar0id = PCIR_BAR(0);
+      <programlisting>    sc-&gt;bar0id = PCIR_BAR(0);
     sc-&gt;bar0res = bus_alloc_resource(dev, SYS_RES_MEMORY, &amp;sc-&gt;bar0id,
 				  0, ~0, 1, RF_ACTIVE);
     if (sc-&gt;bar0res == NULL) {
@@ -309,34 +318,33 @@ SRCS+=	device_if.h bus_if.h pci_if.h
     sc-&gt;bar1_bh = rman_get_bushandle(sc-&gt;bar1res);</programlisting>
 
       <para>Handles for each base address register are kept in the
-        <varname remap="structname">softc</varname> structure so that they can be
-        used to write to the device later.</para>
+	<varname remap="structname">softc</varname> structure so that
+	they can be used to write to the device later.</para>
 
       <para>These handles can then be used to read or write from the
-        device registers with the <function>bus_space_*</function>
-        functions.  For example, a driver might contain a shorthand
-        function to read from a board specific register like this:</para>
+	device registers with the <function>bus_space_*</function>
+	functions.  For example, a driver might contain a shorthand
+	function to read from a board specific register like
+	this:</para>
 
-<programlisting>uint16_t
+      <programlisting>uint16_t
 board_read(struct ni_softc *sc, uint16_t address)
 {
     return bus_space_read_2(sc-&gt;bar1_bt, sc-&gt;bar1_bh, address);
-}
-</programlisting>
+}</programlisting>
 
       <para>Similarly, one could write to the registers with:</para>
 
-<programlisting>void
+      <programlisting>void
 board_write(struct ni_softc *sc, uint16_t address, uint16_t value)
 {
     bus_space_write_2(sc-&gt;bar1_bt, sc-&gt;bar1_bh, address, value);
-}
-</programlisting>
+}</programlisting>
 
       <para>These functions exist in 8bit, 16bit, and 32bit versions
-        and you should use
-        <function>bus_space_{read|write}_{1|2|4}</function>
-        accordingly.</para>
+	and you should use
+	<function>bus_space_{read|write}_{1|2|4}</function>
+	accordingly.</para>
 
       <note>
 	<para>In FreeBSD 7.0 and later, you can use the
@@ -345,31 +353,33 @@ board_write(struct ni_softc *sc, uint16_t address, uin
 	  <function>bus_*</function> functions take a <type>struct
 	  resource *</type> pointer instead of a bus tag and handle.
 	  Thus, you could drop the bus tag and bus handle members from
-	  the <varname remap="structname">softc</varname> and rewrite the
-	  <function>board_read()</function> function as:</para>
+	  the <varname remap="structname">softc</varname> and rewrite
+	  the <function>board_read()</function> function as:</para>
 
-<programlisting>uint16_t
+	<programlisting>uint16_t
 board_read(struct ni_softc *sc, uint16_t address)
 {
 	return (bus_read(sc-&gt;bar1res, address));
-}
-</programlisting>
+}</programlisting>
       </note>
     </sect2>
+
     <sect2>
       <title>Interrupts</title>
 
-      <indexterm><primary>PCI bus</primary><secondary>interrupts</secondary></indexterm>
+      <indexterm><primary>PCI
+	bus</primary><secondary>interrupts</secondary></indexterm>
+
       <para>Interrupts are allocated from the object-oriented bus code
-        in a way similar to the memory resources.  First an IRQ
-        resource must be allocated from the parent bus, and then the
-        interrupt handler must be set up to deal with this IRQ.</para>
+	in a way similar to the memory resources.  First an IRQ
+	resource must be allocated from the parent bus, and then the
+	interrupt handler must be set up to deal with this IRQ.</para>
 
       <para>Again, a sample from a device
-        <function>attach()</function> function says more than
-        words.</para>
+	<function>attach()</function> function says more than
+	words.</para>
 
-<programlisting>/* Get the IRQ resource */
+      <programlisting>/* Get the IRQ resource */
 
     sc-&gt;irqid = 0x0;
     sc-&gt;irqres = bus_alloc_resource(dev, SYS_RES_IRQ, &amp;(sc-&gt;irqid),
@@ -387,67 +397,62 @@ board_read(struct ni_softc *sc, uint16_t address)
     if (error) {
 	printf("Couldn't set up irq\n");
 	goto fail4;
-    }
-</programlisting>
+    }</programlisting>
 
       <para>Some care must be taken in the detach routine of the
-      driver.  You must quiesce the device's interrupt stream, and
-      remove the interrupt handler.  Once
-      <function>bus_teardown_intr()</function> has returned, you
-      know that your interrupt handler will no longer be called and
-      that all threads that might have been executing this interrupt handler
-      have returned.  Since this function can sleep, you must not hold
-      any mutexes when calling this function.</para>
-
+	driver.  You must quiesce the device's interrupt stream, and
+	remove the interrupt handler.  Once
+	<function>bus_teardown_intr()</function> has returned, you
+	know that your interrupt handler will no longer be called and
+	that all threads that might have been executing this interrupt
+	handler have returned.  Since this function can sleep, you
+	must not hold any mutexes when calling this function.</para>
     </sect2>
 
     <sect2>
       <title>DMA</title>
 
-      <indexterm><primary>PCI bus</primary><secondary>DMA</secondary></indexterm>
+      <indexterm><primary>PCI
+	bus</primary><secondary>DMA</secondary></indexterm>
+
       <para>This section is obsolete, and present only for historical
-      reasons.  The proper methods for dealing with these issues is to
-      use the <function>bus_space_dma*()</function> functions instead.
-      This paragraph can be removed when this section is updated to reflect
-      that usage.  However, at the moment, the API is in a bit of
-      flux, so once that settles down, it would be good to update this
-      section to reflect that.</para>
+	reasons.  The proper methods for dealing with these issues is
+	to use the <function>bus_space_dma*()</function> functions
+	instead.  This paragraph can be removed when this section is
+	updated to reflect that usage.  However, at the moment, the
+	API is in a bit of flux, so once that settles down, it would
+	be good to update this section to reflect that.</para>
 
       <para>On the PC, peripherals that want to do bus-mastering DMA
-      must deal with physical addresses.  This is a problem since
-      FreeBSD uses virtual memory and deals almost exclusively with
-      virtual addresses.  Fortunately, there is a function,
-      <function>vtophys()</function> to help.</para>
+	must deal with physical addresses.  This is a problem since
+	FreeBSD uses virtual memory and deals almost exclusively with
+	virtual addresses.  Fortunately, there is a function,
+	<function>vtophys()</function> to help.</para>
 
-<programlisting>#include &lt;vm/vm.h&gt;
+      <programlisting>#include &lt;vm/vm.h&gt;
 #include &lt;vm/pmap.h&gt;
 
-#define vtophys(virtual_address) (...)
-</programlisting>
+#define vtophys(virtual_address) (...)</programlisting>
 
       <para>The solution is a bit different on the alpha however, and
-        what we really want is a function called
-        <function>vtobus()</function>.</para>
+	what we really want is a function called
+	<function>vtobus()</function>.</para>
 
-<programlisting>#if defined(__alpha__)
+      <programlisting>#if defined(__alpha__)
 #define vtobus(va)      alpha_XXX_dmamap((vm_offset_t)va)
 #else
 #define vtobus(va)      vtophys(va)
-#endif
-</programlisting>
-
+#endif</programlisting>
     </sect2>
 
     <sect2>
       <title>Deallocating Resources</title>
 
       <para>It is very important to deallocate all of the resources
-        that were allocated during <function>attach()</function>.
-        Care must be taken to deallocate the correct stuff even on a
-        failure condition so that the system will remain usable while
-        your driver dies.</para>
-
+	that were allocated during <function>attach()</function>.
+	Care must be taken to deallocate the correct stuff even on a
+	failure condition so that the system will remain usable while
+	your driver dies.</para>
     </sect2>
   </sect1>
-
 </chapter>
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"
lmpx.com only provides a reader for public news (NNTP) servers. It is not affiliated with the servers or forums shown here and is not responsible for the content of articles, which is written by their respective authors.