Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit c1aac62f authored by Linus Torvalds's avatar Linus Torvalds
Browse files

Merge tag 'docs-4.11' of git://git.lwn.net/linux 

Pull documentation updates from Jonathan Corbet:
 "A slightly quieter cycle for documentation this time around.

  Three more DocBook template files have been converted to RST; only 21
  to go. There are various build improvements and the usual array of
  documentation improvements and fixes"

* tag 'docs-4.11' of git://git.lwn.net/linux: (44 commits)
  docs / driver-api: Fix structure references in device_link.rst
  PM / docs: Fix structure references in device.rst
  Add a target to check broken external links in the Documentation
  Documentation: Fix linux-api list typo
  Documentation: DocBook/Makefile comment typo
  Improve sparse documentation
  Documentation: make Makefile.sphinx no-ops quieter
  Documentation: DMA-ISA-LPC.txt
  Documentation: input: fix path to input code definitions
  docs: Remove the copyright year from conf.py
  docs: Fix a warning in the Korean HOWTO.rst translation
  PM / sleep / docs: Convert PM notifiers document to reST
  PM / core / docs: Convert sleep states API document to reST
  PM / core: Update kerneldoc comments in pm.h
  doc-rst: Fix recursive make invocation from macros
  doc-rst: Delete output of failed dot-SVG conversion
  doc-rst: Break shell command sequences on failure
  Documentation/sphinx: make targets independent of Sphinx work for HAVE_SPHINX=0
  doc-rst: fixed cleandoc target when used with O=dir
  Documentation/sphinx: prevent generation of .pyc files in the source tree
  ...
parents fd7e9a88 bd856262

Documentation/DMA-ISA-LPC.txt

+1 −1
Original line number Diff line number Diff line
@@ -42,7 +42,7 @@ requirements you pass the flag GFP_DMA to kmalloc. 


Unfortunately the memory available for ISA DMA is scarce so unless you

allocate the memory during boot-up it's a good idea to also pass

__GFP_REPEAT and __GFP_NOWARN to make the allocater try a bit harder.

__GFP_REPEAT and __GFP_NOWARN to make the allocator try a bit harder.



(This scarcity also means that you should allocate the buffer as

early as possible and not release it until the driver is unloaded.)

Documentation/DocBook/Makefile

+3 −2
Original line number Diff line number Diff line
@@ -13,7 +13,7 @@ DOCBOOKS := z8530book.xml \ 
	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \

	    genericirq.xml s390-drivers.xml scsi.xml \

	    sh.xml regulator.xml w1.xml \

	    writing_musb_glue_layer.xml iio.xml

	    writing_musb_glue_layer.xml



ifeq ($(DOCBOOKS),)
@@ -71,6 +71,7 @@ installmandocs: mandocs 
# no-op for the DocBook toolchain

epubdocs:

latexdocs:

linkcheckdocs:



###

#External programs used
@@ -272,6 +273,6 @@ cleandocs: 
	$(Q)rm -rf $(call objectify, $(clean-dirs))



# Declare the contents of the .PHONY variable as phony.  We keep that

# information in a variable se we can use it in if_changed and friends.

# information in a variable so we can use it in if_changed and friends.



.PHONY: $(PHONY)

Documentation/DocBook/deviceiobook.tmpl

deleted100644 → 0
+0 −323
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>



<book id="DoingIO">

 <bookinfo>

  <title>Bus-Independent Device Accesses</title>

  

  <authorgroup>

   <author>

    <firstname>Matthew</firstname>

    <surname>Wilcox</surname>

    <affiliation>

     <address>

      <email>matthew@wil.cx</email>

     </address>

    </affiliation>

   </author>

  </authorgroup>



  <authorgroup>

   <author>

    <firstname>Alan</firstname>

    <surname>Cox</surname>

    <affiliation>

     <address>

      <email>alan@lxorguk.ukuu.org.uk</email>

     </address>

    </affiliation>

   </author>

  </authorgroup>



  <copyright>

   <year>2001</year>

   <holder>Matthew Wilcox</holder>

  </copyright>



  <legalnotice>

   <para>

     This documentation is free software; you can redistribute

     it and/or modify it under the terms of the GNU General Public

     License as published by the Free Software Foundation; either

     version 2 of the License, or (at your option) any later

     version.

   </para>

      

   <para>

     This program is distributed in the hope that it will be

     useful, but WITHOUT ANY WARRANTY; without even the implied

     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

     See the GNU General Public License for more details.

   </para>

      

   <para>

     You should have received a copy of the GNU General Public

     License along with this program; if not, write to the Free

     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,

     MA 02111-1307 USA

   </para>

      

   <para>

     For more details see the file COPYING in the source

     distribution of Linux.

   </para>

  </legalnotice>

 </bookinfo>



