mistakenly membase8_io used instead of membase8_config
in this case we can't read/write CAM module memory (TUPLES)
Signed-off-by: Abylay Ospan <aospan@netup.ru>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
CXD2854ER is identical to CXD2841ER except ISDB-T/S added.
New method 'cxd2841er_attach_i' is added
xtal frequency now configurable. Available options:
20.5MHz, 24MHz, 41MHz
Signed-off-by: Abylay Ospan <aospan@netup.ru>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
This is Sony HELENE DVB-S/S2 DVB-T/T2 DVB-C/C2 ISDB-T/S tuner
driver (CXD2858ER).
Tuner is used on NetUP Dual Universal DVB CI card (hardware revision 1.4).
Use 'helene_attach_s' to attach tuner in 'satellite mode'.
Use 'helene_attach' for 'terrestrial mode'.
Satellite delivery systems supported:
DVB-S/S2, ISDB-S
Terrestrial delivery systems supported:
DVB-T/T2, ISDB-T
Cable delivery systems supported:
DVB-C/C2
Signed-off-by: Abylay Ospan <aospan@netup.ru>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
The formula used to calculate bytesperline only works for packed format.
So far, all planar format we support have their bytesperline equal to
the image width (stride of the Y plane or a line of Y for M420).
Signed-off-by: Nicolas Dufresne <nicolas.dufresne@collabora.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Add a DT binding documentation of Video Processor Unit for the
MT8173 SoC from Mediatek.
Signed-off-by: Andrew-CT Chen <andrew-ct.chen@mediatek.com>
Signed-off-by: Tiffany Lin <tiffany.lin@mediatek.com>
Acked-by: Rob Herring <robh@kernel.org>
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
User-space applications can use the VIDIOC_REQBUFS ioctl to determine if a
memory mapped, user pointer or DMABUF based I/O is supported by the driver.
So a set of VIDIOC_REQBUFS ioctl calls will be made with count 0 and then
the real VIDIOC_REQBUFS call with count == n. But for count 0, the driver
not only frees the buffer but also closes the MFC instance and s5p_mfc_ctx
state is set to MFCINST_FREE.
The VIDIOC_REQBUFS handler for the output device checks if the s5p_mfc_ctx
state is set to MFCINST_INIT (which happens on an VIDIOC_S_FMT) and fails
otherwise. So after a VIDIOC_REQBUFS(n), future VIDIOC_REQBUFS(n) calls
will fails unless a VIDIOC_S_FMT ioctl calls happens before the reqbufs.
But applications may first set the format and then attempt to determine
the I/O methods supported by the driver (for example Gstramer does it) so
the state won't be set to MFCINST_INIT again and VIDIOC_REQBUFS will fail.
To avoid this issue, only free the buffers on VIDIOC_REQBUFS(0) but don't
close the MFC instance to allow future VIDIOC_REQBUFS(n) calls to succeed.
[javier: Rewrote changelog to explain the problem more detailed]
Signed-off-by: ayaka <ayaka@soulik.info>
Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
Acked-by: Nicolas Dufresne <nicolas@collabora.com>
Tested-by: Marek Szyprowski <m.szyprowski@samsung.com>
Acked-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Failing to get the struct s5p_mfc_pm .clock is a non-fatal error so the
clock field can have a errno pointer value. But s5p_mfc_final_pm() only
checks if .clock is not NULL before attempting to unprepare and put it.
This leads to the following warning in clk_put() due s5p_mfc_final_pm():
WARNING: CPU: 3 PID: 1023 at drivers/clk/clk.c:2814 s5p_mfc_final_pm+0x48/0x74 [s5p_mfc]
CPU: 3 PID: 1023 Comm: rmmod Tainted: G W 4.6.0-rc6-next-20160502-00005-g5a15a49106bc #9
Hardware name: SAMSUNG EXYNOS (Flattened Device Tree)
[<c010e1bc>] (unwind_backtrace) from [<c010af28>] (show_stack+0x10/0x14)
[<c010af28>] (show_stack) from [<c032485c>] (dump_stack+0x88/0x9c)
[<c032485c>] (dump_stack) from [<c011b8e8>] (__warn+0xe8/0x100)
[<c011b8e8>] (__warn) from [<c011b9b0>] (warn_slowpath_null+0x20/0x28)
[<c011b9b0>] (warn_slowpath_null) from [<bf16004c>] (s5p_mfc_final_pm+0x48/0x74 [s5p_mfc])
[<bf16004c>] (s5p_mfc_final_pm [s5p_mfc]) from [<bf157414>] (s5p_mfc_remove+0x8c/0x94 [s5p_mfc])
[<bf157414>] (s5p_mfc_remove [s5p_mfc]) from [<c03fe1f8>] (platform_drv_remove+0x24/0x3c)
[<c03fe1f8>] (platform_drv_remove) from [<c03fcc70>] (__device_release_driver+0x84/0x110)
[<c03fcc70>] (__device_release_driver) from [<c03fcdd8>] (driver_detach+0xac/0xb0)
[<c03fcdd8>] (driver_detach) from [<c03fbff8>] (bus_remove_driver+0x4c/0xa0)
[<c03fbff8>] (bus_remove_driver) from [<c01886a8>] (SyS_delete_module+0x174/0x1b8)
[<c01886a8>] (SyS_delete_module) from [<c01078c0>] (ret_fast_syscall+0x0/0x3c)
Assign the pointer to NULL in case of a lookup failure to fix the issue.
Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
Acked-by: Arnd Bergmann <arnd@arndb.de>
Reviewed-by: Krzysztof Kozlowski <k.kozlowski@samsung.com>
Acked-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
This patch fixes build break caused by lack of dma-iommu API on ARM64
(this API is specific to ARM 32bit architecture).
Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
* 'for-v4.8/media/exynos-mfc' of git://linuxtv.org/snawrocki/samsung:
media: s5p-mfc: add iommu support
media: s5p-mfc: replace custom reserved memory handling code with generic one
media: s5p-mfc: use generic reserved memory bindings
of: reserved_mem: add support for using more than one region for given device
media: set proper max seg size for devices on Exynos SoCs
media: vb2-dma-contig: add helper for setting dma max seg size
s5p-mfc: Fix race between s5p_mfc_probe() and s5p_mfc_open()
s5p-mfc: Add release callback for memory region devs
s5p-mfc: Set device name for reserved memory region devs
Design is pretty simple: kernel-doc inserts breadcrumbs with line
numbers, and sphinx picks them up. At first I went with a sphinx
comment, but inserting those at random places seriously upsets the
parser, and must be filtered. Hence why this version now uses "#define
LINEO " since one of these ever escape into output it's pretty clear
there is a bug.
It seems to work well, and at least the 2-3 errors where sphinx
complained about something that was not correct in kernel-doc text the
line numbers matched up perfectly.
v2: Instead of noodling around in the parser state machine, create
a ViewList and parse it ourselves. This seems to be the recommended
way, per Jani's suggestion.
v3:
- Split out ViewList pach. Splitting the kernel-doc changes from the
sphinx ones isn't possible, since emitting the LINENO lines wreaks
havoc with the rst formatting. We must filter them.
- Improve the regex per Jani's suggestions, and compile it just once
for speed.
- Now that LINENO lines are eaten, also add them to function parameter
descriptions. Much less content and offset than for in-line struct
member descriptions, but still nice to know which exact continuation
line upsets sphinx.
- Simplify/clarify the line +/-1 business a bit.
v4: Split out the scripts/kernel-doc changes and make line-numbers
opt-in, as suggested by Jani.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Opt-in since this wreaks the rst output and must be removed
by consumers again. This is useful to adjust the linenumbers
for included kernel-doc snippets in shinx. With that sphinx
error message will be accurate when there's issues with the
rst-ness of the kernel-doc comments.
Especially when transitioning a new docbook .tmpl to .rst this
is extremely useful, since you can just use your editors compilation
quickfix list to accurately jump from error to error.
v2:
- Also make sure that we filter the LINENO for purpose/at declaration
start so it only shows for selected blocks, not all of them (Jani).
While at it make it a notch more accurate.
- Avoid undefined $lineno issues. I tried filtering these out at the
callsite, but Jani spotted more when linting the entire kernel.
Unamed unions and similar things aren't stored consistently and end
up with an undefined line number (but also no kernel-doc text, just
the parameter type). Simplify things and filter undefined line
numbers in print_lineno() to catch them all.
v3: Fix LINENO 0 issue for kernel-doc comments without @param: lines
or any other special sections that directly jump to the description
after the "name - purpose" line. Only really possible for functions
without parameters. Noticed by Jani.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Chinese version CodingStyle is a little outdate, it should be updated.
This patch sync with the latest CodingStyle of all changes,
new chapters (chapter 19 and chapter 20) have been translated.
Signed-off-by: Andy Deng <theandy.deng@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
It took me browsing through the source code to determine that I was,
indeed, using the wrong delimiter in my command lines. So I might as
well document it for the next person.
Signed-off-by: Brian Norris <computersforpeace@gmail.com>
Acked-by: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The compilation emits a warning in function ‘snprintf’,
inlined from ‘set_cmdline’ at
../Documentation/mic/mpssd/mpssd.c:1541:9:
/usr/include/x86_64-linux-gnu/bits/stdio2.h:64:10:
warning: call to __builtin___snprintf_chk will always overflow
destination buffer
This was introduced in commit f4a66c2044 ("misc: mic: Update MIC host
daemon with COSM changes") and is fixed by reverting the changes to the
size argument of these snprintf statements.
Cc: Ashutosh Dixit <ashutosh.dixit@intel.com>
Signed-off-by: Mike Danese <mikedanese@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are two sentences in the Sync File documentation where the
english is a little off. This patch is an attempt to fix these.
Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
Reviewed-by: Gustavo Padovan <gustavo.padovan@collabora.co.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This patch adds support for IOMMU to s5p-mfc device driver. MFC firmware
is limited and it cannot use the default configuration. If IOMMU is
available, the patch disables the default DMA address space
configuration and creates a new address space of size limited to 256M
and base address set to 0x20000000.
For now the same address space is shared by both 'left' and 'right'
memory channels, because the DMA/IOMMU frameworks do not support
configuring them separately. This is not optimal, but besides limiting
total address space available has no other drawbacks (MFC firmware
supports 256M of address space per each channel).
Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
Reviewed-by: Javier Martinez Canillas <javier@osg.samsung.com>
Tested-by: Javier Martinez Canillas <javier@osg.samsung.com>
Signed-off-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
This patch removes custom code for initialization and handling of
reserved memory regions in s5p-mfc driver and replaces it with generic
reserved memory regions api.
s5p-mfc driver now handles two reserved memory regions defined by
generic reserved memory bindings. Support for non-dt platform has been
removed, because all supported platforms have been already converted to
device tree.
Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
Reviewed-by: Javier Martinez Canillas <javier@osg.samsung.com>
Tested-by: Javier Martinez Canillas <javier@osg.samsung.com>
Signed-off-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
Use generic reserved memory bindings and mark old, custom properties
as obsoleted.
Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
Reviewed-by: Javier Martinez Canillas <javier@osg.samsung.com>
Acked-by: Rob Herring <robh@kernel.org>
Acked-by: Krzysztof Kozlowski <k.kozlowski@samsung.com>
Signed-off-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
This patch allows device drivers to initialize more than one reserved
memory region assigned to given device. When driver needs to use more
than one reserved memory region, it should allocate child devices and
initialize regions by index for each of its child devices.
Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
Acked-by: Rob Herring <robh@kernel.org>
Signed-off-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
All multimedia devices found on Exynos SoCs support only contiguous
buffers, so set DMA max segment size to DMA_BIT_MASK(32) to let memory
allocator to correctly create contiguous memory mappings.
Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
Signed-off-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
Add a helper function for device drivers to set DMA's max_seg_size.
Setting it to largest possible value lets DMA-mapping API always create
contiguous mappings in DMA address space. This is essential for all
devices, which use dma-contig videobuf2 memory allocator and shared
buffers.
Till now, the only case when vb2-dma-contig really 'worked' was a case
where userspace provided USERPTR buffer, which was in fact mmaped
contiguous buffer from the other v4l2/drm device. Also DMABUF made of
contiguous buffer worked only when its exporter did not split it into
several chunks in the scatter-list. Any other buffer failed, regardless
of the arch/platform used and the presence of the IOMMU of the device bus.
This patch provides interface to fix this issue.
Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
Signed-off-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
The s5p_mfc_probe() function registers the video devices before all the
resources needed by s5p_mfc_open() are correctly initalized.
So if s5p_mfc_open() function is called before s5p_mfc_probe() finishes
(since the video dev is already registered), a NULL pointer dereference
will happen due s5p_mfc_open() accessing uninitialized vars such as the
struct s5p_mfc_dev .watchdog_timer and .mfc_ops fields.
An example is following BUG caused by add_timer() getting a NULL pointer:
[ 45.765374] kernel BUG at kernel/time/timer.c:790!
[ 45.765381] Internal error: Oops - BUG: 0 [#1] PREEMPT SMP ARM
...
[ 45.766149] [<c016fdf4>] (mod_timer) from [<bf181d18>] (s5p_mfc_open+0x274/0x4d4 [s5p_mfc])
[ 45.766416] [<bf181d18>] (s5p_mfc_open [s5p_mfc]) from [<bf0214a0>] (v4l2_open+0x9c/0x100 [videodev])
[ 45.766547] [<bf0214a0>] (v4l2_open [videodev]) from [<c01e355c>] (chrdev_open+0x9c/0x178)
[ 45.766575] [<c01e355c>] (chrdev_open) from [<c01dceb4>] (do_dentry_open+0x1e0/0x300)
[ 45.766595] [<c01dceb4>] (do_dentry_open) from [<c01ec2f0>] (path_openat+0x800/0x10d4)
[ 45.766610] [<c01ec2f0>] (path_openat) from [<c01ed8b8>] (do_filp_open+0x5c/0xc0)
[ 45.766624] [<c01ed8b8>] (do_filp_open) from [<c01de218>] (do_sys_open+0x10c/0x1bc)
[ 45.766642] [<c01de218>] (do_sys_open) from [<c01078c0>] (ret_fast_syscall+0x0/0x3c)
[ 45.766655] Code: eaffffe3 e3a00001 e28dd008 e8bd81f0 (e7f001f2)
Fix it by registering the video devs as the last step in s5p_mfc_probe().
Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
Tested-by: Marek Szyprowski <m.szyprowski@samsung.com>
Signed-off-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
When s5p_mfc_remove() calls put_device() for the reserved memory region
devs, the driver core warns that the dev doesn't have a release callback:
WARNING: CPU: 0 PID: 591 at drivers/base/core.c:251 device_release+0x8c/0x90
Device 's5p-mfc-l' does not have a release() function, it is broken and must be fixed.
Also, the declared DMA memory using dma_declare_coherent_memory() isn't
relased so add a dev .release that calls dma_release_declared_memory().
Cc: <stable@vger.kernel.org>
Fixes: 6e83e6e25e ("[media] s5p-mfc: Fix kernel warning on memory init")
Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
Tested-by: Marek Szyprowski <m.szyprowski@samsung.com>
Signed-off-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
The devices don't have a name set, so makes dev_name() returns NULL which
makes harder to identify the devices that are causing issues, for example:
WARNING: CPU: 2 PID: 616 at drivers/base/core.c:251 device_release+0x8c/0x90
Device '(null)' does not have a release() function, it is broken and must be fixed.
And after setting the device name:
WARNING: CPU: 0 PID: 591 at drivers/base/core.c:251 device_release+0x8c/0x90
Device 's5p-mfc-l' does not have a release() function, it is broken and must be fixed.
Cc: <stable@vger.kernel.org>
Fixes: 6e83e6e25e ("[media] s5p-mfc: Fix kernel warning on memory init")
Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
Tested-by: Marek Szyprowski <m.szyprowski@samsung.com>
Signed-off-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
state3 = prototype parsing, so name them accordingly.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Instead of just forcefully inserting our kernel-doc input and letting
the state machine stumble over it the recommended way is to create
ViewList, parse that and then return the list of parsed nodes.
Suggested by Jani.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Further up in the state machinery we switch from STATE_NAME to
STATE_DOCBLOCK when we match /$doc_block/. Which means this block of
code here is entirely unreachable, unless there are multiple DOC:
sections within a single kernel-doc comment.
Getting a list of all the files with more than one DOC: section using
$ git grep -c " * DOC:" | grep -v ":1$"
and then doing a full audit of them reveals there are no such comment
blocks in the kernel.
Supporting multiple DOC: sections in a single kernel-doc comment does
not seem like a recommended way of doing things anyway, so nuke the code
for simplicity.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
[Jani: amended the commit message]
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
With this error output becomes almost readable. The line numbers are
still totally bonghits, but that's a lot harder to pull out of
kerneldoc. We'd essentially have to insert some special markers in the
kernel-doc output, split the output along these markers and then
insert each block separately using
state_machine.insert_input(block, source, first_line)
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Reconcile differences between python2 and python3 on dealing with
stdout, stderr from Popen. This fixes "name 'unicode' is not defined"
errors on python3. We'll need to try to keep the extension working on
both python-sphinx and python3-sphinx so we don't need two copies.
Reported-and-tested-by: Marius Vlad <marius.c.vlad@intel.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQEcBAABAgAGBQJXSxkJAAoJEHm+PkMAQRiGwfcH/iK8kqycIUhLc/Wn2TnY0TcO
9FPW6EREzc7cRu38rXAgLyU15ysCK56QtV8anqvxkalHgY0ovmE3bwR3BKyUtW3W
IdevRChiGCH0jwG+KjlGrguBI1PCejnY9/El2F1mzUvlkMv7OYYMcUHPUm96HN15
TLjOYgUQyK+YBsj/LBWj7qUmpWEa+DuQyY/AoohtGQR9KHRAxxAr0SsvFrC+/phJ
xkozkqhy5/snqiqbVgDcqxqFBqHO23IYAbWjaCWG3M2/9HPOjw7tJwM7P2d6LQuz
mQi3+FY3sIKgjGS6T9vKYpt3PE3KmziVkzL13iU0yX/iuatjrhUKapifwPZfiKc=
=Ihgt
-----END PGP SIGNATURE-----
Merge tag 'v4.7-rc1' into patchwork
Linux 4.7-rc1
* tag 'v4.7-rc1': (10534 commits)
Linux 4.7-rc1
hash_string: Fix zero-length case for !DCACHE_WORD_ACCESS
Rename other copy of hash_string to hashlen_string
hpfs: implement the show_options method
affs: fix remount failure when there are no options changed
hpfs: fix remount failure when there are no options changed
fs: fix binfmt_aout.c build error
h8300: Add <asm/hash.h>
microblaze: Add <asm/hash.h>
m68k: Add <asm/hash.h>
<linux/hash.h>: Add support for architecture-specific functions
fs/namei.c: Improve dcache hash function
Eliminate bad hash multipliers from hash_32() and hash_64()
Change hash_64() return value to 32 bits
<linux/sunrpc/svcauth.h>: Define hash_str() in terms of hashlen_string()
fs/namei.c: Add hashlen_string() function
Pull out string hash to <linux/stringhash.h>
Revert "platform/chrome: chromeos_laptop: Add Leon Touch"
i2c: dev: use after free in detach
MIPS: Add missing FROZEN hotplug notifier transitions
...
If the documentation comment does not have params or sections, the
section heading may leak from the previous documentation comment.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
If there are multiple sections with the same section name, the current
implementation results in several sections by the same heading, with the
content duplicated from the last section to all. Even if there's the
error message, a more graceful approach is to combine all the
identically named sections into one, with concatenated contents.
With the supported sections already limited to select few, there are
massively fewer collisions than there used to be, but this is still
useful for e.g. when function parameters are documented in the middle of
a documentation comment, with description spread out above and
below. (This is not a recommended documentation style, but used in the
kernel nonetheless.)
We can now also demote the error to a warning.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
kernel-doc currently identifies anything matching "section header:"
(specifically a string of word characters and spaces followed by a
colon) as a new section in the documentation comment, and renders the
section header accordingly.
Unfortunately, this turns all uses of colon into sections, mostly
unintentionally. Considering the output, erroneously creating sections
when not intended is always worse than erroneously not creating sections
when intended. For example, a line with "http://example.com" turns into
a "http" heading followed by "//example.com" in normal text style, which
is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even
if "WARNING" does not turn into a heading.
It is virtually impossible to change all the kernel-doc comments, either
way. The compromise is to pick the most commonly used and depended on
section headers (with variants) and accept them as section headers.
The accepted section headers are, case insensitive:
* description:
* context:
* return:
* returns:
Additionally, case sensitive:
* @return:
All of the above are commonly used in the kernel-doc comments, and will
result in worse output if not identified as section headers. Also,
kernel-doc already has some special handling for all of them, so there's
nothing particularly controversial in adding more special treatment for
them.
While at it, improve the whitespace handling surrounding section
names. Do not consider the whitespace as part of the name.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
If a param description spans multiple lines, check any leading
whitespace in the first continuation line, and remove same amount of
whitespace from following lines.
This allows indentation in the multi-line parameter descriptions for
aesthetical reasons while not causing accidentally significant
indentation in the rst output.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Handle whitespace on the first line of param text as if it was the empty
string. There is no need to add the newline in this case. This improves
the rst output in particular, where blank lines may be problematic in
parameter lists.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Move away from field lists, and simply use **strong emphasis** for
section headings on lines of their own. Do not use rst section headings,
because their nesting depth depends on the surrounding context, which
kernel-doc has no knowledge of. Also, they do not need to end up in any
table of contexts or indexes.
There are two related immediate benefits. Field lists are typically
rendered in two columns, while the new style uses the horizontal width
better. With no extra indent on the left, there's no need to be as fussy
about it. Field lists are more susceptible to indentation problems than
the new style.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
The inline member markup allows whitespace lines before the actual
documentation starts. Strip the leading blank lines. This improves the
rst output.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
The use of these is confusing in the script, and per this grep, they're
not used anywhere anyway:
$ git grep " \* [%$&][a-zA-Z0-9_]*:" -- *.[ch] | grep -v "\$\(Id\|Revision\|Date\)"
While at it, throw out the constants array, nothing is ever put there
again.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Link "&foo->bar", "&foo->bar()", "&foo.bar", and "&foo.bar()" to the
struct/union/enum foo definition. The members themselves do not
currently have anchors to link to, but this is better than nothing, and
promotes a universal notation.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
