Merge branch 'doc/4.9' into docs-next

cleanup needed then just return directly.

Choose label names which say what the goto does or why the goto exists.  An

example of a good name could be "out_buffer:" if the goto frees "buffer".  Avoid

using GW-BASIC names like "err1:" and "err2:".  Also don't name them after the

goto location like "err_kmalloc_failed:"

example of a good name could be "out_free_buffer:" if the goto frees "buffer".

Avoid using GW-BASIC names like "err1:" and "err2:", as you would have to

renumber them if you ever add or remove exit paths, and they make correctness

difficult to verify anyway.

It is advised to indent labels with a single space (not tab), so that

"diff -p" does not confuse labels with functions.

The rationale for using gotos is:

			goto out_buffer;

		}

		...

	out_buffer:

	 out_free_buffer:

		kfree(buffer);

		return result;

	}

		return ret;

The bug in this code is that on some exit paths "foo" is NULL.  Normally the

fix for this is to split it up into two error labels "err_bar:" and "err_foo:".

fix for this is to split it up into two error labels "err_free_bar:" and

"err_free_foo:":

	 err_free_bar:

		kfree(foo->bar);

	 err_free_foo:

		kfree(foo);

		return ret;

Ideally you should simulate errors to test all exit paths.

		Chapter 8: Commenting

See the files Documentation/kernel-documentation.rst and scripts/kernel-doc

for details.

Linux style for comments is the C89 "/* ... */" style.

Don't use C99-style "// ..." comments.