<toc></toc>



  <chapter id="intro">

      <title>Introduction</title>

  <para>

	Linux provides an API which abstracts performing IO across all busses

	and devices, allowing device drivers to be written independently of

	bus type.

  </para>

  </chapter>



  <chapter id="bugs">

     <title>Known Bugs And Assumptions</title>

  <para>

	None.	

  </para>

  </chapter>



  <chapter id="mmio">

    <title>Memory Mapped IO</title>

    <sect1 id="getting_access_to_the_device">

      <title>Getting Access to the Device</title>

      <para>

	The most widely supported form of IO is memory mapped IO.

	That is, a part of the CPU's address space is interpreted

	not as accesses to memory, but as accesses to a device.  Some

	architectures define devices to be at a fixed address, but most

	have some method of discovering devices.  The PCI bus walk is a

	good example of such a scheme.	This document does not cover how

	to receive such an address, but assumes you are starting with one.

	Physical addresses are of type unsigned long. 

      </para>



      <para>

	This address should not be used directly.  Instead, to get an

	address suitable for passing to the accessor functions described

	below, you should call <function>ioremap</function>.

	An address suitable for accessing the device will be returned to you.

      </para>



      <para>

	After you've finished using the device (say, in your module's

	exit routine), call <function>iounmap</function> in order to return

	the address space to the kernel.  Most architectures allocate new

	address space each time you call <function>ioremap</function>, and

	they can run out unless you call <function>iounmap</function>.

      </para>

    </sect1>



    <sect1 id="accessing_the_device">

      <title>Accessing the device</title>

      <para>

	The part of the interface most used by drivers is reading and

	writing memory-mapped registers on the device.	Linux provides

	interfaces to read and write 8-bit, 16-bit, 32-bit and 64-bit

	quantities.  Due to a historical accident, these are named byte,

	word, long and quad accesses.  Both read and write accesses are

	supported; there is no prefetch support at this time.

      </para>



      <para>

	The functions are named <function>readb</function>,

	<function>readw</function>, <function>readl</function>,

	<function>readq</function>, <function>readb_relaxed</function>,

	<function>readw_relaxed</function>, <function>readl_relaxed</function>,

	<function>readq_relaxed</function>, <function>writeb</function>,

	<function>writew</function>, <function>writel</function> and

	<function>writeq</function>.

      </para>



      <para>

	Some devices (such as framebuffers) would like to use larger

	transfers than 8 bytes at a time.  For these devices, the

	<function>memcpy_toio</function>, <function>memcpy_fromio</function>

	and <function>memset_io</function> functions are provided.

	Do not use memset or memcpy on IO addresses; they

	are not guaranteed to copy data in order.

      </para>



      <para>

	The read and write functions are defined to be ordered. That is the

	compiler is not permitted to reorder the I/O sequence. When the 

	ordering can be compiler optimised, you can use <function>

	__readb</function> and friends to indicate the relaxed ordering. Use 

	this with care.

      </para>



      <para>

	While the basic functions are defined to be synchronous with respect

	to each other and ordered with respect to each other the busses the

	devices sit on may themselves have asynchronicity. In particular many

	authors are burned by the fact that PCI bus writes are posted

	asynchronously. A driver author must issue a read from the same

	device to ensure that writes have occurred in the specific cases the

	author cares. This kind of property cannot be hidden from driver

	writers in the API.  In some cases, the read used to flush the device

	may be expected to fail (if the card is resetting, for example).  In

	that case, the read should be done from config space, which is

	guaranteed to soft-fail if the card doesn't respond.

      </para>



      <para>

	The following is an example of flushing a write to a device when

	the driver would like to ensure the write's effects are visible prior

	to continuing execution.

      </para>



<programlisting>

static inline void

qla1280_disable_intrs(struct scsi_qla_host *ha)

{

	struct device_reg *reg;



	reg = ha->iobase;

	/* disable risc and host interrupts */

	WRT_REG_WORD(&amp;reg->ictrl, 0);

	/*

	 * The following read will ensure that the above write

	 * has been received by the device before we return from this

	 * function.

	 */

	RD_REG_WORD(&amp;reg->ictrl);

	ha->flags.ints_enabled = 0;

}

