Merge branch 'doc/4.9' into docs-next
Jonathan Corbet
commit
cc935bb596
|
|
@ -396,9 +396,13 @@ locations and some common work such as cleanup has to be done. If there is no
|
|||
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:
|
||||
|
||||
|
|
@ -425,20 +429,29 @@ The rationale for using gotos is:
|
|||
goto out_buffer;
|
||||
}
|
||||
...
|
||||
out_buffer:
|
||||
out_free_buffer:
|
||||
kfree(buffer);
|
||||
return result;
|
||||
}
|
||||
|
||||
A common type of bug to be aware of is "one err bugs" which look like this:
|
||||
|
||||
err:
|
||||
err:
|
||||
kfree(foo->bar);
|
||||
kfree(foo);
|
||||
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
|
||||
|
|
@ -461,9 +474,6 @@ When commenting the kernel API functions, please use the kernel-doc format.
|
|||
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:
|
||||
|
||||
/*
|
||||
|
|
|
|||
|
|
@ -22,8 +22,14 @@ ifeq ($(DOCBOOKS),)
|
|||
# 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):
|
||||
|
|
@ -221,6 +227,7 @@ silent_gen_xml = :
|
|||
echo "</programlisting>") > $@
|
||||
|
||||
endif # DOCBOOKS=""
|
||||
endif # SPHINDIR=...
|
||||
|
||||
###
|
||||
# Help targets as used by the top-level makefile
|
||||
|
|
|
|||
|
|
@ -5,6 +5,9 @@
|
|||
# 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
|
||||
|
||||
|
|
@ -33,30 +36,50 @@ PAPEROPT_a4 = -D latex_paper_size=a4
|
|||
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:
|
||||
|
|
@ -76,3 +99,9 @@ dochelp:
|
|||
@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.'
|
||||
|
|
|
|||
|
|
@ -31,24 +31,25 @@ serve as a convenient shorthand for the implementation of the
|
|||
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;
|
||||
...
|
||||
};
|
||||
|
||||
|
|
@ -56,16 +57,19 @@ The members above make up the core of the clk tree topology. The clk
|
|||
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,
|
||||
|
|
@ -84,6 +88,8 @@ the operations defined in clk.h:
|
|||
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);
|
||||
|
|
@ -91,7 +97,7 @@ the operations defined in clk.h:
|
|||
|
||||
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:
|
||||
|
|
@ -107,7 +113,7 @@ struct clk_gate contains struct clk_hw hw as well as hardware-specific
|
|||
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:
|
||||
|
||||
|
|
@ -139,22 +145,18 @@ static void clk_gate_set_bit(struct clk_gate *gate)
|
|||
|
||||
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:
|
||||
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ import os
|
|||
# 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 ------------------------------------------------
|
||||
|
||||
|
|
@ -421,3 +422,9 @@ pdf_documents = [
|
|||
# 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())
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
# -*- coding: utf-8 mode: conf-colon -*-
|
||||
#
|
||||
# docutils configuration file
|
||||
# http://docutils.sourceforge.net/docs/user/config.html
|
||||
|
||||
[general]
|
||||
halt_level: severe
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
# -*- coding: utf-8; mode: python -*-
|
||||
|
||||
project = "Linux GPU Driver Developer's Guide"
|
||||
|
|
@ -6,18 +6,13 @@
|
|||
Welcome to The Linux Kernel's documentation!
|
||||
============================================
|
||||
|
||||
Nothing for you to see here *yet*. Please move along.
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
kernel-documentation
|
||||
media/media_uapi
|
||||
media/media_kapi
|
||||
media/dvb-drivers/index
|
||||
media/v4l-drivers/index
|
||||
media/index
|
||||
gpu/index
|
||||
|
||||
Indices and tables
|
||||
|
|
|
|||
|
|
@ -0,0 +1,3 @@
|
|||
# -*- coding: utf-8; mode: python -*-
|
||||
|
||||
project = 'Linux Media Subsystem Documentation'
|
||||
|
|
@ -0,0 +1,93 @@
|
|||
# -*- coding: utf-8; mode: python -*-
|
||||
|
||||
project = 'Linux Media Subsystem Documentation'
|
||||
|
||||
# It is possible to run Sphinx in nickpick mode with:
|
||||
nitpicky = True
|
||||
|
||||
# within nit-picking build, do not refer to any intersphinx object
|
||||
intersphinx_mapping = {}
|
||||
|
||||
# In nickpick mode, it will complain about lots of missing references that
|
||||
#
|
||||
# 1) are just typedefs like: bool, __u32, etc;
|
||||
# 2) It will complain for things like: enum, NULL;
|
||||
# 3) It will complain for symbols that should be on different
|
||||
# books (but currently aren't ported to ReST)
|
||||
#
|
||||
# The list below has a list of such symbols to be ignored in nitpick mode
|
||||
#
|
||||
nitpick_ignore = [
|
||||
("c:func", "clock_gettime"),
|
||||
("c:func", "close"),
|
||||
("c:func", "container_of"),
|
||||
("c:func", "determine_valid_ioctls"),
|
||||
("c:func", "ERR_PTR"),
|
||||
("c:func", "ioctl"),
|
||||
("c:func", "IS_ERR"),
|
||||
("c:func", "mmap"),
|
||||
("c:func", "open"),
|
||||
("c:func", "pci_name"),
|
||||
("c:func", "poll"),
|
||||
("c:func", "PTR_ERR"),
|
||||
("c:func", "read"),
|
||||
("c:func", "release"),
|
||||
("c:func", "set"),
|
||||
("c:func", "struct fd_set"),
|
||||
("c:func", "struct pollfd"),
|
||||
("c:func", "usb_make_path"),
|
||||
("c:func", "write"),
|
||||
("c:type", "atomic_t"),
|
||||
("c:type", "bool"),
|
||||
("c:type", "buf_queue"),
|
||||
("c:type", "device"),
|
||||
("c:type", "device_driver"),
|
||||
("c:type", "device_node"),
|
||||
("c:type", "enum"),
|
||||
("c:type", "file"),
|
||||
("c:type", "i2c_adapter"),
|
||||
("c:type", "i2c_board_info"),
|
||||
("c:type", "i2c_client"),
|
||||
("c:type", "ktime_t"),
|
||||
("c:type", "led_classdev_flash"),
|
||||
("c:type", "list_head"),
|
||||
("c:type", "lock_class_key"),
|
||||
("c:type", "module"),
|
||||
("c:type", "mutex"),
|
||||
("c:type", "pci_dev"),
|
||||
("c:type", "pdvbdev"),
|
||||
("c:type", "poll_table_struct"),
|
||||
("c:type", "s32"),
|
||||
("c:type", "s64"),
|
||||
("c:type", "sd"),
|
||||
("c:type", "spi_board_info"),
|
||||
("c:type", "spi_device"),
|
||||
("c:type", "spi_master"),
|
||||
("c:type", "struct fb_fix_screeninfo"),
|
||||
("c:type", "struct pollfd"),
|
||||
("c:type", "struct timeval"),
|
||||
("c:type", "struct video_capability"),
|
||||
("c:type", "u16"),
|
||||
("c:type", "u32"),
|
||||
("c:type", "u64"),
|
||||
("c:type", "u8"),
|
||||
("c:type", "union"),
|
||||
("c:type", "usb_device"),
|
||||
|
||||
("cpp:type", "boolean"),
|
||||
("cpp:type", "fd"),
|
||||
("cpp:type", "fd_set"),
|
||||
("cpp:type", "int16_t"),
|
||||
("cpp:type", "NULL"),
|
||||
("cpp:type", "off_t"),
|
||||
("cpp:type", "pollfd"),
|
||||
("cpp:type", "size_t"),
|
||||
("cpp:type", "ssize_t"),
|
||||
("cpp:type", "timeval"),
|
||||
("cpp:type", "__u16"),
|
||||
("cpp:type", "__u32"),
|
||||
("cpp:type", "__u64"),
|
||||
("cpp:type", "uint16_t"),
|
||||
("cpp:type", "uint32_t"),
|
||||
("cpp:type", "video_system_t"),
|
||||
]
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
Linux Media Subsystem Documentation
|
||||
===================================
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
media_uapi
|
||||
media_kapi
|
||||
dvb-drivers/index
|
||||
v4l-drivers/index
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
# -*- coding: utf-8; mode: python -*-
|
||||
# pylint: disable=R0903, C0330, R0914, R0912, E0401
|
||||
|
||||
import os
|
||||
import sys
|
||||
from sphinx.util.pycompat import execfile_
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
def loadConfig(namespace):
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
u"""Load an additional configuration file into *namespace*.
|
||||
|
||||
The name of the configuration file is taken from the environment
|
||||
``SPHINX_CONF``. The external configuration file extends (or overwrites) the
|
||||
configuration values from the origin ``conf.py``. With this you are able to
|
||||
maintain *build themes*. """
|
||||
|
||||
config_file = os.environ.get("SPHINX_CONF", None)
|
||||
if (config_file is not None
|
||||
and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ):
|
||||
config_file = os.path.abspath(config_file)
|
||||
|
||||
if os.path.isfile(config_file):
|
||||
sys.stdout.write("load additional sphinx-config: %s\n" % config_file)
|
||||
config = namespace.copy()
|
||||
config['__file__'] = config_file
|
||||
execfile_(config_file, config)
|
||||
del config['__file__']
|
||||
namespace.update(config)
|
||||
else:
|
||||
sys.stderr.write("WARNING: additional sphinx-config not found: %s\n" % config_file)
|
||||
8
README
8
README
|
|
@ -229,10 +229,6 @@ CONFIGURING the kernel:
|
|||
under some circumstances lead to problems: probing for a
|
||||
nonexistent controller card may confuse your other controllers
|
||||
|
||||
- Compiling the kernel with "Processor type" set higher than 386
|
||||
will result in a kernel that does NOT work on a 386. The
|
||||
kernel will detect this on bootup, and give up.
|
||||
|
||||
- A kernel with math-emulation compiled in will still use the
|
||||
coprocessor if one is present: the math emulation will just
|
||||
never get used in that case. The kernel will be slightly larger,
|
||||
|
|
@ -289,7 +285,7 @@ COMPILING the kernel:
|
|||
LOCALVERSION can be set in the "General Setup" menu.
|
||||
|
||||
- In order to boot your new kernel, you'll need to copy the kernel
|
||||
image (e.g. .../linux/arch/i386/boot/bzImage after compilation)
|
||||
image (e.g. .../linux/arch/x86/boot/bzImage after compilation)
|
||||
to the place where your regular bootable kernel is found.
|
||||
|
||||
- Booting a kernel directly from a floppy without the assistance of a
|
||||
|
|
@ -391,7 +387,7 @@ IF SOMETHING GOES WRONG:
|
|||
|
||||
- Alternatively, you can use gdb on a running kernel. (read-only; i.e. you
|
||||
cannot change values or set break points.) To do this, first compile the
|
||||
kernel with -g; edit arch/i386/Makefile appropriately, then do a "make
|
||||
kernel with -g; edit arch/x86/Makefile appropriately, then do a "make
|
||||
clean". You'll also need to enable CONFIG_PROC_FS (via "make config").
|
||||
|
||||
After you've rebooted with the new kernel, do "gdb vmlinux /proc/kcore".
|
||||
|
|
|
|||
Loading…
Reference in New Issue