The preferred style for long (multi-line) comments is:

	/*

# Skip DocBook build if the user explicitly requested no DOCBOOKS.

.DEFAULT:

	@echo "  SKIP    DocBook $@ target (DOCBOOKS=\"\" specified)."

else

ifneq ($(SPHINXDIRS),)

# Skip DocBook build if the user explicitly requested a sphinx dir

.DEFAULT:

	@echo "  SKIP    DocBook $@ target (SPHINXDIRS specified)."

else

###

# The build process is as follows (targets):

#              (xmldocs) [by docproc]

	   echo "</programlisting>")  > $@

endif # DOCBOOKS=""

endif # SPHINDIR=...

###

# Help targets as used by the top-level makefile

# You can set these variables from the command line.

SPHINXBUILD   = sphinx-build

SPHINXOPTS    =

SPHINXDIRS    = .

_SPHINXDIRS   = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))

SPHINX_CONF   = conf.py

PAPER         =

BUILDDIR      = $(obj)/output

PAPEROPT_letter = -D latex_paper_size=letter

KERNELDOC       = $(srctree)/scripts/kernel-doc

KERNELDOC_CONF  = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)

ALLSPHINXOPTS   = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)

ALLSPHINXOPTS   =  $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)

# the i18n builder cannot share the environment and doctrees with the others

I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

quiet_cmd_sphinx = SPHINX  $@

      cmd_sphinx = $(MAKE) BUILDDIR=$(BUILDDIR) $(build)=Documentation/media all; BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2

# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*

loop_cmd = $(echo-cmd) $(cmd_$(1))

# $2 sphinx builder e.g. "html"

# $3 name of the build subfolder / e.g. "media", used as:

#    * dest folder relative to $(BUILDDIR) and

#    * cache folder relative to $(BUILDDIR)/.doctrees

# $4 dest subfolder e.g. "man" for man pages at media/man

# $5 reST source folder relative to $(srctree)/$(src),

#    e.g. "media" for the linux-tv book-set at ./Documentation/media

quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4);

      cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\

	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \

	$(SPHINXBUILD) \

	-b $2 \

	-c $(abspath $(srctree)/$(src)) \

	-d $(abspath $(BUILDDIR)/.doctrees/$3) \

	-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \

	$(ALLSPHINXOPTS) \

	$(abspath $(srctree)/$(src)/$5) \

	$(abspath $(BUILDDIR)/$3/$4);

htmldocs:

	$(call cmd,sphinx,html)

	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))

pdfdocs:

ifeq ($(HAVE_PDFLATEX),0)

	$(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)

	@echo "  SKIP    Sphinx $@ target."

else # HAVE_PDFLATEX

	$(call cmd,sphinx,latex)

	@$(call loop_cmd,sphinx,latex,.,latex,.))

	$(Q)$(MAKE) -C $(BUILDDIR)/latex

endif # HAVE_PDFLATEX

epubdocs:

	$(call cmd,sphinx,epub)

	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))

xmldocs:

	$(call cmd,sphinx,xml)

	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))

# no-ops for the Sphinx toolchain

sgmldocs:

	@echo  '  epubdocs        - EPUB'

	@echo  '  xmldocs         - XML'

	@echo  '  cleandocs       - clean all generated files'

	@echo

	@echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'

	@echo  '  valid values for SPHINXDIRS are: $(_SPHINXDIRS)'

	@echo

	@echo  '  make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'

	@echo  '  configuration. This is e.g. useful to build with nit-picking config.'

hardware-specific bits for the hypothetical "foo" hardware.

Tying the two halves of this interface together is struct clk_hw, which

is defined in struct clk_foo and pointed to within struct clk.  This

is defined in struct clk_foo and pointed to within struct clk_core.  This

allows for easy navigation between the two discrete halves of the common

clock interface.

	Part 2 - common data structures and api

Below is the common struct clk definition from

include/linux/clk-private.h, modified for brevity:

Below is the common struct clk_core definition from

drivers/clk/clk.c, modified for brevity:

	struct clk {

	struct clk_core {

		const char		*name;

		const struct clk_ops	*ops;

		struct clk_hw		*hw;

		char			**parent_names;

		struct clk		**parents;

		struct clk		*parent;

		struct hlist_head	children;

		struct hlist_node	child_node;

		struct module		*owner;

		struct clk_core		*parent;

		const char		**parent_names;

		struct clk_core		**parents;

		u8			num_parents;

		u8			new_parent_index;

		...

	};

api itself defines several driver-facing functions which operate on

struct clk.  That api is documented in include/linux/clk.h.

Platforms and devices utilizing the common struct clk use the struct

clk_ops pointer in struct clk to perform the hardware-specific parts of

the operations defined in clk.h:

Platforms and devices utilizing the common struct clk_core use the struct

clk_ops pointer in struct clk_core to perform the hardware-specific parts of

the operations defined in clk-provider.h:

	struct clk_ops {

		int		(*prepare)(struct clk_hw *hw);

		void		(*unprepare)(struct clk_hw *hw);

		int		(*is_prepared)(struct clk_hw *hw);

		void		(*unprepare_unused)(struct clk_hw *hw);

		int		(*enable)(struct clk_hw *hw);

		void		(*disable)(struct clk_hw *hw);

		int		(*is_enabled)(struct clk_hw *hw);

		void		(*disable_unused)(struct clk_hw *hw);

		unsigned long	(*recalc_rate)(struct clk_hw *hw,

						unsigned long parent_rate);

		long		(*round_rate)(struct clk_hw *hw,

					    u8 index);

		unsigned long	(*recalc_accuracy)(struct clk_hw *hw,

						unsigned long parent_accuracy);

		int		(*get_phase)(struct clk_hw *hw);

		int		(*set_phase)(struct clk_hw *hw, int degrees);

		void		(*init)(struct clk_hw *hw);

		int		(*debug_init)(struct clk_hw *hw,

					      struct dentry *dentry);

	Part 3 - hardware clk implementations

The strength of the common struct clk comes from its .ops and .hw pointers

The strength of the common struct clk_core comes from its .ops and .hw pointers

which abstract the details of struct clk from the hardware-specific bits, and

vice versa.  To illustrate consider the simple gateable clk implementation in

drivers/clk/clk-gate.c:

knowledge about which register and bit controls this clk's gating.

Nothing about clock topology or accounting, such as enable_count or

notifier_count, is needed here.  That is all handled by the common

framework code and struct clk.

framework code and struct clk_core.

Let's walk through enabling this clk from driver code:

Note that to_clk_gate is defined as:

#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, clk)

#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw)

This pattern of abstraction is used for every clock hardware

representation.

	Part 4 - supporting your own clk hardware

When implementing support for a new type of clock it only necessary to

When implementing support for a new type of clock it is only necessary to

include the following header:

#include <linux/clk-provider.h>

include/linux/clk.h is included within that header and clk-private.h

must never be included from the code which implements the operations for

a clock.  More on that below in Part 5.

To construct a clk hardware structure for your platform you must define

the following:

# add these directories to sys.path here. If the directory is relative to the

# documentation root, use os.path.abspath to make it absolute, like shown here.

sys.path.insert(0, os.path.abspath('sphinx'))

from load_config import loadConfig

# -- General configuration ------------------------------------------------

# line arguments.

kerneldoc_bin = '../scripts/kernel-doc'

kerneldoc_srctree = '..'

# ------------------------------------------------------------------------------

# Since loadConfig overwrites settings from the global namespace, it has to be

# the last statement in the conf.py file

# ------------------------------------------------------------------------------

loadConfig(globals())