</programlisting>



      <para>

	In addition to write posting, on some large multiprocessing systems

	(e.g. SGI Challenge, Origin and Altix machines) posted writes won't

	be strongly ordered coming from different CPUs.  Thus it's important

	to properly protect parts of your driver that do memory-mapped writes

	with locks and use the <function>mmiowb</function> to make sure they

	arrive in the order intended.  Issuing a regular <function>readX

	</function> will also ensure write ordering, but should only be used

	when the driver has to be sure that the write has actually arrived

	at the device (not that it's simply ordered with respect to other

	writes), since a full <function>readX</function> is a relatively

	expensive operation.

      </para>



      <para>

	Generally, one should use <function>mmiowb</function> prior to

	releasing a spinlock that protects regions using <function>writeb

	</function> or similar functions that aren't surrounded by <function>

	readb</function> calls, which will ensure ordering and flushing.  The

	following pseudocode illustrates what might occur if write ordering

	isn't guaranteed via <function>mmiowb</function> or one of the

	<function>readX</function> functions.

      </para>



<programlisting>

CPU A:  spin_lock_irqsave(&amp;dev_lock, flags)

CPU A:  ...

CPU A:  writel(newval, ring_ptr);

CPU A:  spin_unlock_irqrestore(&amp;dev_lock, flags)

        ...

CPU B:  spin_lock_irqsave(&amp;dev_lock, flags)

CPU B:  writel(newval2, ring_ptr);

CPU B:  ...

CPU B:  spin_unlock_irqrestore(&amp;dev_lock, flags)

</programlisting>



      <para>

	In the case above, newval2 could be written to ring_ptr before

	newval.  Fixing it is easy though:

      </para>



<programlisting>

CPU A:  spin_lock_irqsave(&amp;dev_lock, flags)

CPU A:  ...

CPU A:  writel(newval, ring_ptr);

CPU A:  mmiowb(); /* ensure no other writes beat us to the device */

CPU A:  spin_unlock_irqrestore(&amp;dev_lock, flags)

        ...

CPU B:  spin_lock_irqsave(&amp;dev_lock, flags)

CPU B:  writel(newval2, ring_ptr);

CPU B:  ...

CPU B:  mmiowb();

CPU B:  spin_unlock_irqrestore(&amp;dev_lock, flags)

</programlisting>



      <para>

	See tg3.c for a real world example of how to use <function>mmiowb

	</function>

      </para>



      <para>

	PCI ordering rules also guarantee that PIO read responses arrive

	after any outstanding DMA writes from that bus, since for some devices

	the result of a <function>readb</function> call may signal to the

	driver that a DMA transaction is complete.  In many cases, however,

	the driver may want to indicate that the next

	<function>readb</function> call has no relation to any previous DMA

	writes performed by the device.  The driver can use

	<function>readb_relaxed</function> for these cases, although only

	some platforms will honor the relaxed semantics.  Using the relaxed

	read functions will provide significant performance benefits on

	platforms that support it.  The qla2xxx driver provides examples

	of how to use <function>readX_relaxed</function>.  In many cases,

	a majority of the driver's <function>readX</function> calls can

	safely be converted to <function>readX_relaxed</function> calls, since

	only a few will indicate or depend on DMA completion.

      </para>

    </sect1>



  </chapter>



  <chapter id="port_space_accesses">

    <title>Port Space Accesses</title>

    <sect1 id="port_space_explained">

      <title>Port Space Explained</title>



      <para>

	Another form of IO commonly supported is Port Space.  This is a

	range of addresses separate to the normal memory address space.

	Access to these addresses is generally not as fast as accesses

	to the memory mapped addresses, and it also has a potentially

	smaller address space.

      </para>



      <para>

	Unlike memory mapped IO, no preparation is required

	to access port space.

      </para>



    </sect1>

    <sect1 id="accessing_port_space">

      <title>Accessing Port Space</title>

      <para>

	Accesses to this space are provided through a set of functions

	which allow 8-bit, 16-bit and 32-bit accesses; also

	known as byte, word and long.  These functions are

	<function>inb</function>, <function>inw</function>,

	<function>inl</function>, <function>outb</function>,

	<function>outw</function> and <function>outl</function>.

      </para>



      <para>

	Some variants are provided for these functions.  Some devices

	require that accesses to their ports are slowed down.  This

	functionality is provided by appending a <function>_p</function>

	to the end of the function.  There are also equivalents to memcpy.

	The <function>ins</function> and <function>outs</function>

	functions copy bytes, words or longs to the given port.

      </para>

    </sect1>



  </chapter>



  <chapter id="pubfunctions">

     <title>Public Functions Provided</title>

!Iarch/x86/include/asm/io.h

!Elib/pci_iomap.c

  </chapter>



