Re: [PATCH] MAINTAINERS & files: Canonize the e-mails I use at files
On Fri, 04 May 2018, Mauro Carvalho Chehab <mchehab+sams...@kernel.org> wrote: > From now on, I'll start using my @kernel.org as my development e-mail. > > As such, let's remove the entries that point to the old > mche...@s-opensource.com at MAINTAINERS file. > > For the files written with a copyright with mchehab@s-opensource, > let's keep Samsung on their names, using mchehab+sams...@kernel.org, > in order to keep pointing to my employer, with sponsors the work. > > For the files written before I join Samsung (on July, 4 2013), > let's just use mche...@kernel.org. > > For bug reports, we can simply point to just kernel.org, as > this will reach my mchehab+samsung inbox anyway. I suppose this begs the question, why do we insist on adding our email addresses all over the place? On a quick grep, there are at least 40k+ email addresses in the sources. Do we expect them all to be up-to-date too? BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
Re: Linux 4.16 Kernel Boot Crash
81747] rmi_create_function+0x112/0x1a0 [rmi_core] > [ 43.184677] ? rmi_driver_clear_irq_bits+0xc0/0xc0 [rmi_core] > [ 43.187505] rmi_scan_pdt+0xca/0x1a0 [rmi_core] > [ 43.190171] rmi_init_functions+0x5b/0x120 [rmi_core] > [ 43.192809] rmi_driver_probe+0x152/0x3c0 [rmi_core] > [ 43.195403] ? sysfs_create_link+0x25/0x40 > [ 43.198253] driver_probe_device+0x310/0x480 > [ 43.201083] __device_attach_driver+0x86/0x100 > [ 43.203800] ? __driver_attach+0xf0/0xf0 > [ 43.206503] bus_for_each_drv+0x6b/0xb0 > [ 43.209291] __device_attach+0xdd/0x160 > [ 43.212207] device_initial_probe+0x13/0x20 > [ 43.215146] bus_probe_device+0x95/0xa0 > [ 43.217885] device_add+0x44b/0x680 > [ 43.220597] rmi_register_transport_device+0x84/0x100 [rmi_core] > [ 43.223321] rmi_input_configured+0xbf/0x1a0 [hid_rmi] > [ 43.226051] ? input_allocate_device+0xdf/0xf0 > [ 43.228814] hidinput_connect+0x4a9/0x37a0 [hid] > [ 43.231701] hid_connect+0x326/0x3d0 [hid] > [ 43.234548] hid_hw_start+0x42/0x70 [hid] > [ 43.237302] rmi_probe+0x115/0x510 [hid_rmi] > [ 43.239862] hid_device_probe+0xd3/0x150 [hid] > [ 43.242558] ? sysfs_create_link+0x25/0x40 > [ 43.242828] audit: type=1400 audit(1522795151.600:4): > apparmor="STATUS" operation="profile_load" profile="unconfined" > name="/snap/core/4206/usr/lib/snapd/snap-confine" pid=1151 > comm="apparmor_parser" > [ 43.244859] driver_probe_device+0x310/0x480 > [ 43.244862] __driver_attach+0xbf/0xf0 > [ 43.246982] audit: type=1400 audit(1522795151.600:5): > apparmor="STATUS" operation="profile_load" profile="unconfined" > name="/snap/core/4206/usr/lib/snapd/snap-confine//mount-namespace-capture-helper" > > pid=1151 comm="apparmor_parser" > [ 43.249403] ? driver_probe_device+0x480/0x480 > [ 43.249405] bus_for_each_dev+0x74/0xb0 > [ 43.253200] audit: type=1400 audit(1522795151.600:6): > apparmor="STATUS" operation="profile_load" profile="unconfined" > name="/snap/core/4206/usr/lib/snapd/snap-confine//snap_update_ns" > pid=1151 comm="apparmor_parser" > [ 43.254055] ? kmem_cache_alloc_trace+0x1a6/0x1c0 > [ 43.256282] audit: type=1400 audit(1522795151.604:7): > apparmor="STATUS" operation="profile_load" profile="unconfined" > name="/sbin/dhclient" pid=1152 comm="apparmor_parser" > [ 43.258436] driver_attach+0x1e/0x20 > [ 43.260875] audit: type=1400 audit(1522795151.604:8): > apparmor="STATUS" operation="profile_load" profile="unconfined" > name="/usr/lib/NetworkManager/nm-dhcp-client.action" pid=1152 > comm="apparmor_parser" > [ 43.263118] bus_add_driver+0x167/0x260 > [ 43.267676] audit: type=1400 audit(1522795151.604:9): > apparmor="STATUS" operation="profile_load" profile="unconfined" > name="/usr/lib/NetworkManager/nm-dhcp-helper" pid=1152 > comm="apparmor_parser" > [ 43.268807] ? 0xc0cbc000 > [ 43.268812] driver_register+0x60/0xe0 > [ 43.271184] audit: type=1400 audit(1522795151.604:10): > apparmor="STATUS" operation="profile_load" profile="unconfined" > name="/usr/lib/connman/scripts/dhclient-script" pid=1152 > comm="apparmor_parser" > [ 43.274081] ? 0xc0cbc000 > [ 43.274086] __hid_register_driver+0x63/0x70 [hid] > [ 43.288367] rmi_driver_init+0x23/0x1000 [hid_rmi] > [ 43.291501] do_one_initcall+0x52/0x191 > [ 43.292348] audit: type=1400 audit(1522795151.652:11): > apparmor="STATUS" operation="profile_load" profile="unconfined" > name="/usr/bin/man" pid=1242 comm="apparmor_parser" > [ 43.294212] ? _cond_resched+0x19/0x40 > [ 43.300028] ? kmem_cache_alloc_trace+0xa2/0x1c0 > [ 43.303475] ? do_init_module+0x27/0x209 > [ 43.306842] do_init_module+0x5f/0x209 > [ 43.310269] load_module+0x1987/0x1f10 > [ 43.313704] ? ima_post_read_file+0x96/0xa0 > [ 43.317174] SYSC_finit_module+0xfc/0x120 > [ 43.320754] ? SYSC_finit_module+0xfc/0x120 > [ 43.324065] SyS_finit_module+0xe/0x10 > [ 43.327387] do_syscall_64+0x73/0x130 > [ 43.330909] entry_SYSCALL_64_after_hwframe+0x3d/0xa2 > [ 43.334305] RIP: 0033:0x7fd2d880b839 > [ 43.337810] RSP: 002b:7ffe0a6b2368 EFLAGS: 0246 ORIG_RAX: > 0139 > [ 43.341259] RAX: ffda RBX: 55cdd86542e0 RCX: > 7fd2d880b839 > [ 43.344613] RDX: RSI: 7fd2d84ea0e5 RDI: > 0016 > [ 43.347962] RBP: 7fd2d84ea0e5 R08: R09: > 7ffe0a6b2480 > [ 43.351456] R10: 0016 R11: 0246 R12: > > [ 43.354845] R13: 55cdd8688930 R14: 0002 R15: > 55cdd86542e0 > [ 43.358224] Code: c7 05 ad 12 02 00 00 00 00 00 48 8d 88 00 08 00 00 > eb 09 48 83 c0 08 48 39 c1 74 31 48 8b 10 48 85 d2 74 ef 49 8b b7 98 04 > 00 00 <48> 39 b2 98 04 00 00 75 df 48 63 92 f8 04 00 00 f0 48 0f ab 15 > [ 43.361764] RIP: __video_register_device+0x1cc/0x1090 [videodev] RSP: > a5c5c231b420 > [ 43.365281] CR2: 0499 > ___ > Intel-gfx mailing list > intel-...@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/intel-gfx -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCHv2 6/7] cec-pin-error-inj.rst: document CEC Pin Error Injection
On Wed, 21 Mar 2018, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: > Please notice that all debugfs/sysfs entries should *also* be > documented at the standard way, e. g. by adding the corresponding > documentation at Documentation/ABI. > > Please see Documentation/ABI/README. > > Additionally, there are a few minor nitpicks on this patch. > See below. > > The remaining patches looked ok on my eyes. > > I'll wait for a v3 with the debugfs ABI documentation in order to merge > it. Feel free to put it on a separate patch. debugfs ABI? Sounds like an oxymoron to me. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH v3 05/10] pwm: add PWM mode to pwm_config()
On Wed, 28 Feb 2018, Thierry Reding <thierry.red...@gmail.com> wrote: > Anyone that needs something other than normal mode should use the new > atomic PWM API. At the risk of revealing my true ignorance, what is the new atomic PWM API? Where? Examples of how one would convert old code over to the new API? BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH v3 05/10] pwm: add PWM mode to pwm_config()
On Thu, 22 Feb 2018, Daniel Thompson <daniel.thomp...@linaro.org> wrote:
> On Thu, Feb 22, 2018 at 02:01:16PM +0200, Claudiu Beznea wrote:
>> Add PWM mode to pwm_config() function. The drivers which uses pwm_config()
>> were adapted to this change.
>>
>> Signed-off-by: Claudiu Beznea <claudiu.bez...@microchip.com>
>> ---
>> arch/arm/mach-s3c24xx/mach-rx1950.c | 11 +--
>> drivers/bus/ts-nbus.c| 2 +-
>> drivers/clk/clk-pwm.c| 3 ++-
>> drivers/gpu/drm/i915/intel_panel.c | 17 ++---
>> drivers/hwmon/pwm-fan.c | 2 +-
>> drivers/input/misc/max77693-haptic.c | 2 +-
>> drivers/input/misc/max8997_haptic.c | 6 +-
>> drivers/leds/leds-pwm.c | 5 -
>> drivers/media/rc/ir-rx51.c | 5 -
>> drivers/media/rc/pwm-ir-tx.c | 5 -
>> drivers/video/backlight/lm3630a_bl.c | 4 +++-
>> drivers/video/backlight/lp855x_bl.c | 4 +++-
>> drivers/video/backlight/lp8788_bl.c | 5 -
>> drivers/video/backlight/pwm_bl.c | 11 +--
>> drivers/video/fbdev/ssd1307fb.c | 3 ++-
>> include/linux/pwm.h | 6 --
>> 16 files changed, 70 insertions(+), 21 deletions(-)
>>
>> diff --git a/drivers/video/backlight/lm3630a_bl.c
>> b/drivers/video/backlight/lm3630a_bl.c
>> index 2030a6b77a09..696fa25dafd2 100644
>> --- a/drivers/video/backlight/lm3630a_bl.c
>> +++ b/drivers/video/backlight/lm3630a_bl.c
>> @@ -165,8 +165,10 @@ static void lm3630a_pwm_ctrl(struct lm3630a_chip
>> *pchip, int br, int br_max)
>> {
>> unsigned int period = pchip->pdata->pwm_period;
>> unsigned int duty = br * period / br_max;
>> +struct pwm_caps caps = { };
>>
>> -pwm_config(pchip->pwmd, duty, period);
>> +pwm_get_caps(pchip->pwmd->chip, pchip->pwmd, );
>> +pwm_config(pchip->pwmd, duty, period, BIT(ffs(caps.modes) - 1));
>
> Well... I admit I've only really looked at the patches that impact
> backlight but dispersing this really odd looking bit twiddling
> throughout the kernel doesn't strike me a great API design.
>
> IMHO callers should not be required to find the first set bit in
> some specially crafted set of capability bits simply to get sane
> default behaviour.
Agreed. IMHO the regular use case becomes rather tedious, ugly, and
error prone.
BR,
Jani.
--
Jani Nikula, Intel Open Source Technology Center
Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers
On Wed, 14 Feb 2018, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
> There is a simple fix, though. Make inline comments to accept a dot:
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index fee8952037b1..06d7f3f2c094 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
> my $doc_content = $doc_com_body . '(.*)';
> my $doc_block = $doc_com . 'DOC:\s*(.*)?';
> my $doc_inline_start = '^\s*/\*\*\s*$';
> -my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
> +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
> my $doc_inline_end = '^\s*\*/\s*$';
> my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
> my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
>
> That requires a small change at the inline parameters, though:
>
> diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c
> b/drivers/gpu/drm/i915/intel_dpio_phy.c
> index 76473e9836c6..c8e9e44e5981 100644
> --- a/drivers/gpu/drm/i915/intel_dpio_phy.c
> +++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
> @@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
>*/
> struct {
> /**
> - * @port: which port maps to this channel.
> + * @channel.port: which port maps to this channel.
>*/
> enum port port;
> } channel[2];
Perhaps it would be slightly more elegant to be able to leave out
"channel." here and deduce that from the context... but the above
matches what you'd write in the higher level struct comment, and
produces the same output. It works and it's really simple. I like it.
Please submit this as a proper patch, with
Tested-by: Jani Nikula <jani.nik...@intel.com>
BR,
Jani.
--
Jani Nikula, Intel Open Source Technology Center
Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers
next;
> + }
> + foreach my $name (split /,/, $names) {
> + $name =~ s/^\s*\**(\S+)\s*/$1/;
> + next if (($name =~ m/^\s*$/));
> + if ($id =~ m/^\s*$/) {
> + # anonymous struct/union
> + $newmember .= "$type
> $name; ";
> + } else {
> + $newmember .= "$type
> $id.$name; ";
> + }
> }
> }
> }
> - $members =~
> s/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/$newmember/;
> - $cont = 1;
> - };
> - };
> + }
> + $members =~
> s/(struct|union)([^\{\};]+)\{([^\{\}]*)}([^\{\}\;]*)\;/$newmember/;
> + }
>
> # Ignore other nested elements, like enums
> $members =~ s/({[^\{\}]*})//g;
--
Jani Nikula, Intel Open Source Technology Center
Re: [-next PATCH 0/4] sysfs and DEVICE_ATTR_
On Tue, 19 Dec 2017, Joe Perches <j...@perches.com> wrote: > drivers/gpu/drm/i915/i915_sysfs.c | 12 ++-- For i915, Acked-by: Jani Nikula <jani.nik...@intel.com> -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH 01/10] scripts: kernel-doc: get rid of unused output formats
On Tue, 26 Sep 2017, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: > Since there isn't any docbook code anymore upstream, > we can get rid of several output formats: > > - docbook/xml, html, html5 and list formats were used by > the old build system; > - As ReST is text, there's not much sense on outputting > on a different text format. > > After this patch, only man and rst output formats are > supported. FWIW, Acked-by: Jani Nikula <jani.nik...@intel.com> Please do keep at least two output formats going forward. Otherwise the mechanisms of having more than one output format will bitrot and get conflated into the one output format. > > Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com> > --- > scripts/kernel-doc | 1182 > +--- > 1 file changed, 4 insertions(+), 1178 deletions(-) > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index 9d3eafea58f0..69757ee9db4c 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -51,13 +51,8 @@ The documentation comments are identified by "/**" opening > comment mark. See > Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax. > > Output format selection (mutually exclusive): > - -docbook Output DocBook format. > - -html Output HTML format. > - -html5 Output HTML5 format. > - -list Output symbol list format. This is for use by > docproc. >-man Output troff manual page format. This is the > default. >-rst Output reStructuredText format. > - -text Output plain text format. > > Output selection (mutually exclusive): >-exportOnly output documentation for symbols that have been > @@ -224,84 +219,11 @@ my $type_typedef = '\&(typedef\s*([_\w]+))'; > my $type_union = '\&(union\s*([_\w]+))'; > my $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; > my $type_fallback = '\&([_\w]+)'; > -my $type_enum_xml = '\(enum\s*([_\w]+))'; > -my $type_struct_xml = '\(struct\s*([_\w]+))'; > -my $type_typedef_xml = '\(typedef\s*([_\w]+))'; > -my $type_union_xml = '\(union\s*([_\w]+))'; > -my $type_member_xml = '\([_\w]+)(\.|-\)([_\w]+)'; > -my $type_fallback_xml = '\([_\w]+)'; > my $type_member_func = $type_member . '\(\)'; > > # Output conversion substitutions. > # One for each output format > > -# these work fairly well > -my @highlights_html = ( > - [$type_constant, "\$1"], > - [$type_constant2, "\$1"], > - [$type_func, "\$1"], > - [$type_enum_xml, "\$1"], > - [$type_struct_xml, "\$1"], > - [$type_typedef_xml, "\$1"], > - [$type_union_xml, "\$1"], > - [$type_env, "\$1"], > - [$type_param, "\$1"], > - [$type_member_xml, "\$1\$2\$3"], > - [$type_fallback_xml, "\$1"] > - ); > -my $local_lt = "lt:"; > -my $local_gt = "gt:"; > -my $blankline_html = $local_lt . "p" . $local_gt;# was "" > - > -# html version 5 > -my @highlights_html5 = ( > -[$type_constant, "\$1"], > -[$type_constant2, " class=\"const\">\$1"], > -[$type_func, "\$1"], > -[$type_enum_xml, "\$1"], > -[$type_struct_xml, " class=\"struct\">\$1"], > -[$type_typedef_xml, " class=\"typedef\">\$1"], > -[$type_union_xml, " class=\"union\">\$1"], > -[$type_env, "\$1"], > -[$type_param, "\$1]"], > -[$type_member_xml, " class=\"struct\">\$1\$2\$3"], > -[$type_fallback_xml, " class=\"struct\">\$1"] > -); > -my $blankline_html5 = $local_lt . "br /" . $local_gt; > - > -# XML, docbook format > -my @highlights_xml = ( > - ["([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2"], > - [$type_constant, "\$1"], > - [$type_consta
Re: [PATCH 1/2] docs: kernel-doc comments are ASCII
On Thu, 31 Aug 2017, Randy Dunlap <rdun...@infradead.org> wrote: > On 08/31/17 09:36, Jani Nikula wrote: >> On Thu, 31 Aug 2017, Jani Nikula <jani.nik...@linux.intel.com> wrote: >>> On Thu, 31 Aug 2017, Randy Dunlap <rdun...@infradead.org> wrote: >>>> On 08/31/17 07:17, Jonathan Corbet wrote: >>>>> On Thu, 31 Aug 2017 10:56:26 -0300 >>>>> Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: >>>>> >>>>>> It should have something to do with python version and/or to some >>>>>> locale info at the system, as neither I or Jon can reproduce it. >>>>> >>>>> I can't reproduce it here, but I have certainly seen situations where >>>>> Python 2 wants to run with the ascii codec by default. >>>>> >>>>> Note that the exception happens in our Sphinx extension, not in Sphinx >>>>> itself. We've had other non-ascii text in our docs, so I think Sphinx is >>>>> doing the right thing. The problem is with our own code. If I could >>>>> reproduce it, it shouldn't be too hard to track down - take out that >>>>> massive "except anything" block and see where it explodes. >>>>> >>>>> Randy, which distribution are you running, and are you using their version >>>>> of Sphinx? >>>> >>>> opensuse LEAP 42.2 >>>> Yes, their sphinx 1.3.1. >>> >>> What's your LANG setting? I think that's what it boils down to, and >>> trying to work around non-UTF-8 LANG in both python 2 and 3 compatible >>> ways. >>> >>> The odd thing is that I can reproduce the issue using a small python >>> snippet, but not through Sphinx. >> >> Your original error message suggests your Sphinx actually uses python >> 3. Can you check that? The clue is that it's the *decode* that fails. > > Where do you see that clue? The message, "'ascii' codec can't decode byte 0xe2 in position 6368: ordinal not in range(128)". In my testing I could only get that *decode* error message using python 3. > My /usr/bin/python is linked to python2.7: > >> ll /usr/bin/python > lrwxrwxrwx 1 root root 9 Jun 10 19:59 /usr/bin/python -> python2.7* Sure, but how about 'head $(which sphinx-build)'? I could be completely mistaken too. ;) >> Does the below patch help? It avoids the implicit ascii decoding due to >> universal_newlines=True and your LANG setting, and does explicit utf-8 >> decoding instead. >> >> Fingers crossed. > > testing now. Thanks. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH 1/2] docs: kernel-doc comments are ASCII
On Thu, 31 Aug 2017, Jani Nikula <jani.nik...@linux.intel.com> wrote:
> On Thu, 31 Aug 2017, Randy Dunlap <rdun...@infradead.org> wrote:
>> On 08/31/17 07:17, Jonathan Corbet wrote:
>>> On Thu, 31 Aug 2017 10:56:26 -0300
>>> Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
>>>
>>>> It should have something to do with python version and/or to some
>>>> locale info at the system, as neither I or Jon can reproduce it.
>>>
>>> I can't reproduce it here, but I have certainly seen situations where
>>> Python 2 wants to run with the ascii codec by default.
>>>
>>> Note that the exception happens in our Sphinx extension, not in Sphinx
>>> itself. We've had other non-ascii text in our docs, so I think Sphinx is
>>> doing the right thing. The problem is with our own code. If I could
>>> reproduce it, it shouldn't be too hard to track down - take out that
>>> massive "except anything" block and see where it explodes.
>>>
>>> Randy, which distribution are you running, and are you using their version
>>> of Sphinx?
>>
>> opensuse LEAP 42.2
>> Yes, their sphinx 1.3.1.
>
> What's your LANG setting? I think that's what it boils down to, and
> trying to work around non-UTF-8 LANG in both python 2 and 3 compatible
> ways.
>
> The odd thing is that I can reproduce the issue using a small python
> snippet, but not through Sphinx.
Your original error message suggests your Sphinx actually uses python
3. Can you check that? The clue is that it's the *decode* that fails.
Does the below patch help? It avoids the implicit ascii decoding due to
universal_newlines=True and your LANG setting, and does explicit utf-8
decoding instead.
Fingers crossed.
BR,
Jani.
diff --git a/Documentation/sphinx/kerneldoc.py
b/Documentation/sphinx/kerneldoc.py
index d15e07f36881..39aa9e8697cc 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -27,6 +27,7 @@
# Please make sure this works on both python2 and python3.
#
+import codecs
import os
import subprocess
import sys
@@ -88,13 +89,10 @@ class KernelDocDirective(Directive):
try:
env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
-p = subprocess.Popen(cmd, stdout=subprocess.PIPE,
stderr=subprocess.PIPE, universal_newlines=True)
+p = subprocess.Popen(cmd, stdout=subprocess.PIPE,
stderr=subprocess.PIPE)
out, err = p.communicate()
-# python2 needs conversion to unicode.
-# python3 with universal_newlines=True returns strings.
-if sys.version_info.major < 3:
-out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8')
+out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
if p.returncode != 0:
sys.stderr.write(err)
--
Jani Nikula, Intel Open Source Technology Center
Re: [PATCH 1/2] docs: kernel-doc comments are ASCII
On Thu, 31 Aug 2017, Randy Dunlap <rdun...@infradead.org> wrote: > On 08/31/17 07:17, Jonathan Corbet wrote: >> On Thu, 31 Aug 2017 10:56:26 -0300 >> Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: >> >>> It should have something to do with python version and/or to some >>> locale info at the system, as neither I or Jon can reproduce it. >> >> I can't reproduce it here, but I have certainly seen situations where >> Python 2 wants to run with the ascii codec by default. >> >> Note that the exception happens in our Sphinx extension, not in Sphinx >> itself. We've had other non-ascii text in our docs, so I think Sphinx is >> doing the right thing. The problem is with our own code. If I could >> reproduce it, it shouldn't be too hard to track down - take out that >> massive "except anything" block and see where it explodes. >> >> Randy, which distribution are you running, and are you using their version >> of Sphinx? > > opensuse LEAP 42.2 > Yes, their sphinx 1.3.1. What's your LANG setting? I think that's what it boils down to, and trying to work around non-UTF-8 LANG in both python 2 and 3 compatible ways. The odd thing is that I can reproduce the issue using a small python snippet, but not through Sphinx. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH 1/2] docs: kernel-doc comments are ASCII
On Thu, 31 Aug 2017, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: > As Documentation/conf.py has: > > # -*- coding: utf-8 -*- > > on its first line, I suspect that the error you're getting is likely > due to the usage of a python version that doesn't recognize this. AFAIK that has nothing to do with python I/O, and everything to do with the encoding of that specific python source file. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH, RESEND 03/14] drm/vmwgfx: avoid gcc-7 parentheses warning
On Fri, 14 Jul 2017, Arnd Bergmann <a...@arndb.de> wrote:
> gcc-7 warns about slightly suspicious code in vmw_cmd_invalid:
>
> drivers/gpu/drm/vmwgfx/vmwgfx_execbuf.c: In function 'vmw_cmd_invalid':
> drivers/gpu/drm/vmwgfx/vmwgfx_execbuf.c:522:23: error: the omitted middle
> operand in ?: will always be 'true', suggest explicit middle operand
> [-Werror=parentheses]
>
> The problem is that it is mixing boolean and integer values here.
> I assume that the code actually works correctly, so making it use
> a literal '1' instead of the implied 'true' makes it more readable
> and avoids the warning.
>
> The code has been in this file since the start, but it could
> make sense to backport this patch to stable to make it build cleanly
> with gcc-7.
>
> Fixes: fb1d9738ca05 ("drm/vmwgfx: Add DRM driver for VMware Virtual GPU")
> Reviewed-by: Sinclair Yeh <s...@vmware.com>
> Signed-off-by: Arnd Bergmann <a...@arndb.de>
> ---
> Originally submitted on Nov 16, but for some reason it never appeared
> upstream. The patch is still needed as of v4.11-rc2
See also the thread starting at
http://lkml.kernel.org/r/CA+55aFwZV-QirBTY8y4y+h796V2CzpWdL=twb27rj1u3roj...@mail.gmail.com
BR,
Jani.
> ---
> drivers/gpu/drm/vmwgfx/vmwgfx_execbuf.c | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/drivers/gpu/drm/vmwgfx/vmwgfx_execbuf.c
> b/drivers/gpu/drm/vmwgfx/vmwgfx_execbuf.c
> index c7b53d987f06..3f343e55972a 100644
> --- a/drivers/gpu/drm/vmwgfx/vmwgfx_execbuf.c
> +++ b/drivers/gpu/drm/vmwgfx/vmwgfx_execbuf.c
> @@ -519,7 +519,7 @@ static int vmw_cmd_invalid(struct vmw_private *dev_priv,
> struct vmw_sw_context *sw_context,
> SVGA3dCmdHeader *header)
> {
> - return capable(CAP_SYS_ADMIN) ? : -EINVAL;
> + return capable(CAP_SYS_ADMIN) ? 1 : -EINVAL;
> }
>
> static int vmw_cmd_ok(struct vmw_private *dev_priv,
--
Jani Nikula, Intel Open Source Technology Center
Re: [RFC PATCH 7/7] drm/i915: add DisplayPort CEC-Tunneling-over-AUX support
On Tue, 30 May 2017, Hans Verkuil <hverk...@xs4all.nl> wrote: > On 05/29/2017 09:00 PM, Daniel Vetter wrote: >> On Fri, May 26, 2017 at 12:20:48PM +0200, Hans Verkuil wrote: >>> On 05/26/2017 09:15 AM, Daniel Vetter wrote: >>>> Did you look into also wiring this up for dp mst chains? >>> >>> Isn't this sufficient? I have no way of testing mst chains. >>> >>> I think I need some pointers from you, since I am a complete newbie when it >>> comes to mst. >> >> I don't really have more clue, but yeah if you don't have an mst thing (a >> simple dp port multiplexer is what I use for testing here, then plug in a >> converter dongle or cable into that) then probably better to not wire up >> the code for it. > > I think my NUC already uses mst internally. But I was planning on buying a > dp multiplexer to make sure there is nothing special I need to do for mst. > > The CEC Tunneling is all in the branch device, so if I understand things > correctly it is not affected by mst. > > BTW, I did a bit more testing on my NUC7i5BNK: for the HDMI output they > use a MegaChip MCDP2800 DP-to-HDMI converter which according to their > datasheet is supposed to implement CEC Tunneling, but if they do it is not > exposed as a capability. I'm not sure if it is a MegaChip firmware issue > or something else. The BIOS is able to do some CEC, but whether they hook > into the MegaChip or have the CEC pin connected to a GPIO or something and > have their own controller is something I do not know. > > If anyone can clarify what Intel did on the NUC, then that would be very > helpful. It's called LSPCON, see i915/intel_lspcon.c, basically to support HDMI 2.0. Currently we only use it in PCON mode, shows up as DP for us. It could be used in LS mode, showing up as HDMI 1.4, but we don't support that in i915. I don't know about the CEC on that. BR, Jani. > > It would be so nice to get MegaChip CEC Tunneling working on the NUC, because > then you have native CEC support without requiring any Pulse Eight adapter. > > And add a CEC-capable USB-C to HDMI adapter and you have it on the USB-C > output as well. > > Regards, > > Hans -- Jani Nikula, Intel Open Source Technology Center
Re: [RFC PATCH 7/7] drm/i915: add DisplayPort CEC-Tunneling-over-AUX support
On Thu, 25 May 2017, Hans Verkuil <hverk...@xs4all.nl> wrote:
> @@ -4179,6 +4181,33 @@ intel_dp_check_mst_status(struct intel_dp *intel_dp)
> return -EINVAL;
> }
>
> +static bool
> +intel_dp_check_cec_status(struct intel_dp *intel_dp)
> +{
> + bool handled = false;
> +
> + for (;;) {
> + u8 cec_irq;
> + int ret;
> +
> + ret = drm_dp_dpcd_readb(_dp->aux,
> + DP_DEVICE_SERVICE_IRQ_VECTOR_ESI1,
> + _irq);
> + if (ret < 0 || !(cec_irq & DP_CEC_IRQ))
> + return handled;
> +
> + cec_irq &= ~DP_CEC_IRQ;
> + drm_dp_cec_irq(_dp->aux);
> + handled = true;
> +
> + ret = drm_dp_dpcd_writeb(_dp->aux,
> + DP_DEVICE_SERVICE_IRQ_VECTOR_ESI1,
> + cec_irq);
> + if (ret < 0)
> + return handled;
> + }
DP sinks suck. Please add a limit to the loop.
BR,
Jani.
--
Jani Nikula, Intel Open Source Technology Center
Re: [RFC PATCH 5/7] drm/cec: Add CEC over Aux register definitions
On Thu, 25 May 2017, Hans Verkuil <hverk...@xs4all.nl> wrote: > From: Clint Taylor <clinton.a.tay...@intel.com> > > Adding DPCD register definitions from the DP 1.3 specification for CEC > over AUX support. > > V2: Add DP_ prefix to all defines. > V3: missed prefixes from the ESI1 defines > > Cc: Jani Nikula <jani.nik...@linux.intel.com> > > Reviewed-by: Jani Nikula <jani.nik...@intel.com> > Signed-off-by: Clint Taylor <clinton.a.tay...@intel.com> > Signed-off-by: Jani Nikula <jani.nik...@intel.com> > Link: > http://patchwork.freedesktop.org/patch/msgid/1492703263-11494-1-git-send-email-clinton.a.tay...@intel.com This one's already in drm-next as commit d753e41d475421543eaaea5f0feadba827f5fa01 Author: Clint Taylor <clinton.a.tay...@intel.com> Date: Thu Apr 20 08:47:43 2017 -0700 drm/cec: Add CEC over Aux register definitions BR, Jani. > --- > include/drm/drm_dp_helper.h | 59 > + > 1 file changed, 59 insertions(+) > > diff --git a/include/drm/drm_dp_helper.h b/include/drm/drm_dp_helper.h > index c0bd0d7651a9..3f4ad709534e 100644 > --- a/include/drm/drm_dp_helper.h > +++ b/include/drm/drm_dp_helper.h > @@ -603,6 +603,9 @@ > #define DP_DEVICE_SERVICE_IRQ_VECTOR_ESI0 0x2003 /* 1.2 */ > > #define DP_DEVICE_SERVICE_IRQ_VECTOR_ESI1 0x2004 /* 1.2 */ > +# define DP_RX_GTC_MSTR_REQ_STATUS_CHANGE(1 << 0) > +# define DP_LOCK_ACQUISITION_REQUEST (1 << 1) > +# define DP_CEC_IRQ (1 << 2) > > #define DP_LINK_SERVICE_IRQ_VECTOR_ESI0 0x2005 /* 1.2 */ > > @@ -636,6 +639,62 @@ > # define DP_VSC_EXT_CEA_SDP_SUPPORTED(1 << 6) /* DP > 1.4 */ > # define DP_VSC_EXT_CEA_SDP_CHAINING_SUPPORTED (1 << 7) /* DP > 1.4 */ > > +/* HDMI CEC tunneling over AUX DP 1.3 section 5.3.3.3.1 DPCD 1.4+ */ > +#define DP_CEC_TUNNELING_CAPABILITY0x3000 > +# define DP_CEC_TUNNELING_CAPABLE (1 << 0) > +# define DP_CEC_SNOOPING_CAPABLE(1 << 1) > +# define DP_CEC_MULTIPLE_LA_CAPABLE (1 << 2) > + > +#define DP_CEC_TUNNELING_CONTROL 0x3001 > +# define DP_CEC_TUNNELING_ENABLE(1 << 0) > +# define DP_CEC_SNOOPING_ENABLE (1 << 1) > + > +#define DP_CEC_RX_MESSAGE_INFO 0x3002 > +# define DP_CEC_RX_MESSAGE_LEN_MASK (0xf << 0) > +# define DP_CEC_RX_MESSAGE_LEN_SHIFT0 > +# define DP_CEC_RX_MESSAGE_HPD_STATE(1 << 4) > +# define DP_CEC_RX_MESSAGE_HPD_LOST (1 << 5) > +# define DP_CEC_RX_MESSAGE_ACKED(1 << 6) > +# define DP_CEC_RX_MESSAGE_ENDED(1 << 7) > + > +#define DP_CEC_TX_MESSAGE_INFO 0x3003 > +# define DP_CEC_TX_MESSAGE_LEN_MASK (0xf << 0) > +# define DP_CEC_TX_MESSAGE_LEN_SHIFT0 > +# define DP_CEC_TX_RETRY_COUNT_MASK (0x7 << 4) > +# define DP_CEC_TX_RETRY_COUNT_SHIFT4 > +# define DP_CEC_TX_MESSAGE_SEND (1 << 7) > + > +#define DP_CEC_TUNNELING_IRQ_FLAGS 0x3004 > +# define DP_CEC_RX_MESSAGE_INFO_VALID (1 << 0) > +# define DP_CEC_RX_MESSAGE_OVERFLOW (1 << 1) > +# define DP_CEC_TX_MESSAGE_SENT (1 << 4) > +# define DP_CEC_TX_LINE_ERROR (1 << 5) > +# define DP_CEC_TX_ADDRESS_NACK_ERROR (1 << 6) > +# define DP_CEC_TX_DATA_NACK_ERROR (1 << 7) > + > +#define DP_CEC_LOGICAL_ADDRESS_MASK0x300E /* 0x300F word */ > +# define DP_CEC_LOGICAL_ADDRESS_0 (1 << 0) > +# define DP_CEC_LOGICAL_ADDRESS_1 (1 << 1) > +# define DP_CEC_LOGICAL_ADDRESS_2 (1 << 2) > +# define DP_CEC_LOGICAL_ADDRESS_3 (1 << 3) > +# define DP_CEC_LOGICAL_ADDRESS_4 (1 << 4) > +# define DP_CEC_LOGICAL_ADDRESS_5 (1 << 5) > +# define DP_CEC_LOGICAL_ADDRESS_6 (1 << 6) > +# define DP_CEC_LOGICAL_ADDRESS_7 (1 << 7) > +#define DP_CEC_LOGICAL_ADDRESS_MASK_2 0x300F /* 0x300E word */ > +# define DP_CEC_LOGICAL_ADDRESS_8 (1 << 0) > +# define DP_CEC_LOGICAL_ADDRESS_9 (1 << 1) > +# define DP_CEC_LOGICAL_ADDRESS_10 (1 << 2) > +# define DP_CEC_LOGICAL_ADDRESS_11 (1 << 3) > +# define DP_CEC_LOGICAL_ADDRESS_12 (1 << 4) > +# define DP_CEC_LOGICAL_ADDRESS_13 (1 << 5) > +# define DP_CEC_LOGICAL_ADDRESS_14 (1 << 6) > +# define DP_CEC_LOGICAL_ADDRESS_15 (1 << 7) > + > +#define DP_CEC_RX_MESSAGE_BUFFER 0x3010 > +#define DP_CEC_TX_MESSAGE_BUFFER 0x3020 > +#define DP_CEC_MESSAGE_BUFFER_LENGTH 0x10 > + > /* DP 1.2 Sideband message defines */ > /* peer device type - DP 1.2a Table 2-92 */ > #define DP_PEER_DEVICE_NONE 0x0 -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH v2 01/22] tmplcvt: make the tool more robust
On Thu, 30 Mar 2017, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: > Currently, the script just assumes to be called at > Documentation/sphinx/. Change it to work on any directory, > and make it abort if something gets wrong. > > Also, be sure that both parameters are specified. > > That should avoid troubles like this: > > $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl > sed: couldn't open file convert_template.sed: No such file or directory > > Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com> > --- > Documentation/sphinx/tmplcvt | 13 +++-- > 1 file changed, 11 insertions(+), 2 deletions(-) > > diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt > index 909a73065e0a..31df8eb7feca 100755 > --- a/Documentation/sphinx/tmplcvt > +++ b/Documentation/sphinx/tmplcvt > @@ -7,13 +7,22 @@ > # fix \_ > # title line? > # > +set -eu > + > +if [ "$2" == "" ]; then if [ "$#" != "2" ]; then otherwise with set -u you'll get unbound variable error if you don't provide $2. BR, Jani. > + echo "$0 " > + exit > +fi > + > +DIR=$(dirname $0) > > in=$1 > rst=$2 > tmp=$rst.tmp > > cp $in $tmp > -sed --in-place -f convert_template.sed $tmp > +sed --in-place -f $DIR/convert_template.sed $tmp > pandoc -s -S -f docbook -t rst -o $rst $tmp > -sed --in-place -f post_convert.sed $rst > +sed --in-place -f $DIR/post_convert.sed $rst > rm $tmp > +echo "book writen to $rst" -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST
On Thu, 30 Mar 2017, Markus Heiser <markus.hei...@darmarit.de> wrote: > Hi Mauro, > > Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab > <mche...@s-opensource.com>: > >> As we're moving out of DocBook, let's convert the remaining >> USB docbooks to ReST. >> >> The transformation itself on this patch is a no-brainer >> conversion using pandoc. > > right, its a no-brainer ;-) I'am not very happy with this > conversions, some examples see below. > > I recommend to use a more elaborate conversion as starting point, > e.g. from my sphkerneldoc project: > > * > https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget > * > https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer > * > https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver > > Since these DocBooks hasn't been changed in the last month, the linked reST > should be up to date. Markus, I know you've done a lot of work on your conversions, and you like to advocate them, but AFAICT you have never posted the conversions as patches to the list. Your project isn't a clone of the kernel tree. It's a pile of .rst files that nobody knows how to produce from current upstream DocBook .tmpl files. I'm sorry, but this just doesn't work that way. At this point I'd just go with what Mauro has. It's here now, as patches. We've seen from the GPU documentation that polishing the one-time initial conversion is, after a point, wasted effort. Having the documentation in rst attracts more attention and contributions, and any remaining issues will get ironed out in rst. This is also one reason I'm in favor of just bulk converting the rest of the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook and be done with it, and have the crowds focus on rst. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag
On Thu, 30 Mar 2017, Jani Nikula <jani.nik...@linux.intel.com> wrote: > On Wed, 29 Mar 2017, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: >> The pandoc conversion is not perfect. Do handwork in order to: >> >> - add a title to this chapter; >> - use the proper warning and note markups; >> - use kernel-doc to include Kernel header and c files; > > Please look at Documentation/sphinx/tmplcvt which takes care of all of > that. That said, since you've already manually done the work, you might want to do another conversion using the script, and diff the results to see if there's something you've perhaps missed. I'm pretty sure nobody's going to read patch 2 line-by-line... BR, Jani. > > BR, > Jani. > >> - remove legacy notes with regards to DocBook; >> - some other minor adjustments to make it better to read in >> text mode and in html. >> >> Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com> >> --- >> Documentation/driver-api/usb/gadget.rst | 69 >> + >> 1 file changed, 45 insertions(+), 24 deletions(-) >> >> diff --git a/Documentation/driver-api/usb/gadget.rst >> b/Documentation/driver-api/usb/gadget.rst >> index 4fd9862f3f21..c4c76ebb51d3 100644 >> --- a/Documentation/driver-api/usb/gadget.rst >> +++ b/Documentation/driver-api/usb/gadget.rst >> @@ -1,3 +1,7 @@ >> +Linux-USB "Gadget" kernel mode API >> +~~ >> + >> + >> Introduction >> >> >> @@ -175,16 +179,12 @@ the gadget, and submitting one or more *struct >> usb\_request* buffers to >> transfer data. Understand those four data types, and their operations, >> and you will understand how this API works. >> >> -**Note** >> +.. Note:: >> >> -This documentation was prepared using the standard Linux kernel >> -``docproc`` tool, which turns text and in-code comments into SGML >> -DocBook and then into usable formats such as HTML or PDF. Other than >> -the "Chapter 9" data types, most of the significant data types and >> -functions are described here. >> +Other than the "Chapter 9" data types, most of the significant data >> +types and functions are described here. >> >> -However, docproc does not understand all the C constructs that are >> -used, so some relevant information is likely omitted from what you >> +However, some relevant information is likely omitted from what you >> are reading. One example of such information is endpoint >> autoconfiguration. You'll have to read the header file, and use >> example source code (such as that for "Gadget Zero"), to fully >> @@ -192,10 +192,10 @@ and you will understand how this API works. >> >> The part of the API implementing some basic driver capabilities is >> specific to the version of the Linux kernel that's in use. The 2.6 >> -kernel includes a *driver model* framework that has no analogue on >> -earlier kernels; so those parts of the gadget API are not fully >> -portable. (They are implemented on 2.4 kernels, but in a different >> -way.) The driver model state is another part of this API that is >> +and upper kernel versions include a *driver model* framework that has >> +no analogue on earlier kernels; so those parts of the gadget API are >> +not fully portable. (They are implemented on 2.4 kernels, but in a >> +different way.) The driver model state is another part of this API that >> is >> ignored by the kerneldoc tools. >> >> The core API does not expose every possible hardware feature, only the >> @@ -301,18 +301,19 @@ USB 2.0 Chapter 9 Types and Constants >> - >> >> Gadget drivers rely on common USB structures and constants defined in >> -the header file, which is standard in Linux 2.6 >> -kernels. These are the same types and constants used by host side >> +the :ref:`linux/usb/ch9.h ` header file, which is standard in >> +Linux 2.6+ kernels. These are the same types and constants used by host side >> drivers (and usbcore). >> >> -!Iinclude/linux/usb/ch9.h >> Core Objects and Methods >> >> >> These are declared in , and are used by gadget >> drivers to interact with USB peripheral controller drivers. >> >> -!Iinclude/linux/usb/gadget.h >> +.. kernel-doc:: include/linux/usb/gadget.h >> + :internal
Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag
ass storage device". Management functions may also exist, > such as "Device Firmware Upgrade". > > -!Iinclude/linux/usb/composite.h !Edrivers/usb/gadget/composite.c > +.. kernel-doc:: include/linux/usb/composite.h > + :internal: > + > +.. kernel-doc:: drivers/usb/gadget/composite.c > + :export: > + > Composite Device Functions > -- > > @@ -345,11 +356,21 @@ At this writing, a few of the current gadget drivers > have been converted > to this framework. Near-term plans include converting all of them, > except for "gadgetfs". > > -!Edrivers/usb/gadget/function/f\_acm.c > -!Edrivers/usb/gadget/function/f\_ecm.c > -!Edrivers/usb/gadget/function/f\_subset.c > -!Edrivers/usb/gadget/function/f\_obex.c > -!Edrivers/usb/gadget/function/f\_serial.c > +.. kernel-doc:: drivers/usb/gadget/function/f_acm.c > + :export: > + > +.. kernel-doc:: drivers/usb/gadget/function/f_ecm.c > + :export: > + > +.. kernel-doc:: drivers/usb/gadget/function/f_subset.c > + :export: > + > +.. kernel-doc:: drivers/usb/gadget/function/f_obex.c > + :export: > + > +.. kernel-doc:: drivers/usb/gadget/function/f_serial.c > + :export: > + > Peripheral Controller Drivers > = > > @@ -475,7 +496,7 @@ can also benefit non-OTG products. > - Also on the host side, a driver must support the OTG "Targeted > Peripheral List". That's just a whitelist, used to reject peripherals > not supported with a given Linux OTG host. *This whitelist is > - product-specific; each product must modify ``otg_whitelist.h`` to > + product-specific; each product must modify* ``otg_whitelist.h`` *to > match its interoperability specification.* > > Non-OTG Linux hosts, like PCs and workstations, normally have some -- Jani Nikula, Intel Open Source Technology Center
Re: [Ksummit-discuss] Including images on Sphinx documents
On Mon, 21 Nov 2016, Johannes Berg <johan...@sipsolutions.net> wrote: > I had a hack elsewhere that would embed the fixed-width text if the > plugin isn't present, which seemed like a decent compromise, but nobody > is willing to let plugins be used in general to start with, it seems :) FWIW I'm all for doing this stuff in Sphinx, with Sphinx extensions. And to me it sounds like what you describe is interesting outside of kernel too. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [Ksummit-discuss] Including images on Sphinx documents
On Thu, 17 Nov 2016, Linus Torvalds <torva...@linux-foundation.org> wrote:
> We have makefiles, but more importantly, few enough people actually
> *generate* the documentation, that I think if it's an option to just
> fix sphinx, we should do that instead. If it means that you have to
> have some development version of sphinx, so be it. Most people read
> the documentation either directly in the unprocessed text-files
> ("source code") or on the web (by searching for pre-formatted docs)
> that I really don't think we need to worry too much about the
> toolchain.
My secret plan was to make building documentation easy, and then trick
more people into actually doing that on a regular basis, to ensure we
keep the build working and the output sensible in a variety of
environments. Sure we have a bunch of people doing this, and we have
0day doing this, but I'd hate it if it became laborous and fiddly to set
up the toolchain to generate documentation.
So I'm not necessarily disagreeing with anything you say, but I think
there's value in having a low bar for entry (from the toolchain POV) for
people interested in working with documentation, whether they're
seasoned kernel developers or newcomers purely interested in
documentation.
BR,
Jani.
--
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [Ksummit-discuss] Including images on Sphinx documents
On Thu, 17 Nov 2016, Arnd Bergmann <a...@arndb.de> wrote: > On Wednesday, November 16, 2016 6:26:33 PM CET Mauro Carvalho Chehab wrote: >> Em Wed, 16 Nov 2016 17:03:47 +0100 >> Arnd Bergmann <a...@arndb.de> escreveu: >> >> > On Tuesday, November 8, 2016 8:50:36 AM CET Mauro Carvalho Chehab wrote: >> > > It basically calls ImageMagick "convert" tool for all png and >> > > pdf files currently at the documentation (they're all at media, >> > > ATM). >> > >> > It looks like we still need to find a way to address the .gif files >> > though, as they have the same problem as the .pdf files. >> >> Actually, my last patch series removed all *.pdf images and converted >> all .gif files under Documentation/media to PNG[1]. I also replaced some >> images by .svg, but the remaining ones are more complex. I'm even not >> sure if it makes sense to convert a few of them to vectorial graphics, >> like on this case: >> https://mchehab.fedorapeople.org/kernel_docs/media/_images/selection.png >> >> > >> > During the kernel summit, I looked around for any binary files in >> > the kernel source tree, and except for the penguin logo, they are >> > all in Documentation/media/uapi/v4l/, but they are not all pdf >> > files, but also .png and .pdf. >> >> From what I understood from Linus, his problem is to carry on a >> non-editable file at the Kernel tree. With that sense, a PNG file >> is OK, as it is editable. > > [adding Linus for clarification] > > I understood the concern as being about binary files that you cannot > modify with classic 'patch', which is a separate issue. Also reported at [1]. So kernel.org has patches that you can't apply with either classic patch or git apply. They could at least be in git binary format so you could apply them with *something*. Of course, not having binaries at all would be clean. BR, Jani. [1] http://lkml.kernel.org/r/02a78907-933d-3f61-572e-28154b16b...@redhat.com > >> I had, in the past, problems with binary contents on either Mercurial >> or git (before migrating to git, we used Mercurial for a while). >> So, before Kernel 4.8, those .pdf, .png (and .gif) images were uuencoded, >> in order to avoid troubles handling patches with them. >> >> Nowadays, I don't see any issue handling binary images via e-mail or via git. > > > >> Btw, with that regards, SVG images are a lot worse to handle, as a single >> line can easily have more than 998 characters, with makes some email >> servers to reject patches with them. So, at the version 3 of my patch >> series, I had to use inkscape to ungroup some images, and to rewrite their >> files, as otherwise, two patches were silently rejected by the VGER >> server. > > Ok, good to know. > >> [1] The reason to convert to PNG is that it means one less format to be >> concerned with. Also, it doesn't make much sense to use two different >> formats for bitmap images at the documentation. > > I just tried converting all the .gif and .png files to .pnm. This would > make the files patchable but also add around 25MB to the uncompressed > kernel source tree (118kb compressed, compared to 113kb for the .gif and > .png files). This is certainly worse than the uuencoded files you > had before > > Arnd > ___ > Ksummit-discuss mailing list > ksummit-disc...@lists.linuxfoundation.org > https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [Ksummit-discuss] Including images on Sphinx documents
On Thu, 10 Nov 2016, Jani Nikula <jani.nik...@linux.intel.com> wrote: > On Thu, 10 Nov 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: >> Could this POC persuade you, if so, I send a more elaborate RFC, >> what do you think about? > > Sorry, I do not wish to be part of this. That was uncalled for, apologies. Like I said, I don't think this is the right approach. Call it an unsubstantiated gut feel coming from experience. However, I do not have the time to properly dig into this either, and that frustrates me. I wish I could be more helpful, but I can't right now. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [Ksummit-discuss] Including images on Sphinx documents
On Thu, 10 Nov 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > Could this POC persuade you, if so, I send a more elaborate RFC, > what do you think about? Sorry, I do not wish to be part of this. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [Ksummit-discuss] Including images on Sphinx documents
On Wed, 09 Nov 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > Am 09.11.2016 um 12:16 schrieb Jani Nikula <jani.nik...@linux.intel.com>: >>> So I vote for : >>> >>>> 1) copy (or symlink) all rst files to Documentation/output (or to the >>>> build dir specified via O= directive) and generate the *.pdf there, >>>> and produce those converted images via Makefile.; >> >> We're supposed to solve problems, not create new ones. > > ... new ones? ... Handle in-tree builds without copying. Make dependency analysis with source rst and "intermediate" rst work. Make sure your copying gets the timestamps right. Make Sphinx dependency analysis look at the right copies depending on in-tree vs. out-of-tree. Generally make sure it doesn't confuse Sphinx's own dependency analysis. The stuff I didn't think of. Sure, it's all supposed to be basic Makefile stuff, but don't make the mistake of thinking just one invocation of 'cp' will solve all the problems. It all adds to the complexity we were trying to avoid when dumping DocBook. It adds to the complexity of debugging stuff. (And hey, there's still the one rebuilding-stuff-for-no-reason issue open.) If you want to keep the documentation build sane, try to avoid the Makefile preprocessing. And same old story, if you fix this for real, even if as a Sphinx extension, *other* people than kernel developers will be interested, and *we* don't have to do so much ourselves. BR, Jani. > >>> IMO placing 'sourcedir' to O= is more sane since this marries the >>> Linux Makefile concept (relative to $PWD) with the sphinx concept >>> (in or below 'sourcedir'). > > -- Markus -- -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [Ksummit-discuss] Including images on Sphinx documents
On Wed, 09 Nov 2016, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: > Em Wed, 09 Nov 2016 13:16:55 +0200 > Jani Nikula <jani.nik...@linux.intel.com> escreveu: > >> >> 1) copy (or symlink) all rst files to Documentation/output (or to the >> >> build dir specified via O= directive) and generate the *.pdf there, >> >> and produce those converted images via Makefile.; >> >> We're supposed to solve problems, not create new ones. > > So, what's your proposal? Second message in the thread, http://lkml.kernel.org/r/87wpgf8ssc@intel.com > > Thanks, > Mauro > ___ > Ksummit-discuss mailing list > ksummit-disc...@lists.linuxfoundation.org > https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [Ksummit-discuss] Including images on Sphinx documents
On Wed, 09 Nov 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > Am 07.11.2016 um 18:01 schrieb Josh Triplett <j...@joshtriplett.org>: > >> On Mon, Nov 07, 2016 at 07:55:24AM -0200, Mauro Carvalho Chehab wrote: >>> 2) add an Sphinx extension that would internally call ImageMagick and/or >>> inkscape to convert the bitmap; >> >> This seems sensible; Sphinx should directly handle the source format we >> want to use for images/diagrams. >> >>> 3) if possible, add an extension to trick Sphinx for it to consider the >>> output dir as a source dir too. >> >> Or to provide an additional source path and point that at the output >> directory. > > The sphinx-build command excepts only one 'sourcedir' argument. All > reST files in this folder (and below) are parsed. > > Most (all?) directives which include content like images or literalinclude > except only relative pathnames. Where *relative* means, relative to the > reST file where the directive is used. For security reasons relative > pathnames outside 'sourcepath' are not excepted. > > So I vote for : > >> 1) copy (or symlink) all rst files to Documentation/output (or to the >> build dir specified via O= directive) and generate the *.pdf there, >> and produce those converted images via Makefile.; We're supposed to solve problems, not create new ones. > Placing reST files together with the *autogenerated* (intermediate) > content from > > * image conversions, > * reST content build from MAINTAINERS, > * reST content build for ABI > * etc. > > has the nice side effect, that we can get rid of all theses BUILDDIR > quirks in the Makefile.sphinx > > Additional, we can write Makefile targets to build the above listed > intermediate content relative to the $PWD, which is what Linux's > Makefiles usual do (instead of quirking with a BUILDDIR). > > E.g. with, we can also get rid of the 'kernel-include' directive > and replace it, with Sphinx's common 'literaliclude' and we do not > need any extensions to include intermediate PDFs or whatever > intermediate content we might want to generate. Well, kernel-include is a hack to make parse-headers.pl work, which is also a hack that IMHO shouldn't exist... > IMO placing 'sourcedir' to O= is more sane since this marries the > Linux Makefile concept (relative to $PWD) with the sphinx concept > (in or below 'sourcedir'). > > > -- Markus -- > > > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majord...@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Including images on Sphinx documents
On Mon, 07 Nov 2016, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: > Hi Jon, > > I'm trying to sort out the next steps to do after KS, with regards to > images included on RST files. > > The issue is that Sphinx image support highly depends on the output > format. Also, despite TexLive support for svg and png images[1], Sphinx > doesn't produce the right LaTeX commands to use svg[2]. On my tests > with PNG on my notebook, it also didn't seem to do the right thing for > PNG either. So, it seems that the only safe way to support images is > to convert all of them to PDF for latex/pdf build. > > [1] On Fedora, via texlive-dvipng and texlive-svg > [2] https://github.com/sphinx-doc/sphinx/issues/1907 > > As far as I understand from KS, two decisions was taken: > > - We're not adding a sphinx extension to run generic commands; > - The PDF images should be build in runtime from their source files > (either svg or bitmap), and not ship anymore the corresponding > PDF files generated from its source. > > As you know, we use several images at the media documentation: > https://www.kernel.org/doc/html/latest/_images/ > > Those images are tightly coupled with the explanation texts. So, > maintaining them away from the documentation is not an option. > > I was originally thinking that adding a graphviz extension would solve the > issue, but, in fact, most of the images aren't diagrams. Instead, there are > several ones with images showing the result of passing certain parameters to > the ioctls, explaining things like scale and cropping and how bytes are > packed on some image formats. > > Linus proposed to call some image conversion tool like ImageMagick or > inkscape to convert them to PDF when building the pdfdocs or latexdocs > target at Makefile, but there's an issue with that: Sphinx doesn't read > files from Documentation/output, and writing them directly at the > source dir would be against what it is expected when the "O=" argument > is passed to make. > > So, we have a few alternatives: > > 1) copy (or symlink) all rst files to Documentation/output (or to the >build dir specified via O= directive) and generate the *.pdf there, >and produce those converted images via Makefile.; > > 2) add an Sphinx extension that would internally call ImageMagick and/or >inkscape to convert the bitmap; > > 3) if possible, add an extension to trick Sphinx for it to consider the >output dir as a source dir too. Looking at the available extensions, and the images to be displayed, seems to me making svg work, somehow, is the right approach. (As opposed to trying to represent the images in graphviz or whatnot.) IIUC texlive supports displaying svg directly, but the problem is that Sphinx produces bad latex for that. Can we make it work by manually writing the latex? If yes, we wouldn't need to use an external tool to convert the svg to something else, but rather fix the latex. Thus: 4a) See if this works: .. only:: html .. image:: foo.svg .. raw:: latex 4b) Add a directive extension to make the above happen automatically. Of course, the correct fix is to have this fixed in upstream Sphinx, but as a workaround an extension doing the above seems plausible, and not too much effort - provided that we can make the raw latex work. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 1/3] doc-rst: generic way to build PDF of sub-folders
On Wed, 02 Nov 2016, Markus Heiser <markus.hei...@darmarit.de> wrote:
> Am 02.11.2016 um 12:43 schrieb Jani Nikula <jani.nik...@intel.com>:
>
>> On Wed, 24 Aug 2016, Markus Heiser <markus.hei...@darmarit.de> wrote:
>>> From: Markus Heiser <markus.hei...@darmarit.de>
>>>
>>> This extends the method to build only sub-folders to the targets
>>> "latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is
>>> required, where the latex_documents of the sub-folder are
>>> defined. E.g. to build only gpu's PDF add the following to the
>>> Documentation/gpu/conf.py::
>>>
>>> +latex_documents = [
>>> +("index", "gpu.tex", "Linux GPU Driver Developer's Guide",
>>> + "The kernel development community", "manual"),
>>> +]
>>>
>>> and run:
>>>
>>> make SPHINXDIRS=gpu pdfdocs
>>
>> Did you ever try this with more than one subfolder?
>
> Seems not, there is a ";" missed in the 'foreach' loop, see patch
> below.
>
> To avoid conflicts, can you apply the ";" on your
> "Makefile.sphinx improvements" series? / Thanks
Thanks, done.
http://lkml.kernel.org/r/1478097913-12561-1-git-send-email-jani.nik...@intel.com
>
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index 92deea3..b7fbd12 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -76,7 +76,7 @@ endif # HAVE_PDFLATEX
>
> pdfdocs: latexdocs
> ifneq ($(HAVE_PDFLATEX),0)
> - $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex
> LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex)
> + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex
> LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex;)
> endif # HAVE_PDFLATEX
>
> epubdocs:
>
>
> --Markus --
>
--
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 1/3] doc-rst: generic way to build PDF of sub-folders
On Wed, 24 Aug 2016, Markus Heiser <markus.hei...@darmarit.de> wrote:
> From: Markus Heiser <markus.hei...@darmarit.de>
>
> This extends the method to build only sub-folders to the targets
> "latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is
> required, where the latex_documents of the sub-folder are
> defined. E.g. to build only gpu's PDF add the following to the
> Documentation/gpu/conf.py::
>
> +latex_documents = [
> +("index", "gpu.tex", "Linux GPU Driver Developer's Guide",
> + "The kernel development community", "manual"),
> +]
>
> and run:
>
> make SPHINXDIRS=gpu pdfdocs
Did you ever try this with more than one subfolder?
BR,
Jani.
>
> Signed-off-by: Markus Heiser <markus.hei...@darmarit.de>
> ---
> Documentation/Makefile.sphinx | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index 894cfaa..92deea3 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -71,12 +71,12 @@ ifeq ($(HAVE_PDFLATEX),0)
> $(warning The 'xelatex' command was not found. Make sure you have it
> installed and in PATH to produce PDF output.)
> @echo " SKIPSphinx $@ target."
> else # HAVE_PDFLATEX
> - @$(call loop_cmd,sphinx,latex,.,latex,.)
> + @$(foreach var,$(SPHINXDIRS),$(call
> loop_cmd,sphinx,latex,$(var),latex,$(var)))
> endif # HAVE_PDFLATEX
>
> pdfdocs: latexdocs
> ifneq ($(HAVE_PDFLATEX),0)
> - $(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C
> $(BUILDDIR)/latex
> + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex
> LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex)
> endif # HAVE_PDFLATEX
>
> epubdocs:
--
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Documentation/media/uapi/cec/ sporadically unnecessarily rebuilding
I think I saw some of this in the past [1], but then couldn't reproduce
it after all. Now I'm seeing it again. Sporadically
Documentation/media/uapi/cec/ gets rebuilt on successive runs of make
htmldocs, even when nothing has changed.
Output of 'make SPHINXOPTS="-v -v" htmldocs' attached for both cases.
Using Sphinx (sphinx-build) 1.4.6
BR,
Jani.
[1] id:8760rbp8zh@intel.com
--
Jani Nikula, Intel Open Source Technology Center
SPHINX htmldocs --> file:///home/jani/src/linux/Documentation/output;
make[2]: Nothing to be done for 'all'.
Running Sphinx v1.4.6
[app] setting up extension: 'kernel-doc'
[app] adding config value: ('kerneldoc_bin', None, 'env')
[app] adding config value: ('kerneldoc_srctree', None, 'env')
[app] adding config value: ('kerneldoc_verbosity', 1, 'env')
[app] adding directive: ('kernel-doc', ,
None, None, {})
[app] setting up extension: 'rstFlatTable'
[app] adding directive: ('flat-table', , None,
None, {})
[app] setting up extension: 'kernel_include'
[app] adding directive: ('kernel-include', , None, None, {})
[app] setting up extension: 'cdomain'
[app] overriding domain:
[app] setting up extension: 'sphinx.ext.imgmath'
[app] adding config value: ('math_number_all', False, 'html')
[app] adding node: (, {'latex': (, None), 'man': (, None), 'text': (,
None), 'override': True, 'html': (,
None), 'texinfo': (, None)})
[app] adding node: (, {'latex':
(, None), 'man': (, ), 'text': (,
None), 'html': (, None),
'texinfo': (, )})
[app] adding node: (, {'latex': (, None), 'man': (, None), 'text': (, None), 'html': (,
), 'texinfo': (, None)})
[app] adding role: ('math', )
[app] adding role: ('eq', )
[app] adding directive: ('math', ,
None, None, {})
[app] connecting event 'doctree-resolved': [id=0]
[app] adding config value: ('imgmath_image_format', 'png', 'html')
[app] adding config value: ('imgmath_dvipng', 'dvipng', 'html')
[app] adding config value: ('imgmath_dvisvgm', 'dvisvgm', 'html')
[app] adding config value: ('imgmath_latex', 'latex', 'html')
[app] adding config value: ('imgmath_use_preview', False, 'html')
[app] adding config value: ('imgmath_dvipng_args', ['-gamma', '1.5', '-D',
'110', '-bg', 'Transparent'], 'html')
[app] adding config value: ('imgmath_dvisvgm_args', ['--no-fonts'], 'html')
[app] adding config value: ('imgmath_latex_args', [], 'html')
[app] adding config value: ('imgmath_latex_preamble', '', 'html')
[app] adding config value: ('imgmath_add_tooltips', True, 'html')
[app] adding config value: ('imgmath_font_size', 12, 'html')
[app] connecting event 'build-finished': [id=1]
[app] setting up extension: 'alabaster'
[app] connecting event 'html-page-context': [id=2]
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... 12 found
pickling environment... done
checking consistency... done
docnames to write: media/uapi/cec/cec-func-close,
media/uapi/cec/cec-func-ioctl, media/uapi/cec/cec-func-open,
media/uapi/cec/cec-func-poll, media/uapi/cec/cec-funcs,
media/uapi/cec/cec-header, media/uapi/cec/cec-ioc-adap-g-caps,
media/uapi/cec/cec-ioc-adap-g-log-addrs,
media/uapi/cec/cec-ioc-adap-g-phys-addr, media/uapi/cec/cec-ioc-dqevent,
media/uapi/cec/cec-ioc-g-mode, media/uapi/cec/cec-ioc-receive
preparing documents... WARNING: search index couldn't be loaded, but not all
documents will be built: the index will be incomplete.
done
writing output... [ 7%] index
writing output... [ 14%] media/uapi/cec/cec-api
writing output... [ 21%] media/uapi/cec/cec-func-close
writing output... [ 28%] media/uapi/cec/cec-func-ioctl
writing output... [ 35%] media/uapi/cec/cec-func-open
writing output... [ 42%] media/uapi/cec/cec-func-poll
writing output... [ 50%] media/uapi/cec/cec-funcs
writing output... [ 57%] media/uapi/cec/cec-header
writing output... [ 64%] media/uapi/cec/cec-ioc-adap-g-caps
writing output... [ 71%] media/uapi/cec/cec-ioc-adap-g-log-addrs
writing output... [ 78%] media/uapi/cec/cec-ioc-adap-g-phys-addr
writing output... [ 85%] media/uapi/cec/cec-ioc-dqevent
writing output... [ 92%] media/uapi/cec/cec-ioc-g-mode
writing output... [100%] media/uapi/cec/cec-ioc-receive
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 1 warning.
HTMLDocumentation/DocBook/index.html
SPHINX htmldocs --> file:///home/jani/src/linux/Documentation/output;
make[2]: Nothing to be done for 'all'.
Running Sphinx v1.4.6
[app] setting up extension: 'kernel-doc'
[app] adding config value: ('kerneldoc_bin', None, 'env')
[app] adding config value: ('kerneldoc_srctree', None, 'env')
[app] adding config value: ('kerneldoc_verbosity', 1, 'env')
[app] adding directive: ('kernel-doc', ,
None, None, {
Re: [PATCH 1/4] doc-rst: reST-directive kernel-cmd / include contentent from scripts
=== = > +``K:`` ``of_get_profile``matches patches or files > + that contain > + ``of_get_profile`` > +``K:`` ``\b(printk|pr_(info|err))\b``matches patches or > + files that contain one > + or more of the words > + ``printk``, ``pr_info`` > + or ``pr_err`` > +=== = > + > +One regex pattern per line. Multiple ``K:`` lines acceptable. > + > +.. note:: > + > + For the hard of thinking, this list is meant to remain in alphabetical > + order. If you could add yourselves to it in alphabetical order that would > be > + so much easier [Ed] > > Maintainers List (try to look for most precise areas first) > +--- > > --- > > + > 3C59X NETWORK DRIVER > M: Steffen Klassert <klass...@mathematik.tu-chemnitz.de> > L: net...@vger.kernel.org -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/4] reST-directive kernel-cmd / include contentent from scripts
On Tue, 11 Oct 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > Anyway, these are only my 2cent. I'am interested in what Jon says > in general about using (Perl) scripts to generate reST content. I think I've said all that I have to say on the subject. Up to Jon. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/4] reST-directive kernel-cmd / include contentent from scripts
On Tue, 11 Oct 2016, Mauro Carvalho Chehab <mche...@infradead.org> wrote: > Em Tue, 11 Oct 2016 09:26:48 +0200 > Markus Heiser <markus.hei...@darmarit.de> escreveu: > >> Am 07.10.2016 um 07:56 schrieb Jani Nikula <jani.nik...@intel.com>: >> >> > On Thu, 06 Oct 2016, Mauro Carvalho Chehab <mche...@infradead.org> wrote: >> >> Em Thu, 06 Oct 2016 17:21:36 +0300 >> >> Jani Nikula <jani.nik...@intel.com> escreveu: >> >>> We've seen what happens when we make it easy to add random scripts to >> >>> build documentation. We've worked hard to get rid of that. In my books, >> >>> one of the bigger points in favor of Sphinx over AsciiDoc(tor) was >> >>> getting rid of all the hacks required in the build. Things that broke in >> >>> subtle ways. >> >> >> >> I really can't see what scripts it get rids. >> > >> > Really? You don't see why the DocBook build was so fragile and difficult >> > to maintain? That scares me a bit, because then you will not have >> > learned why we should at all costs avoid adding random scripts to >> > produce documentation. >> >> For me, disassembling the DocBok build was hard and bothersome, I don't >> want this back. >> >> IMO: old hats are productive with perl and they won't adapt another >> interpreter language (like python) for scripting. >> >> This series -- the kernel-cmd -- directive avoid that they build >> fragile and difficult to maintain Makefile constructs, calling their >> perl scripts. >> >> Am 06.10.2016 um 16:21 schrieb Jani Nikula <jani.nik...@intel.com>: >> >> > This is connected to the above: keeping documentation buildable with >> > sphinx-build directly will force you to avoid the Makefile hacks. >> >> >> Thats why I think, that the kernel-cmd directive is a more *straight- >> forward* solution, helps to **avoid** complexity while not everyone >> has to script in python ... >> >> > Case in point, parse-headers.pl was added for a specific need of media >> > documentation, and for the life of me I can't figure out by reading the >> > script what good, if any, it would be for gpu documentation. I call >> > *that* unmaintainable. >> >> >> If one adds a script like parse-headers.pl to the Documentation/sphinx >> folder, he/she also has to add a documentation to the >> kernel-documentation.rst >> >> If the kernel-cmd directive gets acked, I will add a description to >> kernel-documentation.rst and I request Mauro to document the parse-headers.pl >> also. > > I can write documentation for parse-headers.pl, either as a --help/--man > option or at some ReST file (or both). I'll add this to my mental TODO > list. Thanks, documentation will help everyone else evaluate whether parse-headers.pl is only useful for some corner case in media docs, or perhaps more generally useful. Currently, it's hard to tell. Anyway, documentation does not change my view on adding such scripts. As I've said, I think they will make the documentation build more difficult to maintain. They are likely to become special purpose hacks for corner cases across documentation. The rest of what you say is unrelated to the patches at hand. BR, Jani. > > - > > With regards to Sphinx x DocBook, in terms of functionality, Sphinx > is an improvement, as we can now use the same markup for everything, > and cross-reference all documents. Unfortunately, it has less > functionality than DocBook, and requires more magic to work. > > However, there are costs to pay on using a Python script like Sphinx. > I won't mention again the issues with Python itself and its unstable > API, but, instead, focus on Sphinx script itself. > > First of all, installing packages for Sphinx script to work is a lot > more complex, specially for the PDF output, as the LaTeX requirements are > very distribution specific, as some distributions package each LaTeX > extension as optional packages, and the required extensions used by > the Sphinx script are not documented. > > Also, the Sphinx script and its build logic is a lot more fragile than > the Makefile/xmlto that we use on DocBook, and this has nothing to do > with adding extra perl/python scripts. > > While it is clean for html output, it is very dirty when producing > a PDF output. > > It starts by generating its own Makefile for PDF builds, at the output > directory, with we have little control on it. > > Also, it seems that almost all books will need hacks to produce proper PDF, > as neither ReST or
Re: [PATCH 0/4] reST-directive kernel-cmd / include contentent from scripts
On Thu, 06 Oct 2016, Mauro Carvalho Chehab <mche...@infradead.org> wrote: > Em Thu, 06 Oct 2016 17:21:36 +0300 > Jani Nikula <jani.nik...@intel.com> escreveu: >> We've seen what happens when we make it easy to add random scripts to >> build documentation. We've worked hard to get rid of that. In my books, >> one of the bigger points in favor of Sphinx over AsciiDoc(tor) was >> getting rid of all the hacks required in the build. Things that broke in >> subtle ways. > > I really can't see what scripts it get rids. Really? You don't see why the DocBook build was so fragile and difficult to maintain? That scares me a bit, because then you will not have learned why we should at all costs avoid adding random scripts to produce documentation. The DocBook build was designed by Rube Goldberg, and this video accurately illustrates how it works: https://www.youtube.com/watch?v=qybUFnY7Y8w I don't want the Sphinx build to end up like that. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/4] reST-directive kernel-cmd / include contentent from scripts
On Thu, 06 Oct 2016, Mauro Carvalho Chehab <mche...@infradead.org> wrote: > Em Thu, 06 Oct 2016 11:42:14 +0300 > Jani Nikula <jani.nik...@intel.com> escreveu: > Just curious here: what use case do you see by building the Kernel > documentation without the Kernel tree? Not without the kernel tree, but without the kernel build system. If sphinx-build works directly, https://readthedocs.org/ just works when you point it at a kernel git repo and the conf.py inside it. It would be important to get Sphinx working over at https://www.kernel.org/doc/htmldocs/ (which still looks kind of sad) but in the mean time we could have had that at https://readthedocs.org/. If it weren't for parse-headers.pl and the build hacks around it. At least there's one at https://01.org/linuxgraphics/gfx-docs/drm/ now. >> However, I would have much preferred the approach I proposed months ago, >> having the extension itself do specifically what parse-headers.pl does >> now. While it may seem generic on the surface, I don't think it's a >> clean or a secure approach to allow running of arbitrary scripts from >> PATH while building documentation. It's certainly not an approach that >> should be encouraged. > > Sorry, but I disagree. The security threat of having a random command > doing something wrong is the same as we already have with the Kernel > Makefiles, as they can also run a random command. All it is needed > is to add this to a Makefile: My intention was to emphasize the importance of the clarity of the documentation build, and not get hung up on the security aspect. This is connected to the above: keeping documentation buildable with sphinx-build directly will force you to avoid the Makefile hacks. > IMO, a generic solution is a way better, as it sounds easier to > maintain. We've seen what happens when we make it easy to add random scripts to build documentation. We've worked hard to get rid of that. In my books, one of the bigger points in favor of Sphinx over AsciiDoc(tor) was getting rid of all the hacks required in the build. Things that broke in subtle ways. I think having people write Sphinx extensions for the special needs have a better chance of solving the problems in more generic ways than writing scripts for each specific need. Ideally, we can push those extensions to upstream Sphinx, but at least make them easily usable across the kernel documentation. Case in point, parse-headers.pl was added for a specific need of media documentation, and for the life of me I can't figure out by reading the script what good, if any, it would be for gpu documentation. I call *that* unmaintainable. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/4] reST-directive kernel-cmd / include contentent from scripts
On Thu, 06 Oct 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > with this series a reST-directive kernel-cmd is introduced. The kernel-cmd > directive includes contend from the stdout of a command-line (@mchehab asked > for). I like the fact that this removes Documentation/media/Makefile, and cleans up the Sphinx build rule in Documentation/Makefile.sphinx. Does this also make the documentation buildable with sphinx-build directly, without the kernel build system? If so, great. However, I would have much preferred the approach I proposed months ago, having the extension itself do specifically what parse-headers.pl does now. While it may seem generic on the surface, I don't think it's a clean or a secure approach to allow running of arbitrary scripts from PATH while building documentation. It's certainly not an approach that should be encouraged. In part, the reason the DocBook build became so unwieldy was the proliferation of arbitrary scripts and tools required to make it happen. I think it would be really sad to let this happen to the Sphinx build. I am *already* sad about how parse-headers.pl was bolted on to the build. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
kernel-doc-rst-lint (was: Re: [PATCH 00/15] improve function-level documentation)
On Wed, 05 Oct 2016, Daniel Vetter <dan...@ffwll.ch> wrote:
> Jani Nikula has a patch with a scrip to make the one kernel-doc parser
> into a lint/checker pass over the entire kernel. I think that'd would
> be more robust instead of trying to approximate the real kerneldoc
> parser. Otoh that parser is a horror show of a perl/regex driven state
> machine ;-)
>
> Jani, can you pls digg out these patches? Can't find them right now ...
Expanding the massive Cc: with linux-doc list...
Here goes. It's a quick hack from months ago, but still seems to
somewhat work. At least for the kernel-doc parts. The reStructuredText
lint part isn't all that great, and doesn't have mapping to line numbers
like the Sphinx kernel-doc extension does. Anyway I'm happy how this
integrates with kernel build CHECK and C=1/C=2.
I guess Julia's goal is to automate the *fixing* of some of the error
classes from kernel-doc. Not sure how well this could be made to
integrate with any of that.
BR,
Jani.
>From 1244efa0f63a7b13795e8c37f81733a3c8bfc56a Mon Sep 17 00:00:00 2001
From: Jani Nikula <jani.nik...@intel.com>
Date: Tue, 31 May 2016 18:11:33 +0300
Subject: [PATCH] kernel-doc-rst-lint: add tool to check kernel-doc and rst
correctness
Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo
Cc: Jani Nikula <jani.nik...@intel.com>
Simple kernel-doc and reStructuredText lint tool that can be used
independently and as a kernel build CHECK tool to validate kernel-doc
comments.
Independent usage:
$ kernel-doc-rst-lint FILE
Kernel CHECK usage:
$ make CHECK=scripts/kernel-doc-rst-lint C=1# (or C=2)
Depends on docutils and the rst-lint package
https://pypi.python.org/pypi/restructuredtext_lint
Signed-off-by: Jani Nikula <jani.nik...@intel.com>
---
scripts/kernel-doc-rst-lint | 106
1 file changed, 106 insertions(+)
create mode 100755 scripts/kernel-doc-rst-lint
diff --git a/scripts/kernel-doc-rst-lint b/scripts/kernel-doc-rst-lint
new file mode 100755
index ..7e0157679f83
--- /dev/null
+++ b/scripts/kernel-doc-rst-lint
@@ -0,0 +1,106 @@
+#!/usr/bin/env python
+# coding=utf-8
+#
+# Copyright © 2016 Intel Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice (including the next
+# paragraph) shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+#
+# Authors:
+#Jani Nikula <jani.nik...@intel.com>
+#
+# Simple kernel-doc and reStructuredText lint tool that can be used
+# independently and as a kernel build CHECK tool to validate kernel-doc
+# comments.
+#
+# Independent usage:
+# $ kernel-doc-rst-lint FILE
+#
+# Kernel CHECK usage:
+# $ make CHECK=scripts/kernel-doc-rst-lint C=1 # (or C=2)
+#
+# Depends on docutils and the rst-lint package
+# https://pypi.python.org/pypi/restructuredtext_lint
+#
+
+import os
+import subprocess
+import sys
+
+from docutils.parsers.rst import directives
+from docutils.parsers.rst import Directive
+from docutils.parsers.rst import roles
+from docutils import nodes, statemachine
+import restructuredtext_lint
+
+class DummyDirective(Directive):
+required_argument = 1
+optional_arguments = 0
+option_spec = { }
+has_content = True
+
+def run(self):
+return []
+
+# Fake the Sphinx C Domain directives and roles
+directives.register_directive('c:function', DummyDirective)
+directives.register_directive('c:type', DummyDirective)
+roles.register_generic_role('c:func', nodes.emphasis)
+roles.register_generic_role('c:type', nodes.emphasis)
+
+# We accept but ignore parameters to be compatible with how the kernel build
+# invokes CHECK.
+if len(sys.argv) < 2:
+sys.stderr.write('usage: kernel-doc-rst-lint [IGNORED OPTIONS] FILE\n');
+sys.exit(1)
+
+infile = sys.argv[len(sys.argv) - 1]
+cmd = ['scripts/kernel-doc', '-rst', infile]
+
+try:
+p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
universal_newlines=True)
Re: [PATCH 1/3] doc-rst:c-domain: fix sphinx version incompatibility
On Tue, 06 Sep 2016, Jonathan Corbet <cor...@lwn.net> wrote:
> On Wed, 31 Aug 2016 17:29:30 +0200
> Markus Heiser <markus.hei...@darmarit.de> wrote:
>
>> +if major >= 1 and minor < 4:
>> +# indexnode's tuple changed in 1.4
>> +#
>> https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c
>> +self.indexnode['entries'].append(
>> +('single', indextext, targetname, ''))
>> +else:
>> +self.indexnode['entries'].append(
>> +('single', indextext, targetname, '', None))
>
> So this doesn't seem right. We'll get the four-entry tuple behavior with
> 1.3 and the five-entry behavior with 1.4...but what happens when 2.0
> comes out?
>
> Did you want maybe:
>
> if major == 1 and minor < 4:
>
> ?
>
> (That will fail on 0.x, but we've already stated that we don't support
> below 1.2).
Is there a way to check the number of entries expected in the tuples
instead of trying to match the version?
BR,
Jani.
--
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] doc-rst:sphinx-extensions: add metadata parallel-safe
On Thu, 01 Sep 2016, Jonathan Corbet <cor...@lwn.net> wrote: > On Wed, 24 Aug 2016 15:35:24 +0200 > Markus Heiser <markus.hei...@darmarit.de> wrote: > >> With metadata "parallel_read_safe = True" a extension is marked as >> save for "parallel reading of source". This is needed if you want >> build in parallel with N processes. E.g.: >> >> make SPHINXOPTS=-j4 htmldocs > > A definite improvement; applied to the docs tree, thanks. The Sphinx docs say -jN "should be considered experimental" [1]. Any idea *how* experimental that is, really? Could we add some -j by default? BR, Jani. [1] http://www.sphinx-doc.org/en/stable/invocation.html#invocation-of-sphinx-build -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
On Wed, 31 Aug 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > I haven't tested your suggestion, but since *void* is in the list > of stop-words: > > # These C types aren't described anywhere, so don't try to create > # a cross-reference to them > stopwords = set(( > 'const', 'void', 'char', 'wchar_t', 'int', 'short', > 'long', 'float', 'double', 'unsigned', 'signed', 'FILE', > 'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t', > 'struct', '_Bool', > )) > > I think it will work in the matter you think. > > However I like to prefer to fix it in the C-domain, using > Mauro's suggestion on argument parsing. IMHO it is not > the best solution to add a void type to the reST signature > of a macro. This will result in a unusual output and does > not fix what is wrong in Sphinx's c-domain (there is also > a drawback in the index, where a function-type macro is > referred as function, not as macro). >From an API user's perspective, functions and function-like macros should work interchangeably. Personally, I don't think there needs to be a difference in the index. This seems to be the approach taken in Sphinx, but it just doesn't work well for automatic documentation generation because we can't deduce the parameter types from the macro definition. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3] docs-rst: ignore arguments on macro definitions
On Mon, 29 Aug 2016, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: > Em Mon, 29 Aug 2016 16:12:39 +0200 > Markus Heiser <markus.hei...@darmarit.de> escreveu: > >> Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab >> <mche...@s-opensource.com>: >> >> > A macro definition is mapped via .. c:function:: at the >> > ReST markup when using the following kernel-doc tag: >> > >> >/** >> > * DMX_FE_ENTRY - Casts elements in the list of registered >> > * front-ends from the generic type struct list_head >> > * to the type * struct dmx_frontend >> > * >> > * @list: list of struct dmx_frontend >> > */ >> > #define DMX_FE_ENTRY(list) \ >> >list_entry(list, struct dmx_frontend, connectivity_list) >> > >> > However, unlike a function description, the arguments of a macro >> > doesn't contain the data type. >> > >> > This causes warnings when enabling Sphinx on nitkpick mode, >> > like this one: >> >./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target >> > not found: list >> >> I think this is a drawback of sphinx's C-domain, using function >> definition for macros also. From the function documentation >> >> """This is also used to describe function-like preprocessor >> macros. The names of the arguments should be given so >> they may be used in the description.""" >> >> I think about to fix the nitpick message for macros (aka function >> directive) in the C-domain extension (we already have). > > Yeah, that could produce a better output, if it is doable. > >> >> But for this, I need a rule to distinguish between macros >> and functions ... is the uppercase of the macro name a good >> rule to suppress the nitpick message? > > No. There are lots of macros in lowercase. never did any stats about > that, but I guess that we actually have a way more such macros in > lowercase. > >> Any other suggestions? > > I guess the best thing is to check if the type is empty, just like > on this patch. Macros are always: > foo(arg1, arg2, arg3, ...) > > while functions always have some type (with could be as complex as > a function pointer). So, if all arguments match this rejex: > \s*\S+\s* > Then, it is a macro. Otherwise, it is a function. > > There's no way for the C domain to distinguish between a macro or > a function when the number of arguments is zero, but, on such case, > it doesn't really matter. What does Sphinx say if you add "void" as the type? Or a fake "macroparam" type? If those hacks don't help, Mauro's suggestion seems sane. BR, Jani. > > Thanks, > Mauro > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majord...@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: RFC? [PATCH] docs-rst: kernel-doc: better output struct members
On Mon, 22 Aug 2016, Markus Heiser <markus.hei...@darmarit.de> wrote:
> Am 22.08.2016 um 13:16 schrieb Jani Nikula <jani.nik...@intel.com>:
>
>> On Mon, 22 Aug 2016, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
>>> Markus,
>>>
>>> Em Mon, 22 Aug 2016 10:56:01 +0200
>>> Markus Heiser <markus.hei...@darmarit.de> escreveu:
>>>
>>>> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab
>>>> <mche...@s-opensource.com>:
>>>>
>>>>> Right now, for a struct, kernel-doc produces the following output:
>>>>>
>>>>> .. c:type:: struct v4l2_prio_state
>>>>>
>>>>> stores the priority states
>>>>>
>>>>> **Definition**
>>>>>
>>>>> ::
>>>>>
>>>>> struct v4l2_prio_state {
>>>>> atomic_t prios[4];
>>>>> };
>>>>>
>>>>> **Members**
>>>>>
>>>>> ``atomic_t prios[4]``
>>>>> array with elements to store the array priorities
>>>>>
>>>>> Putting a member name in verbatim and adding a continuation line
>>>>> causes the LaTeX output to generate something like:
>>>>> item[atomic_t prios\[4\]] array with elements to store the array
>>>>> priorities
>>>>
>>>>
>>>> Right now, the description of C-struct members is a simple
>>>> rest-definition-list
>>>> (not in the c-domain). It might be better to use the c-domain for members:
>>>>
>>>> http://www.sphinx-doc.org/en/stable/domains.html#directive-c:member
>>>>
>>>> But this is not the only thing we have to consider. To make a valid
>>>> C-struct
>>>> description (with targets/references in the c-domain) we need a more
>>>> *structured* reST markup where the members are described in the
>>>> block-content
>>>> of the struct directive. E.g:
>>>>
>>>> ---
>>>> |.. c:type:: struct v4l2_subdev_ir_ops
>>>> |
>>>> | operations for IR subdevices
>>>> |
>>>> | .. c:member:: int (* rx_read) (struct v4l2_subdev *sd, u8 *buf,
>>>> size_t count,ssize_t *num)
>>>> |
>>>> ---
>>>>
>>>> By this small example, you see, that we have to discuss the whole markup
>>>> produced by the kernel-doc script (function arguments, unions etc.).
>>>> IMHO, since kernel-doc is widely used, this should be a RFC.
>>>
>>> I tried using c:member. It won't work on LaTeX output, as it will
>>> still put everything into a LaTeX item, with doesn't do line breaks.
>>
>> I've tried c:member before, and I'm not convinced it buys us anything
>> useful. I'm also not convinced we'd need more structured rst markup
>> within struct or function descriptions in addition to what we currently
>> have. Keep it simple.
>>
>> BR,
>> Jani.
>
> It buys, that we stay in the c-domain and we can refer to the members
> with the :c:member role. E.g :c:member:`v4l2_subdev_ir_ops.rx_read`.
Yes, it allows anchors to members, while detaching the member
descriptions from the struct descriptions. In the output, there is no
perceivable parent-child relationship between the struct and its
members. Arguably the resulting documentation is harder to follow with
c:member than without. I think it's sufficient to link to the struct
descriptions. It's not enough to say that theoretically using c:member
is the right thing; it needs to be better in practice too.
BR,
Jani.
>
> -- Markus --
>
>
>
--
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: RFC? [PATCH] docs-rst: kernel-doc: better output struct members
On Mon, 22 Aug 2016, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
> Markus,
>
> Em Mon, 22 Aug 2016 10:56:01 +0200
> Markus Heiser <markus.hei...@darmarit.de> escreveu:
>
>> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab
>> <mche...@s-opensource.com>:
>>
>> > Right now, for a struct, kernel-doc produces the following output:
>> >
>> >.. c:type:: struct v4l2_prio_state
>> >
>> > stores the priority states
>> >
>> >**Definition**
>> >
>> >::
>> >
>> > struct v4l2_prio_state {
>> >atomic_t prios[4];
>> > };
>> >
>> >**Members**
>> >
>> >``atomic_t prios[4]``
>> > array with elements to store the array priorities
>> >
>> > Putting a member name in verbatim and adding a continuation line
>> > causes the LaTeX output to generate something like:
>> >item[atomic_t prios\[4\]] array with elements to store the array
>> > priorities
>>
>>
>> Right now, the description of C-struct members is a simple
>> rest-definition-list
>> (not in the c-domain). It might be better to use the c-domain for members:
>>
>> http://www.sphinx-doc.org/en/stable/domains.html#directive-c:member
>>
>> But this is not the only thing we have to consider. To make a valid C-struct
>> description (with targets/references in the c-domain) we need a more
>> *structured* reST markup where the members are described in the block-content
>> of the struct directive. E.g:
>>
>> ---
>> |.. c:type:: struct v4l2_subdev_ir_ops
>> |
>> | operations for IR subdevices
>> |
>> | .. c:member:: int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t
>> count,ssize_t *num)
>> |
>> ---
>>
>> By this small example, you see, that we have to discuss the whole markup
>> produced by the kernel-doc script (function arguments, unions etc.).
>> IMHO, since kernel-doc is widely used, this should be a RFC.
>
> I tried using c:member. It won't work on LaTeX output, as it will
> still put everything into a LaTeX item, with doesn't do line breaks.
I've tried c:member before, and I'm not convinced it buys us anything
useful. I'm also not convinced we'd need more structured rst markup
within struct or function descriptions in addition to what we currently
have. Keep it simple.
BR,
Jani.
>
> Also, according to Sphinx manual at
> http://www.sphinx-doc.org/en/stable/domains.html
> The syntax is:
>
> .. c:member:: type name
>
> Describes a C struct member. Example signature:
>
> .. c:member:: PyObject* PyTypeObject.tp_bases
>
> So, it expects as arguments. If the manual is right, it
> would be expecting, instead, the weird syntax:
>
>.. c:member:: int (*) (struct v4l2_subdev *sd, u8 *buf, size_t
> count,ssize_t *num) rx_read
>
> With hurts my eyes.
>
> As I guess we don't want to maintain ourselves a LaTeX output Sphinx
> plugin forked from upstream, I guess that a more definitive solution
> would involve overriding the parser for c:member in a way that it would
> produce an output like the one in this path, while creating the proper
> c domain reference for the structure member inside the C domain.
>
> Regards,
> Mauro
--
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 1/7] doc-rst: generic way to build only sphinx sub-folders
On Fri, 19 Aug 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <cor...@lwn.net>: > * the pdf goes to the "latex" folder .. since this is WIP > and there are different solutions conceivable ... I left > it open for the first. Mea culpa. As I said, I intended my patches as RFC only. > > * in the index.html we miss some links to pdf-/man- etc files > > The last point needs some discussion. Hopefully, this discussion > starts right here. > > >> I'm not sure that we actually need the format-specific subfolders, but we >> should be consistent across all the formats and in the documentation and, >> as of this patch, we're not. > > IMHO a structure where only non-HTML formats are placed in subfolders > (described above) is the better choice. > > In the long run I like to get rid of all the intermediate formats > (latex, .doctrees) and build a clear output-folder (with all formats > in) which could be copied 1:1 to a static HTTP-server. When I added the Documentation/output subfolder, my main intention was to separate the source documents from everything that is generated, intermediate or final. I suggest you keep the generated files somewhere under output. This'll be handly also when ensuring O= works. I set up the format specific subfolders, because I thought people would want to keep them separated and independent. For me, all the formats were equal and at the same level in that regard. You're suggesting to make html the root of everything? BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 0/3] doc-rst: parseheaders directive
On Fri, 12 Aug 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > this series imlpements a new directive ".. parseheaders::" as a replacement > for > the media/Makefile, suggested by Jani [1]. Thanks for doing this work. I didn't do a thorough review, but at a high level I think it is what we want. > doc-rst: parseheaders directive (inital) I think this patch will break bisect, because it changes the perl script before its users are converted. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC 3/4] Documentation: move dma-buf documentation to rst
On Thu, 11 Aug 2016, Sumit Semwal <sumit.sem...@linaro.org> wrote: > diff --git a/Documentation/dma-buf/guide.rst b/Documentation/dma-buf/guide.rst > new file mode 100644 > index ..fd3534fdccb3 > --- /dev/null > +++ b/Documentation/dma-buf/guide.rst > @@ -0,0 +1,503 @@ > + > +.. _dma-buf-guide: > + > + > +DMA Buffer Sharing API Guide > + > + > +Sumit Semwal - sumit.sem...@linaro.org, sum...@kernel.org Please use the format :author: Sumit Semwal <sumit.sem...@linaro.org> --- While on this subject, please excuse me for hijacking the thread a bit. Personally, I believe it would be better to leave out authorship notes from documentation and source files in collaborative projects. Of course, it is only fair that people who deserve credit get the credit. Listing the authors in the file is often the natural thing to do, and superficially seems fair. However, when do you add more names to the list? When has someone contributed enough to warrant that? Is it fair that the original authors keep getting the credit for the contributions of others? After a while, perhaps there is next to nothing left of the original contributions, but the bar is really high for removing anyone from the authors. Listing the authors gives the impression this is *their* file, while everyone should feel welcome to contribute, and everyone who contributes should feel ownership. IMHO we would be better off using just the git history for the credits. BR, Jani. PS. I am no saint here, I've got a couple of authors lines myself. I promise not to add more. I certainly won't chastise anyone for adding theirs. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: parts of media docs sphinx re-building every time?
On Mon, 08 Aug 2016, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: > The goal of Documentation/sphinx/parse-headers.pl script is to generate > such parsed headers, with the cross-references modified by an exceptions > file at Documentation/media/*.h.rst.exceptions. Would you be so kind as to state in a few lines what you want to achieve? I can guess based on the current solution, but I'd like to hear it from you. Please leave out rants about tools and languages etc. so we can focus on the problem statement, and try to figure out the best overall solution. Thanks, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: parts of media docs sphinx re-building every time?
On Wed, 10 Aug 2016, Mauro Carvalho Chehab <mche...@infradead.org> wrote: > Em Mon, 08 Aug 2016 18:37:38 +0300 > Jani Nikula <jani.nik...@intel.com> escreveu: > >> Hi Mauro & co - >> >> I just noticed running 'make htmldocs' rebuilds parts of media docs >> every time on repeated runs. This shouldn't happen. Please investigate. > > I was unable to reproduce it here. Are you passing any special options > to the building system? Hmh, I can't reproduce this now either. I was able to hit this on another machine consistently, even with 'make cleandocs' in between. I'll check the environment on the other machine when I get my hands on it. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: parts of media docs sphinx re-building every time?
On Mon, 08 Aug 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > Hi Jani, > > Am 08.08.2016 um 17:37 schrieb Jani Nikula <jani.nik...@intel.com>: > >> >> Hi Mauro & co - >> >> I just noticed running 'make htmldocs' rebuilds parts of media docs >> every time on repeated runs. This shouldn't happen. Please investigate. >> >> I wonder if it's related to Documentation/media/Makefile... which I have >> to say I am not impressed by. I was really hoping we could build all the >> documentation by standalone sphinx-build invocation too, relying only on >> the conf.py so that e.g. Read the Docs can build the docs. Part of that >> motivation was to keep the build clean in makefiles, and handing the >> dependency tracking completely to Sphinx. >> >> I believe what's in Documentation/media/Makefile, >> Documentation/sphinx/parse-headers.pl, and >> Documentation/sphinx/kernel_include.py could be replaced by a Sphinx >> extension looking at the sources directly. > > Yes, parse-headers.pl, kernel_include.py and media/Makefile are needed > for one feature ... not very straight forward. > > If it makes sense to migrate the perl scripts functionality to a > Sphinx extension, may I can help ... depends on what Mauro thinks. > > BTW: parse-headers.pl is not the only perl script I like to migrate to py ;) If I understand the need of all of this right, I think the cleanest and fastest short term measure would be to make the kernel-include directive extension do the same thing as the kernel-doc directive does: call the perl script from the directive. This lets you get rid of Documentation/media/Makefile and you don't have to copy-paste all of Include.run method into kernel_include.py. You can also get rid of specifying environment variables in rst files and parsing them in the extension. We can get rid of the problematic intermediate rst files. This design has been proven with the kernel-doc extension and script already. It's much simpler. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: parts of media docs sphinx re-building every time?
On Mon, 08 Aug 2016, Jani Nikula <jani.nik...@intel.com> wrote: > I wonder if it's related to Documentation/media/Makefile... which I have > to say I am not impressed by. I was really hoping we could build all the > documentation by standalone sphinx-build invocation too, relying only on > the conf.py so that e.g. Read the Docs can build the docs. Part of that > motivation was to keep the build clean in makefiles, and handing the > dependency tracking completely to Sphinx. > > I believe what's in Documentation/media/Makefile, > Documentation/sphinx/parse-headers.pl, and > Documentation/sphinx/kernel_include.py could be replaced by a Sphinx > extension looking at the sources directly. (I presume kernel_include.py > is mostly a workaround to keep out-of-tree builds working?) Additionally, 'make pdfdocs' fails with e.g. /path/to/linux/Documentation/media/uapi/cec/cec-header.rst:9: SEVERE: Problems with "kernel-include" directive path: InputError: [Errno 2] No such file or directory: '/path/to/linux/Documentation/output/cec.h.rst'. /path/to/linux/Documentation/media/uapi/dvb/audio_h.rst:9: SEVERE: Problems with "kernel-include" directive path: InputError: [Errno 2] No such file or directory: '/path/to/linux/Documentation/output/audio.h.rst'. /path/to/linux/Documentation/media/uapi/dvb/ca_h.rst:9: SEVERE: Problems with "kernel-include" directive path: InputError: [Errno 2] No such file or directory: '/path/to/linux/Documentation/output/ca.h.rst'. /path/to/linux/Documentation/media/uapi/dvb/dmx_h.rst:9: SEVERE: Problems with "kernel-include" directive path: InputError: [Errno 2] No such file or directory: '/path/to/linux/Documentation/output/dmx.h.rst'. because the makefile hack is only done on htmldocs target. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] doc-rst: support *sphinx build themes*
On Fri, 05 Aug 2016, Markus Heiser <markus.hei...@darmarit.de> wrote:
> From: Markus Heiser <markus.hei...@darmarit.de>
>
> Load an additional configuration file into conf.py 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*.
>
> E.g. to create your own nit-picking *build theme*, create a file
> Documentation/conf_nitpick.py::
>
> nitpicky=True
> nitpick_ignore = [
> ("c:func", "clock_gettime"),
> ...
> ]
>
> and run make with SPHINX_CONF environment::
>
> make SPHINX_CONF=conf_nitpick.py htmldocs
I think I would try to accomplish this by using the -c option in
SPHINXOPTS, and loading the main config file from the "special case"
config file. I think it would be a more generic approach instead of a
specific framework of our own. *shrug*.
BR,
Jani.
>
> Signed-off-by: Markus Heiser <markus.hei...@darmarit.de>
> ---
> Documentation/conf.py | 9 +
> Documentation/sphinx/load_config.py | 25 +
> 2 files changed, 34 insertions(+)
> create mode 100644 Documentation/sphinx/load_config.py
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 96b7aa6..d502775 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -20,6 +20,8 @@ import os
> # 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
>
> # If your documentation needs a minimal Sphinx version, state it here.
> @@ -419,3 +421,10 @@ 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())
> diff --git a/Documentation/sphinx/load_config.py
> b/Documentation/sphinx/load_config.py
> new file mode 100644
> index 000..44bdd22
> --- /dev/null
> +++ b/Documentation/sphinx/load_config.py
> @@ -0,0 +1,25 @@
> +# -*- coding: utf-8; mode: python -*-
> +# pylint: disable=R0903, C0330, R0914, R0912, E0401
> +
> +import os
> +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.exists(config_file):
> +config_file = os.path.abspath(config_file)
> +config = namespace.copy()
> +config['__file__'] = config_file
> +execfile_(config_file, config)
> +del config['__file__']
> +namespace.update(config)
--
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] DocBook: use DOCBOOKS="" to ignore DocBooks instead of IGNORE_DOCBOOKS=1
Instead of a separate ignore flag, use the obvious DOCBOOKS="" to ignore all DocBook files. This is also in line with the Sphinx build being ignored if a non-empty DOCBOOKS make variable is specified on the make command line. This replaces the IGNORE_DOCBOOKS introduced in commit 547218864afb2745d9d137f005f3380ef96b26ab Author: Mauro Carvalho Chehab <mche...@s-opensource.com> Date: Sat Jul 9 13:12:45 2016 -0300 doc-rst: add an option to ignore DocBooks when generating docs and aligns with commit 6387872c86ea6698ed8faa3ccad1d1bd60f762f7 Author: Jani Nikula <jani.nik...@intel.com> Date: Fri Jul 1 15:24:44 2016 +0300 Documentation/sphinx: skip build if user requested specific DOCBOOKS Cc: Mauro Carvalho Chehab <mche...@s-opensource.com> Cc: Jonathan Corbet <cor...@lwn.net> Cc: Daniel Vetter <daniel.vet...@ffwll.ch> Signed-off-by: Jani Nikula <jani.nik...@intel.com> --- Jon, if we agree on the change, I'd like to have this for 4.8 before IGNORE_DOCBOOKS use proliferates. --- Documentation/DocBook/Makefile | 26 ++ 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 01bab5014a4a..fb32ab85ea3a 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -6,8 +6,6 @@ # To add a new book the only step required is to add the book to the # list of DOCBOOKS. -ifeq ($(IGNORE_DOCBOOKS),) - DOCBOOKS := z8530book.xml device-drivers.xml \ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ writing_usb_driver.xml networking.xml \ @@ -19,6 +17,14 @@ DOCBOOKS := z8530book.xml device-drivers.xml \ tracepoint.xml gpu.xml media_api.xml w1.xml \ writing_musb_glue_layer.xml crypto-API.xml iio.xml +ifeq ($(DOCBOOKS),) + +# Skip DocBook build if the user explicitly requested no DOCBOOKS. +.DEFAULT: + @echo " SKIPDocBook $@ target (DOCBOOKS=\"\" specified)." + +else + include Documentation/DocBook/media/Makefile ### @@ -217,19 +223,7 @@ silent_gen_xml = : -e "s/>/\\/g"; \ echo "") > $@ -else - -# Needed, due to cleanmediadocs -include Documentation/DocBook/media/Makefile - -htmldocs: -pdfdocs: -psdocs: -xmldocs: -installmandocs: - -endif # IGNORE_DOCBOOKS - +endif # DOCBOOKS="" ### # Help targets as used by the top-level makefile @@ -246,7 +240,7 @@ dochelp: @echo ' make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' @echo ' valid values for DOCBOOKS are: $(DOCBOOKS)' @echo - @echo " make IGNORE_DOCBOOKS=1 [target] Don't generate docs from Docbook" + @echo " make DOCBOOKS=\"\" [target] Don't generate docs from Docbook" @echo ' This is useful to generate only the ReST docs (Sphinx)' -- 2.1.4 -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] doc-rst: Remove the media docbook
On Wed, 27 Jul 2016, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: > Now that all media documentation was converted to Sphinx, we > should get rid of the old DocBook one, as we don't want people > to submit patches against the old stuff. Mauro, judging from the discussions we've had over the past six months, I never would have guessed media docs would be among the first docbooks converted. Fantastic job! BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Fri, 06 May 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > Am 06.05.2016 um 17:06 schrieb Jani Nikula <jani.nik...@intel.com>: > >> On Fri, 06 May 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: >>> @Jonathan: what do you think? Should I prepare a patch >>> with a basic reST (sphinx) build infrastructure, including >>> >>> * a folder for sphinx docs: >>> >>> ./Documentation/sphinx/ >> >> I'm already working on a patch series taking a different approach. I >> don't think we should hide the documentation under an extra folder named >> after a tool. Actually, I'm strongly opposed to that. > > Could you post a link to a repo? / thanks Very much a work-in-progress https://cgit.freedesktop.org/~jani/drm/log/?h=sphinx I was hoping to polish it a bit more before showing it to the world. > There is no need for concurrency, let's work together on your repo. > Within my POC I realized similar building processes we will need in the > kernel sources ... where you have cascading configuration. A base > configuration which fits for all common cases and (if needed) a > *per-book* configuration. > > At the end, when it comes to generate pdf books/articles, man pages > and e.g. texinfo files out of a sphinx-project you will need a build > infrastructure like this. ... > You will need on sphinx-project for each DocBook and one single > sphinx-project where you collect the .txt to .rst migrated files. Surely you know more about Sphinx than I do, but I specifically would like to include e.g. gpu documentation in the main build. I'm really hoping we can have *additional* configuration files for special cases (only) as needed. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Fri, 06 May 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > @Jonathan: what do you think? Should I prepare a patch > with a basic reST (sphinx) build infrastructure, including > > * a folder for sphinx docs: > > ./Documentation/sphinx/ I'm already working on a patch series taking a different approach. I don't think we should hide the documentation under an extra folder named after a tool. Actually, I'm strongly opposed to that. Instead, we should place the Sphinx stuff directly under Documentation, and have Sphinx recursively pick up all the *.rst files. We should promote gradually switching to lightweight markup and integration of the documents into one system. This process should be as little disruptive as possible. If someone wants to convert a .txt document to .rst and get it processed by Sphinx, it should be as simple as renaming the file, doing the necessary edits, and adding it to a toctree. Imagine gradually converting the files under, say, Documentation/kbuild. Why should the .rst files be moved under another directory? They should stay alongside the .txt files under the same directory. There's bound to be a lot of people who'll never use Sphinx, and will expect to find the good old plain text files (albeit with some markup) where they always were. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Wed, 04 May 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > Correct my, if I'am wrong. I'am a bit unfamiliar with DOCPROC in > particular with your "MARKDOWNREADY := gpu.xml" process. > > As I understood, you convert markdown to docbook within the kernel-doc > script using pandoc's executable? ... I don't face this topic. With my > modification of kernel-doc I produced pure reST markup from standardize > kernel-doc markup, no intermediate steps or tools required. That pandoc thing is a dead end. Forget about it. I think we've all pretty much agreed we should have kernel-doc produce the lightweight markup directly since [1]. [1] http://mid.gmane.org/1453106477-21359-1-git-send-email-jani.nik...@intel.com > Am 04.05.2016 um 17:09 schrieb Jonathan Corbet <cor...@lwn.net>: > >> I think all of this makes sense. It would be really nice to have the >> directives in the native sphinx language like that. I *don't* think we >> need to aim for that at the outset; the docproc approach works until we can >> properly get rid of it. What would be *really* nice would be to get >> support for the kernel-doc directive into the sphinx upstream. > > No need for kernel-doc directive in sphinx upstream, later it will be > an extension which could be installed by a simple command like > "pip install kernel-doc-extensions" or similar. > > I develop these required extension (and more) within my proof of concept > on github ... this takes time ... if I finished all my tests and all is > well, I will build the *kernel-doc-extensions* package and deploy it > on https://pypi.python.org/pypi from where everyone could install this > with "pip". I think we should go for vanilla sphinx at first, to make the setup step as easy as possible for everyone. Even if it means still doing that ugly docproc step to call kernel-doc. We can improve from there, and I definitely appreciate your work on making this work with sphinx extensions. That said, how would it work to include the kernel-doc extension in the kernel source tree? Having things just work if sphinx is installed is preferred over requiring installation of something extra from pypi. (I know this may sound backwards for a lot of projects, but for kernel I'm pretty sure this is how it should be done.) BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Wed, 04 May 2016, Jonathan Corbet <cor...@lwn.net> wrote: > The sphinx/rst approach does seem, to me, to be the right one, with the > existing DocBook structure remaining in place for those who want/need > it. I'm inclined toward my stuff as a base to work with, obviously :) But > it's hackish at best and needs a lot of cleaning up. It's a proof of > concept, but it's hardly finished (one might say it's barely begun...) Thanks. I'll start looking at how to make it less hackish and more upstreamable. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Wed, 04 May 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: >> What do you mean by ".tmpl workflow"? > > Sorry for bad naming, I addressed the DOCPROC build process which builds > the .xml files from .tmpl files ... Yeah, I know more about this part than I care. I was just wondering what you refer to with that in the sphinx context. > In reST the directive might look like: > > - > Device Instance and Driver Handling > === > > .. kernel-doc:: drivers/gpu/drm/drm_drv.c >:doc: driver instance overview >:exported: > > - Yes, I think something like this, parsed by sphinx directly (via some extension perhaps), should be the end goal. I am not sure if it should be the immediate first goal though or whether we should reuse the existing docproc for now. > Right, but you forgot, that the current markup in the source code comments > is based on the kernel-doc-nano-HOWTO and I guess no one will migrate all > these source code comments to reST markup ;-) > > So there is a need to differentiate between *vintage* kernel-doc markup > and reST markup. > > My suggestion is to add a tag to the comments, here a short example > what this might look like. > > -- > /** > * drm_minor_release - Release DRM minor > * @minor: Pointer to DRM minor object > * > * Release a minor that was previously acquired via drm_minor_acquire(). > */ > -- > > in short: the vintage style does not need any change and > comments with reST markup has a tag ":reST:" in the first > line(s) ... > > -- > /** > * :reST: > * > * .. c:function:: void drm_minor_release(struct drm_minor *minor) > * > *Release DRM minor > * > *:param struct drm_minor \*minor: Pointer to DRM minor object > * > */ > -- > > Comments with the ":reST:" tag could be exported and pass-through > to sphinx. Disagreed on most of the above. Maybe I was unclear in my previous mail, and I've probably worked on this so much previously that I thought it was clear how we should handle lightweight markup in kernel-doc comments. Kernel-doc the tool should continue to parse kernel-doc comments at the high level like they currently are, according to the kernel-doc howto. The first heading line, the parameter/member lines with @param:, and references within the text with @param, function(), structures, etc. For those, kernel-doc should produce appropriate rst elements. Beyond that, kernel-doc should *not* try to make guesses about the formatting of the documentation comments. It should just pass the rest of the formatting through. If the ad-hoc lists etc. in the current comments don't turn into proper rst lists, then so be it. If it bugs people, the comments will gradually be converted to proper rst. The worst we could do is promote a sloppy style that kernel-doc fixes for you, possibly "fixing" things you'd want to pass through to sphinx. What you have in example above will not fly. The documentation comment style must remain as is defined in the kernel-doc how, i.e. example. It is imperative that the kernel-doc comments remain as readable as they currently are in the source code. >> Specifically, do not attempt to detect and >> parse elements like lists in kernel-doc. > > If your markup in the comments is plain reST, no need to parse, but there > are markups in the (vintage) comments which made use of individual > text-markups, e.g. the markup of lists or ASCII-art. > > This individual text-markups has not been converted/rendered in the docbook > output, but I wanted to convert this individuals to reST, to render them in > Sphinx. > > E.g. compare the member & description section of struct drm-display-mode ... > > DocBook: > > * https://www.kernel.org/doc/htmldocs/gpu/API-struct-drm-display-mode.html > > kernel-doc reST with the additional reformat_block_rst function: > > * > http://return42.github.io/sphkerneldoc/linux_src_doc/include/drm/drm_modes_h.html#struct-drm-display-mode Overall I think we should promote fixing those in the kernel-doc comments. Trying to guesswork in kernel-doc tool will leave the source littered with bad examples that get proliferated all around. Instead of gradually fixing things, we'll end up gradually messing things up even more. For those specific examples, IIRC the last time I played with that, simply leaving the prefix whitespace in place went a long way (just eat " * " from the lines). The asciiart just worked. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Wed, 04 May 2016, Markus Heiser <markus.hei...@darmarit.de> wrote: > but I think this will not by very helpful, as long as you miss > a similar ".tmpl" workflow for reST documents. > > I'am working on a reST directive (named: "kernel-doc") to provide a > similar ".tmpl" workflow within plain reST. The first step towards > is done with (my) modified kernel-doc script ... > > * > https://github.com/return42/sphkerneldoc/blob/master/scripts/kernel-doc#L1736 > > which produce reST from source code comments. E.g. this content is > generated with it. What do you mean by ".tmpl workflow"? I'd be *very* hesitant about adding the kind of things you do in reformat_block_rst to kernel-doc. IMO the extraction from kernel-doc comments must be as simple as possible with basically pass-through of the comment blocks to sphinx. Specifically, do not attempt to detect and parse elements like lists in kernel-doc. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
/reStructuredText later on when we have everything else in place. It's not the perfect outcome, but IMHO it's the best overall choice. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Wed, 09 Mar 2016, Dan Allen <d...@opendevise.io> wrote: > On Tue, Mar 8, 2016 at 6:58 AM, Jani Nikula <jani.nik...@intel.com> wrote: > >> I need to look into this again. Is there a specific option or directive >> to produce split output for includes? When I tried this, the result was >> just one big output file. (And indeed we'd need both. Some includes we >> want embedded, some includes should produce separate outputs.) >> > > Nope. What I'm saying is that you run Asciidoctor on each sub-master > include file (an include that manages a part or chapter). That gives you > your individual part/chapter files. Then you need to make an index page, > probably by using the Asciidoctor API to itemize all the chapters as a list > or something. Bummer. Getting the inter-document cross references right may become tricky. We'll be generating plenty of snippets of lightweight markup from source code documentation comments. At the time of processing, we won't know where e.g. a specific function to be cross referenced is documented, if at all. We can't require the documentation comment writers to figure that out either; it's too burdensome, too ugly in the code, and they'll bitrot quickly. Cross referencing in the asciidoc proofs of concept have worked because they've all done the processing as a single single unit, with includes. These hacks have also ignored any broken links, and there have been > Yes, it does require some thinking about cross references. There is a lot > more we can do out of the box, but all those references can be fixed with a > little bit of post-processing in the meantime. It seems to me Sphinx provides much better support regarding cross references, out of the box, within documents and to external documents (intersphinx), with target roles and domains, including validation and not creating broken links in the output. Looking at the current hacks we have for post-processing references, I'm really not thrilled about the prospect of keeping or redoing that. See how this works in Jon's Sphinx test [1]. At the time of generating the markup from source comments, there is no idea if and where gem_init_hw() and intel_guc_ucode_init() are documented. Indeed, documentation for the former does not exist, but there's no broken link. BR, Jani. [1] http://static.lwn.net/kerneldoc/gpu.html#c.intel_guc_ucode_load -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Tue, 08 Mar 2016, Dan Allen <d...@opendevise.io> wrote: > That's not entirely true. First, you can pre-split at the source level > using includes and generate output for each of the masters. That's what I > tend to do and it works really well since these are logical split points. I need to look into this again. Is there a specific option or directive to produce split output for includes? When I tried this, the result was just one big output file. (And indeed we'd need both. Some includes we want embedded, some includes should produce separate outputs.) >> That actually makes choosing asciidoc harder, because >> requiring another language environment complicates, not simplifies, the >> toolchain. I'd really like to lower the bar for building the >> documentation, for everyone, so much so that it becomes part of the >> normal checks for patch inclusion. > > Pardon my bluntness here, but I don't buy that argument. This is Linux. > Installing software couldn't be simpler, and we're talking about an > extremely well supported language (Ruby). Granted, that part works for me. I'm not so sensitive to the dependencies; others may disagree. > I think it's a huge exaggeration to say that Asciidoctor is any harder to > install than AsciiDoc Python. It's also a heck of a lot smaller in size > since AsciiDoc Python pulls in hundreds of MB of LaTeX packages. For me, the comparison is really between Sphinx and Asciidoctor, not so much doc vs. doctor. The native output format and extension support in Sphinx is appealing; I am not yet convinced we could manage with Asciidoctor but without DocBook. The extension offering seems better in Sphinx. > Whatever you decide, I wish you all the best with your documentation > efforts! Thanks! BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Tue, 08 Mar 2016, Dan Allen <d...@opendevise.io> wrote: > One of the key goals of the Asciidoctor project is to be able to directly > produce a wide variety of outputs from the same source (without DocBook). > We've added flexibility and best practices into the syntax and matured the > converter mechanism to bridge this (sometimes very wide) gap. I think our conclusion so far was that the native AsciiDoc (and Asciidoctor) outputs fell short of our needs, forcing us to use the DocBook pipeline. I, for one, was hoping we could eventually simplify the toolchain. For example, there was no support for chunked, or split to chapters, HTML, and the single page result was simply way too big. > Asciidoctor is the future of AsciiDoc. Even the AsciiDoc Python maintainers > acknowledge that (including the original creator). Thanks for the input. We've touched the topic of AsciiDoc vs. Asciidoctor before [1]. So we should be using Asciidoctor instead of AsciiDoc. That actually makes choosing asciidoc harder, because requiring another language environment complicates, not simplifies, the toolchain. I'd really like to lower the bar for building the documentation, for everyone, so much so that it becomes part of the normal checks for patch inclusion. BR, Jani. [1] http://mid.gmane.org/86pow31ddj....@hiro.keithp.com -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Fri, 04 Mar 2016, Mauro Carvalho Chehab <mche...@osg.samsung.com> wrote: > Em Thu, 03 Mar 2016 15:23:23 -0800 > Keith Packard <kei...@keithp.com> escreveu: > >> Mauro Carvalho Chehab <mche...@osg.samsung.com> writes: >> >> > On my tests, Sphinix seemed too limited to format tables. Asciidoc >> > produced an output that worked better. >> >> Yes, asciidoc has much more flexibility in table formatting, including >> the ability to control text layout within cells and full control over >> borders. >> >> However, I think asciidoc has two serious problems: >> >> 1) the python version (asciidoc) appears to have been abandoned in >> favor of the ruby version. >> >> 2) It really is just a docbook pre-processor. Native html/latex output >> is poorly supported at best, and exposes only a small subset of the >> full capabilities of the input language. >> >> As such, we would have to commit to using the ruby version and either >> committing to fixing the native html output backend or continuing to use >> the rest of the docbook toolchain. >> >> We could insist on using the python version, of course. I spent a bit of >> time hacking that up to add 'real' support for a table-of-contents in >> the native HTML backend and it looks like getting those changes >> upstreamed would be reasonably straightforward. However, we'd end up >> 'owning' the code, and I'm not sure we want to. > > I'm a way more concerned about using a tool that fulfill our needs > than to look for something that won't use the docbook toolchain or > require to install ruby. I think you meant that to be the other way round, or I fail at parsing you. ;) > In the case of Docbook, we know it works and we know already its > issues. Please correct me if I'm wrong, but the big problem we > have is not due to the DocBook toolchain, but due to the lack of > features at the kernel-doc script. Also, xmlto is already installed > by the ones that build the kernel docs. So, keeping use it won't > require to install a weird toolchain by hand. I think kernel-doc is just a small part of the puzzle. It's a problem, but a small one at that, and we've already made it output asciidoc, rst and docbook as part of this exercise. For real, as in code, not as in talk. The reasons I'm involved in this is that I want to make writing documentation and rich kernel-doc comments easier (using lightweight markup) and I want to make building the documentation easier (using a straightforward toolchain with not too many dependencies). I'm hoping the former makes writing documentation more attractive and the latter keeps the documentation and the toolchain in a better shape through having more people actually build the documentation. IMHO docbook is problematic because the toolchain gets too long and fragile. You need plenty of tools installed to build the documentation, it's fussy to get working, and people just won't. Like code, documentation bitrots too when it's not used. The documentation build is broken too often. Debugging formatting issues through the entire pipeline gets hard; I already faced some of this when playing with the kernel-doc->asciidoc->docbook->html chain. In short, I don't think the docbook toolchain fills all of our needs either. > So, to be frank, it doesn't scary me to use either pyhton or > ruby script + docbook. > > Of course, having to own the code has a cost that should be evaluated. > > If, on the other hand, we decide to use RST, we'll very likely need to > patch it to fulfill our needs in order to add proper table support. > I've no idea how easy/difficult would be to do that, nor if Sphinx > upstream would accept such changes. > > So, at the end of the day, we may end by having to carry on our own > version of Sphinx inside our tree, with doesn't sound good, specially > since it is not just a script, but a package with hundreds of > files. If we end up having to modify Sphinx, it has a powerful extension mechanism for this. We wouldn't have to worry about getting it merged to Sphinx upstream, and we wouldn't have to carry a local version of all of Sphinx. (In fact, the extension mechanism provides a future path for doing kernel-doc within Sphinx instead of as a preprocessing step.) I know none of this alleviates your concerns with table supports right now. I'll try to have a look at that a bit more. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Fri, 04 Mar 2016, Russel Winder <rus...@winder.org.uk> wrote: > On Thu, 2016-03-03 at 15:23 -0800, Keith Packard wrote: >> 1) the python version (asciidoc) appears to have been abandoned in >> favor of the ruby version. > > This is I think true, however the Java-based tool chain Asciidoctor is > I believe the standard bearer for ASCIIdoc these days, albeit called > ASCIIdoctor. If we're talking about the same asciidoctor (http://asciidoctor.org/) it's written in ruby but you can apparently run it in JVM using JRuby. Calling it Java-based is misleading. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Kernel docs: muddying the waters a bit
On Sat, 13 Feb 2016, Jonathan Corbet <cor...@lwn.net> wrote: > So can we discuss? I'm not saying we have to use Sphinx, but, should we > choose not to, we should do so with open eyes and good reasons for the > course we do take. What do you all think? This stalled a bit, but the waters are still muddy... Is the Sphinx/reStructuredText table support adequate for media/v4l documentation? Are the Sphinx output formats adequate in general? Specifically, is the lack of DocBook support, and the flexibility it provides, a blocker? Otherwise, I think Sphinx is promising. Jon, I think we need a roll of dice, err, a well-thought-out decision from the maintainer to go with one or the other, so we can make some real progress. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v2 1/4] break kconfig dependency loop
On Wed, 01 Apr 2015, Gerd Hoffmann kra...@redhat.com wrote: After adding virtio-gpu I get this funky kconfig dependency loop. scripts/kconfig/conf --oldconfig Kconfig drivers/video/fbdev/Kconfig:5:error: recursive dependency detected! drivers/video/fbdev/Kconfig:5: symbol FB is selected by DRM_KMS_FB_HELPER drivers/gpu/drm/Kconfig:34: symbol DRM_KMS_FB_HELPER is selected by DRM_VIRTIO_GPU drivers/gpu/drm/virtio/Kconfig:1: symbol DRM_VIRTIO_GPU depends on VIRTIO drivers/virtio/Kconfig:1: symbol VIRTIO is selected by REMOTEPROC drivers/remoteproc/Kconfig:4: symbol REMOTEPROC is selected by OMAP_REMOTEPROC drivers/remoteproc/Kconfig:12: symbol OMAP_REMOTEPROC depends on OMAP_IOMMU drivers/iommu/Kconfig:141: symbol OMAP_IOMMU is selected by VIDEO_OMAP3 drivers/media/platform/Kconfig:96: symbol VIDEO_OMAP3 depends on VIDEO_V4L2 drivers/media/v4l2-core/Kconfig:6: symbol VIDEO_V4L2 depends on I2C drivers/i2c/Kconfig:7: symbol I2C is selected by FB_DDC drivers/video/fbdev/Kconfig:59: symbol FB_DDC is selected by FB_CYBER2000_DDC drivers/video/fbdev/Kconfig:374:symbol FB_CYBER2000_DDC depends on FB_CYBER2000 drivers/video/fbdev/Kconfig:362:symbol FB_CYBER2000 depends on FB Making VIDEO_OMAP3 depend on OMAP_IOMMU instead of selecting it breaks the loop, which looks like the best way to handle it to me. I'm open to better suggestions though. I think part of the problem is that select is often used not as documented [1] but rather as show my config in menuconfig for convenience even if my dependency is not met, and select the dependency even though I know it can screw up the dependency chain. In light of the documentation, your patch seems to DTRT. (Disclaimer: I don't work with the drivers in question, hence no Reviewed-by.) In the big picture, it feels like menuconfig needs a way to display items whose dependencies are not met, and a way to recursively enable said items and all their dependencies when told. This would reduce the resistance to sticking with select when clearly depends is what's meant. BR, Jani. [1] Documentation/kbuild/kconfig-language.txt: In general use select only for non-visible symbols (no prompts anywhere) and for symbols with no dependencies. That will limit the usefulness but on the other hand avoid the illegal configurations all over. Signed-off-by: Gerd Hoffmann kra...@redhat.com --- drivers/media/platform/Kconfig | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/media/platform/Kconfig b/drivers/media/platform/Kconfig index d9b872b..fc21734 100644 --- a/drivers/media/platform/Kconfig +++ b/drivers/media/platform/Kconfig @@ -87,8 +87,8 @@ config VIDEO_OMAP3 tristate OMAP 3 Camera support depends on VIDEO_V4L2 I2C VIDEO_V4L2_SUBDEV_API ARCH_OMAP3 depends on HAS_DMA + depends on OMAP_IOMMU select ARM_DMA_USE_IOMMU - select OMAP_IOMMU select VIDEOBUF2_DMA_CONTIG ---help--- Driver for an OMAP 3 camera controller. -- 1.8.3.1 ___ dri-devel mailing list dri-de...@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/dri-devel -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line unsubscribe linux-media in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/2] [RFC] video: display: Adding frame related ops to MIPI DSI video source struct
On Thu, 10 Jan 2013, Inki Dae inki@samsung.com wrote:
2013/1/10 Laurent Pinchart laurent.pinch...@ideasonboard.com:
Hi Vikas,
Thank you for the patch.
On Friday 04 January 2013 10:24:04 Vikas Sajjan wrote:
On 3 January 2013 16:29, Tomasz Figa t.f...@samsung.com wrote:
On Wednesday 02 of January 2013 18:47:22 Vikas C Sajjan wrote:
From: Vikas Sajjan vikas.saj...@linaro.org
Signed-off-by: Vikas Sajjan vikas.saj...@linaro.org
---
include/video/display.h |6 ++
1 file changed, 6 insertions(+)
diff --git a/include/video/display.h b/include/video/display.h
index b639fd0..fb2f437 100644
--- a/include/video/display.h
+++ b/include/video/display.h
@@ -117,6 +117,12 @@ struct dsi_video_source_ops {
void (*enable_hs)(struct video_source *src, bool enable);
+ /* frame related */
+ int (*get_frame_done)(struct video_source *src);
+ int (*clear_frame_done)(struct video_source *src);
+ int (*set_early_blank_mode)(struct video_source *src, int power);
+ int (*set_blank_mode)(struct video_source *src, int power);
+
I'm not sure if all those extra ops are needed in any way.
Looking and Exynos MIPI DSIM driver, set_blank_mode is handling only
FB_BLANK_UNBLANK status, which basically equals to the already existing
enable operation, while set_early_blank mode handles only
FB_BLANK_POWERDOWN, being equal to disable callback.
Right, exynos_mipi_dsi_blank_mode() only supports FB_BLANK_UNBLANK as
of now, but FB_BLANK_NORMAL will be supported in future.
If not for Exynos, i think it will be need for other SoCs which
support FB_BLANK_UNBLANK and FB_BLANK_NORMAL.
Could you please explain in a bit more details what the set_early_blank_mode
and set_blank_mode operations do ?
Both get_frame_done and clear_frame_done do not look at anything used at
the moment and if frame done status monitoring will be ever needed, I
think a better way should be implemented.
You are right, as of now Exynos MIPI DSI Panels are NOT using these
callbacks, but as you mentioned we will need frame done status monitoring
anyways, so i included these callbacks here. Will check, if we can implement
any better method.
Do you expect the entity drivers (and in particular the panel drivers) to
require frame done notification ? If so, could you explain your use case(s) ?
Hi Laurent,
As you know, there are two types of MIPI-DSI based lcd panels, RGB and
CPU mode. In case of CPU mode lcd panel, it has its own framebuffer
internally and the image in the framebuffer is transferred on lcd
panel in 60Hz itself. But for this, there is something we should
consider. The display controller with CPU mode doens't transfer image
data to MIPI-DSI controller itself. So we should set trigger bit of
the display controller to 1 to do it and also check whether the data
transmission in the framebuffer is done on lcd panel to avoid tearing
issue and some confliction issue(A) between read and write operations
like below,
Quite right. Just to elaborate, in the MIPI DSI spec the two types are
called Video Mode and Command Mode display modules, of which the latter
has a framebuffer of its own. Update of the display module framebuffer
has to dodge the scanning of the buffer by the display module's
controller to avoid tearing. For that, info about the controller's
scanline is required. There are basically three ways for this:
1) polling the scanline using DCS get_scan_line command
2) enabling tearing effect reporting, and turning over bus ownership to
the display module for subsequent tearing effect signal (vertical
blanking) reporting by the module at the specified scanline
3) external GPIO line (outside of DSI PHY spec) to report tearing effect
signal
For an example, drivers/video/omap2/displays/panel-taal.c supports
option #2 via OMAP DSI and option #3 independently.
BR,
Jani.
lcd_panel_frame_done_interrrupt_handler()
{
...
if (mipi-dsi frame done)
trigger display controller;
...
}
A. the issue that LCD panel can access its own framebuffer while some
new data from MIPI-DSI controller is being written in the framebuffer.
But I think there might be better way to avoid such thing.
Thanks,
Inki Dae
--
Regards,
Laurent Pinchart
___
dri-devel mailing list
dri-de...@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel
___
dri-devel mailing list
dri-de...@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC v2 0/5] Common Display Framework
Hi Laurent - On Tue, 18 Dec 2012, Laurent Pinchart laurent.pinch...@ideasonboard.com wrote: Hi Jani, On Monday 17 December 2012 18:53:37 Jani Nikula wrote: I can see the need for a framework for DSI panels and such (in fact Tomi and I have talked about it like 2-3 years ago already!) but what is the story for HDMI and DP? In particular, what's the relationship between DRM and CDF here? Is there a world domination plan to switch the DRM drivers to use this framework too? ;) Do you have some rough plans how DRM and CDF should work together in general? There's always a world domination plan, isn't there ? :-) I certainly want CDF to be used by DRM (or more accurately KMS). That's what the C stands for, common refers to sharing panel and other display entity drivers between FBDEV, KMS and V4L2. I currently have no plan to expose CDF internals to userspace through the KMS API. We might have to do so later if the hardware complexity grows in such a way that finer control than what KMS provides needs to be exposed to userspace, but I don't think we're there yet. The CDF API will thus only be used internally in the kernel by display controller drivers. The KMS core might get functions to handle common display entity operations, but the bulk of the work will be in the display controller drivers to start with. We will then see what can be abstracted in KMS helper functions. Regarding HDMI and DP, I imagine HDMI and DP drivers that would use the CDF API. That's just a thought for now, I haven't tried to implement them, but it would be nice to handle HDMI screens and DPI/DBI/DSI panels in a generic way. Do you have thoughts to share on this topic ? It just seems to me that, at least from a DRM/KMS perspective, adding another layer (=CDF) for HDMI or DP (or legacy outputs) would be overengineering it. They are pretty well standardized, and I don't see there would be a need to write multiple display drivers for them. Each display controller has one, and can easily handle any chip specific requirements right there. It's my gut feeling that an additional framework would just get in the way. Perhaps there could be more common HDMI/DP helper style code in DRM to reduce overlap across KMS drivers, but that's another thing. So is the HDMI/DP drivers using CDF a more interesting idea from a non-DRM perspective? Or, put another way, is it more of an alternative to using DRM? Please enlighten me if there's some real benefit here that I fail to see! For DSI panels (or DSI-to-whatever bridges) it's of course another story. You typically need a panel specific driver. And here I see the main point of the whole CDF: decoupling display controllers and the panel drivers, and sharing panel (and converter chip) specific drivers across display controllers. Making it easy to write new drivers, as there would be a model to follow. I'm definitely in favour of coming up with some framework that would tackle that. BR, Jani. -- To unsubscribe from this list: send the line unsubscribe linux-media in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC v2 0/5] Common Display Framework
Hi Laurent -
On Mon, 17 Dec 2012, Laurent Pinchart laurent.pinch...@ideasonboard.com wrote:
Hi Tomi,
I finally have time to work on a v3 :-)
On Friday 23 November 2012 16:51:37 Tomi Valkeinen wrote:
On 2012-11-22 23:45, Laurent Pinchart wrote:
From: Laurent Pinchart laurent.pinchart+rene...@ideasonboard.com
Hi everybody,
Here's the second RFC of what was previously known as the Generic Panel
Framework.
Nice work! Thanks for working on this.
I was doing some testing with the code, seeing how to use it in omapdss.
Here are some thoughts:
In your model the DSS gets the panel devices connected to it from
platform data. After the DSS and the panel drivers are loaded, DSS gets
a notification and connects DSS and the panel.
I think it's a bit limited way. First of all, it'll make the DT data a
bit more complex (although this is not a major problem). With your
model, you'll need something like:
soc-base.dtsi:
dss {
dpi0: dpi {
};
};
board.dts:
dpi0 {
panel = dpi-panel;
};
/ {
dpi-panel: dpi-panel {
...panel data...;
};
};
Second, it'll prevent hotplug, and even if real hotplug would not be
supported, it'll prevent cases where the connected panel must be found
dynamically (like reading ID from eeprom).
Hotplug definitely needs to be supported, as the common display framework
also
targets HDMI and DP. The notification mechanism was actually designed to
support hotplug.
I can see the need for a framework for DSI panels and such (in fact Tomi
and I have talked about it like 2-3 years ago already!) but what is the
story for HDMI and DP? In particular, what's the relationship between
DRM and CDF here? Is there a world domination plan to switch the DRM
drivers to use this framework too? ;) Do you have some rough plans how
DRM and CDF should work together in general?
BR,
Jani.
How do you see the proposal preventing hotplug ?
Third, it kinda creates a cyclical dependency: the DSS needs to know
about the panel and calls ops in the panel, and the panel calls ops in
the DSS. I'm not sure if this is an actual problem, but I usually find
it simpler if calls are done only in one direction.
I don't see any way around that. The panel is not a standalone entity that
can
only receive calls (as it needs to control video streams, per your request
:-)) or only emit calls (as something needs to control it, userspace doesn't
control the panel directly).
What I suggest is take a simpler approach, something alike to how regulators
or gpios are used, even if slightly more complex than those: the entity that
has a video output (SoC's DSS, external chips) offers that video output as
resource. It doesn't know or care who uses it. The user of the video output
(panel, external chips) will find the video output (to which it is connected
in the HW) by some means, and will use different operations on that output
to operate the device.
This would give us something like the following DT data:
soc-base.dtsi:
dss {
dpi0: dpi {
};
};
board.dts:
/ {
dpi-panel: dpi-panel {
source = dpi0;
...panel data...;
};
};
The panel driver would do something like this in its probe:
int dpi_panel_probe()
{
// Find the video source, increase ref
src = get_video_source_from_of(source);
// Reserve the video source for us. others can still get and
// observe it, but cannot use it as video data source.
// I think this should cascade upstream, so that after this call
// each video entity from the panel to the SoC's CRTC is
// reserved and locked for this video pipeline.
reserve_video_source(src);
// set DPI HW configuration, like DPI data lines. The
// configuration would come from panel's platform data
set_dpi_config(src, config);
// register this panel as a display.
register_display(this);
}
The DSS's dpi driver would do something like:
int dss_dpi_probe()
{
// register as a DPI video source
register_video_source(this);
}
A DSI-2-DPI chip would do something like:
int dsi2dpi_probe()
{
// get, reserve and config the DSI bus from SoC
src = get_video_source_from_of(source);
reserve_video_source(src);
set_dsi_config(src, config);
// register as a DPI video source
register_video_source(this);
}
Here we wouldn't have similar display_entity as you have, but video sources
and displays. Video sources are elements in the video pipeline, and a video
source is used only by the next downstream element. The last element in the
pipeline would not be a video source, but a display, which would be used by
the upper layer.
I don't think we should handle pure sources, pure sinks (displays) and mixed
entities (transceivers) differently. I prefer having abstract entities that
can have a source and a sink, and