</book>

Documentation/DocBook/iio.tmpl

deleted100644 → 0
+0 −697

File deleted.

Preview size limit exceeded, changes collapsed.

Documentation/DocBook/regulator.tmpl

deleted100644 → 0
+0 −304
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>



<book id="regulator-api">

 <bookinfo>

  <title>Voltage and current regulator API</title>



  <authorgroup>

   <author>

    <firstname>Liam</firstname>

    <surname>Girdwood</surname>

    <affiliation>

     <address>

      <email>lrg@slimlogic.co.uk</email>

     </address>

    </affiliation>

   </author>

   <author>

    <firstname>Mark</firstname>

    <surname>Brown</surname>

    <affiliation>

     <orgname>Wolfson Microelectronics</orgname>

     <address>

      <email>broonie@opensource.wolfsonmicro.com</email>

     </address>

    </affiliation>

   </author>

  </authorgroup>



  <copyright>

   <year>2007-2008</year>

   <holder>Wolfson Microelectronics</holder>

  </copyright>

  <copyright>

   <year>2008</year>

   <holder>Liam Girdwood</holder>

  </copyright>



  <legalnotice>

   <para>

     This documentation is free software; you can redistribute

     it and/or modify it under the terms of the GNU General Public

     License version 2 as published by the Free Software Foundation.

   </para>



   <para>

     This program is distributed in the hope that it will be

     useful, but WITHOUT ANY WARRANTY; without even the implied

     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

     See the GNU General Public License for more details.

   </para>



   <para>

     You should have received a copy of the GNU General Public

     License along with this program; if not, write to the Free

     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,

     MA 02111-1307 USA

   </para>



   <para>

     For more details see the file COPYING in the source

     distribution of Linux.

   </para>

  </legalnotice>

 </bookinfo>



<toc></toc>



  <chapter id="intro">

    <title>Introduction</title>

    <para>

	This framework is designed to provide a standard kernel

	interface to control voltage and current regulators.

    </para>

    <para>

	The intention is to allow systems to dynamically control

	regulator power output in order to save power and prolong

	battery life.  This applies to both voltage regulators (where

	voltage output is controllable) and current sinks (where current

	limit is controllable).

    </para>

    <para>

	Note that additional (and currently more complete) documentation

	is available in the Linux kernel source under

	<filename>Documentation/power/regulator</filename>.

    </para>



    <sect1 id="glossary">

       <title>Glossary</title>

       <para>

	The regulator API uses a number of terms which may not be

	familiar:

       </para>

       <glossary>



         <glossentry>

	   <glossterm>Regulator</glossterm>

	   <glossdef>

	     <para>

	Electronic device that supplies power to other devices.  Most

	regulators can enable and disable their output and some can also

	control their output voltage or current.

	     </para>

	   </glossdef>

         </glossentry>



	 <glossentry>

	   <glossterm>Consumer</glossterm>

	   <glossdef>

	     <para>

	Electronic device which consumes power provided by a regulator.

	These may either be static, requiring only a fixed supply, or

	dynamic, requiring active management of the regulator at

	runtime.

	     </para>

	   </glossdef>

	 </glossentry>



	 <glossentry>

	   <glossterm>Power Domain</glossterm>

	   <glossdef>

	     <para>

	The electronic circuit supplied by a given regulator, including

	the regulator and all consumer devices.  The configuration of

	the regulator is shared between all the components in the

	circuit.

	     </para>

	   </glossdef>

	 </glossentry>



	 <glossentry>

	   <glossterm>Power Management Integrated Circuit</glossterm>

	   <acronym>PMIC</acronym>

	   <glossdef>

	     <para>

	An IC which contains numerous regulators and often also other

	subsystems.  In an embedded system the primary PMIC is often

	equivalent to a combination of the PSU and southbridge in a

	desktop system.

	     </para>

	   </glossdef>

	 </glossentry>

	</glossary>

     </sect1>

  </chapter>



  <chapter id="consumer">

     <title>Consumer driver interface</title>

     <para>

       This offers a similar API to the kernel clock framework.

       Consumer drivers use <link

       linkend='API-regulator-get'>get</link> and <link

       linkend='API-regulator-put'>put</link> operations to acquire and

       release regulators.  Functions are

       provided to <link linkend='API-regulator-enable'>enable</link>

       and <link linkend='API-regulator-disable'>disable</link> the

       regulator and to get and set the runtime parameters of the

       regulator.

     </para>

     <para>

       When requesting regulators consumers use symbolic names for their

       supplies, such as "Vcc", which are mapped into actual regulator

       devices by the machine interface.

     </para>

     <para>

	A stub version of this API is provided when the regulator

	framework is not in use in order to minimise the need to use

	ifdefs.

     </para>



     <sect1 id="consumer-enable">

       <title>Enabling and disabling</title>

       <para>

         The regulator API provides reference counted enabling and

	 disabling of regulators. Consumer devices use the <function><link

	 linkend='API-regulator-enable'>regulator_enable</link></function>

	 and <function><link

	 linkend='API-regulator-disable'>regulator_disable</link>

	 </function> functions to enable and disable regulators.  Calls

	 to the two functions must be balanced.

       </para>

       <para>

         Note that since multiple consumers may be using a regulator and

	 machine constraints may not allow the regulator to be disabled

	 there is no guarantee that calling

	 <function>regulator_disable</function> will actually cause the

	 supply provided by the regulator to be disabled. Consumer

	 drivers should assume that the regulator may be enabled at all

	 times.

       </para>

     </sect1>



     <sect1 id="consumer-config">

       <title>Configuration</title>

       <para>

         Some consumer devices may need to be able to dynamically

	 configure their supplies.  For example, MMC drivers may need to

	 select the correct operating voltage for their cards.  This may

	 be done while the regulator is enabled or disabled.

       </para>

       <para>

	 The <function><link

	 linkend='API-regulator-set-voltage'>regulator_set_voltage</link>

	 </function> and <function><link

	 linkend='API-regulator-set-current-limit'

	 >regulator_set_current_limit</link>

	 </function> functions provide the primary interface for this.

	 Both take ranges of voltages and currents, supporting drivers

	 that do not require a specific value (eg, CPU frequency scaling

	 normally permits the CPU to use a wider range of supply

	 voltages at lower frequencies but does not require that the

	 supply voltage be lowered).  Where an exact value is required

	 both minimum and maximum values should be identical.

       </para>

     </sect1>



     <sect1 id="consumer-callback">

       <title>Callbacks</title>

       <para>

	  Callbacks may also be <link

	  linkend='API-regulator-register-notifier'>registered</link>

	  for events such as regulation failures.

       </para>

     </sect1>

   </chapter>



   <chapter id="driver">

     <title>Regulator driver interface</title>

     <para>

       Drivers for regulator chips <link

       linkend='API-regulator-register'>register</link> the regulators

       with the regulator core, providing operations structures to the

       core.  A <link

       linkend='API-regulator-notifier-call-chain'>notifier</link> interface

       allows error conditions to be reported to the core.

     </para>

     <para>

       Registration should be triggered by explicit setup done by the

       platform, supplying a <link

       linkend='API-struct-regulator-init-data'>struct

       regulator_init_data</link> for the regulator containing

       <link linkend='machine-constraint'>constraint</link> and

       <link linkend='machine-supply'>supply</link> information.

     </para>

   </chapter>



   <chapter id="machine">

     <title>Machine interface</title>

     <para>

       This interface provides a way to define how regulators are

       connected to consumers on a given system and what the valid

       operating parameters are for the system.

     </para>



     <sect1 id="machine-supply">

       <title>Supplies</title>

       <para>

         Regulator supplies are specified using <link

	 linkend='API-struct-regulator-consumer-supply'>struct

	 regulator_consumer_supply</link>.  This is done at

	 <link linkend='driver'>driver registration

	 time</link> as part of the machine constraints.

       </para>

     </sect1>



     <sect1 id="machine-constraint">

       <title>Constraints</title>

       <para>

	 As well as defining the connections the machine interface

	 also provides constraints defining the operations that

	 clients are allowed to perform and the parameters that may be

	 set.  This is required since generally regulator devices will

	 offer more flexibility than it is safe to use on a given

	 system, for example supporting higher supply voltages than the

	 consumers are rated for.

       </para>

       <para>

	 This is done at <link linkend='driver'>driver

	 registration time</link> by providing a <link

	 linkend='API-struct-regulation-constraints'>struct

	 regulation_constraints</link>.

       </para>

       <para>

         The constraints may also specify an initial configuration for the

         regulator in the constraints, which is particularly useful for

         use with static consumers.

       </para>

     </sect1>

  </chapter>



  <chapter id="api">

    <title>API reference</title>

    <para>

      Due to limitations of the kernel documentation framework and the

      existing layout of the source code the entire regulator API is

      documented here.

    </para>

!Iinclude/linux/regulator/consumer.h

!Iinclude/linux/regulator/machine.h

!Iinclude/linux/regulator/driver.h

!Edrivers/regulator/core.c

  </chapter>

</book>