Re: V4L docs and docbook
On Wed, 2016-02-17 at 21:51 -0200, Mauro Carvalho Chehab wrote: > […] > > We have 2 types of documentation for the Kernel part of the > subsystem, > Both using DocBook: > - The uAPI documentation: > https://linuxtv.org/downloads/v4l-dvb-apis > - The kAPI documentation: > https://linuxtv.org/downloads/v4l-dvb-internals/device-drivers/ > mediadev.html […] I may not be introducing new data here but… Whilst ReStructuredText and Markdown are fairly popular text markup languages, they are not related to the DocBook/XML toolchain. Many people, especially authors of books etc. are not really willing to write in DocBook/XML even though it is the re-purposable representation of choice for most of the major publishers. This led to ASCIIDoc. ASCIIDoc is a plain text markup language in the same way ReStructuredText and Markdown are, but it's intention was always to be a lightweight front end to DocBook/XML so as to allow authors to write in a nice markup language but work with the DocBook/XML toolchain. ASCIIDoc has gained quite a strong following. So much so that it now has a life of its own separate from the DocBook/XML tool chain. There is ASCIIDoctor which generates PDF, HTML,… from the source without using DocBook/XML, yet the source can quite happily go through a DocBook/XML toolchain as well. Many of the open source projects I am involved with are now using ASCIIDoctor as the documentation form. This has increased the number of non-main-contributor contributions via pull requests. It is so much easier to work with ASCIIDoc(tor) source than DocBook/XML source. -- Russel. = Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel.win...@ekiga.net 41 Buckmaster Roadm: +44 7770 465 077 xmpp: rus...@winder.org.uk London SW11 1EN, UK w: www.russel.org.uk skype: russel_winder signature.asc Description: This is a digitally signed message part
Re: V4L docs and docbook
Em Thu, 18 Feb 2016 08:17:00 + Russel Winder escreveu: > On Wed, 2016-02-17 at 21:51 -0200, Mauro Carvalho Chehab wrote: > > […] > > > > We have 2 types of documentation for the Kernel part of the > > subsystem, > > Both using DocBook: > > - The uAPI documentation: > > https://linuxtv.org/downloads/v4l-dvb-apis > > - The kAPI documentation: > > https://linuxtv.org/downloads/v4l-dvb-internals/device-drivers/ > > mediadev.html > […] > > I may not be introducing new data here but… > > Whilst ReStructuredText and Markdown are fairly popular text markup > languages, they are not related to the DocBook/XML toolchain. > > Many people, especially authors of books etc. are not really willing to > write in DocBook/XML even though it is the re-purposable representation > of choice for most of the major publishers. This led to ASCIIDoc. > > ASCIIDoc is a plain text markup language in the same way > ReStructuredText and Markdown are, but it's intention was always to be > a lightweight front end to DocBook/XML so as to allow authors to write > in a nice markup language but work with the DocBook/XML toolchain. > > ASCIIDoc has gained quite a strong following. So much so that it now > has a life of its own separate from the DocBook/XML tool chain. There > is ASCIIDoctor which generates PDF, HTML,… from the source without > using DocBook/XML, yet the source can quite happily go through a > DocBook/XML toolchain as well. > > Many of the open source projects I am involved with are now using > ASCIIDoctor as the documentation form. This has increased the number of > non-main-contributor contributions via pull requests. It is so much > easier to work with ASCIIDoc(tor) source than DocBook/XML source. Are there any tools that would convert from DocBook to ASCIIDoc? Thanks, Mauro pgp06fUKfAiNJ.pgp Description: Assinatura digital OpenPGP
Re: V4L docs and docbook
Em Thu, 18 Feb 2016 06:31:14 -0200 Mauro Carvalho Chehab escreveu: > Em Thu, 18 Feb 2016 08:17:00 + > Russel Winder escreveu: > > > On Wed, 2016-02-17 at 21:51 -0200, Mauro Carvalho Chehab wrote: > > > […] > > > > > > We have 2 types of documentation for the Kernel part of the > > > subsystem, > > > Both using DocBook: > > > - The uAPI documentation: > > > https://linuxtv.org/downloads/v4l-dvb-apis > > > - The kAPI documentation: > > > https://linuxtv.org/downloads/v4l-dvb-internals/device-drivers/ > > > mediadev.html > > […] > > > > I may not be introducing new data here but… > > > > Whilst ReStructuredText and Markdown are fairly popular text markup > > languages, they are not related to the DocBook/XML toolchain. > > > > Many people, especially authors of books etc. are not really willing to > > write in DocBook/XML even though it is the re-purposable representation > > of choice for most of the major publishers. This led to ASCIIDoc. > > > > ASCIIDoc is a plain text markup language in the same way > > ReStructuredText and Markdown are, but it's intention was always to be > > a lightweight front end to DocBook/XML so as to allow authors to write > > in a nice markup language but work with the DocBook/XML toolchain. > > > > ASCIIDoc has gained quite a strong following. So much so that it now > > has a life of its own separate from the DocBook/XML tool chain. There > > is ASCIIDoctor which generates PDF, HTML,… from the source without > > using DocBook/XML, yet the source can quite happily go through a > > DocBook/XML toolchain as well. > > > > Many of the open source projects I am involved with are now using > > ASCIIDoctor as the documentation form. This has increased the number of > > non-main-contributor contributions via pull requests. It is so much > > easier to work with ASCIIDoc(tor) source than DocBook/XML source. > > Are there any tools that would convert from DocBook to ASCIIDoc? Answering myself: I found one tool at: https://github.com/oreillymedia/docbook2asciidoc That seemed to work. I ran it with: $ make DOCBOOKS=media_api.xml htmldocs 2>&1 | grep -v "element.*: validity error : ID .* already defined" $ xmllint --noent --postvalid "$PWD/Documentation/DocBook/media_api.xml" >/tmp/x.xml 2>/dev/null $ java -jar saxon9he.jar -s /tmp/x.xml -o book.asciidoc d2a_docbook.xsl chunk-output=true And it produced a series of documents, that I stored at: https://mchehab.fedorapeople.org/media-kabi-docs-test/ I noticed, however, that it kept some things using DocBook xml. Perhaps because some things cannot be translated to markup (see appa.asciidoc)? Also, converting them to HTML produced me some errors, but perhaps because I don't know what I'm doing ;) What I did was: for i in book-docinfo.xml *.asciidoc; do asciidoc $i; done errors enclosed. Yet, it seems there are some hope on using asciidoc for the kAPI documentation. Thanks, Mauro --- asciidoc: ERROR: book.asciidoc: line 9: only book doctypes can contain level 0 sections asciidoc: ERROR: ch01.asciidoc: line 588: only book doctypes can contain level 0 sections asciidoc: ERROR: ch02.asciidoc: line 2: section title not permitted in delimited block asciidoc: ERROR: ch03.asciidoc: line 2: section title not permitted in delimited block asciidoc: ERROR: ch03.asciidoc: line 370: illegal style name: capture example asciidoc: ERROR: ch04.asciidoc: line 2: section title not permitted in delimited block asciidoc: ERROR: ch04.asciidoc: line 719: illegal style name: to do asciidoc: ERROR: ch05.asciidoc: line 2: section title not permitted in delimited block asciidoc: ERROR: ch06.asciidoc: line 2: section title not permitted in delimited block asciidoc: ERROR: ch07.asciidoc: line 2: section title not permitted in delimited block asciidoc: ERROR: ch07.asciidoc: line 907: illegal style name: Solution? asciidoc: ERROR: ch07.asciidoc: line 2208: illegal style name: to do - OSS/ALSA asciidoc: ERROR: appa.asciidoc: line 3: section title not permitted in delimited block asciidoc: WARNING: appa.asciidoc: line 7: missing style: [blockdef-pass]: appendix asciidoc: ERROR: appb.asciidoc: line 2: section title not permitted in delimited block asciidoc: WARNING: appb.asciidoc: line 7: missing style: [paradef-default]: appendix asciidoc: ERROR: appc.asciidoc: line 3: section title not permitted in delimited block asciidoc: WARNING: appc.asciidoc: line 7: missing style: [blockdef-pass]: appendix asciidoc: ERROR: appd.asciidoc: line 3: section title not permitted in delimited block asciidoc: WARNING: appd.asciidoc: line 7: missing style: [blockdef-pass]: appendix asciidoc: ERROR: appe.asciidoc: line 3: section title not permitted in delimited block asciidoc: WARNING: appe.asciidoc: line 5: missing style: [paradef-default]: appendix asciidoc: ERROR: book.asciidoc: line 142: section title not permitted in delimited block asciidoc: ERROR: book.asciidoc: line 148: section tit
Re: Kernel docs: muddying the waters a bit
On Thu, 18 Feb 2016, Daniel Vetter wrote: > On Wed, Feb 17, 2016 at 11:14 PM, Jonathan Corbet wrote: >> On Sun, 14 Feb 2016 13:27:04 +0100 >> Daniel Vetter wrote: >> >>> One concern/open I have for pro/cons are the hyperlinks from kerneldoc >>> comments. Currently we have the postproc hack, iirc Jani's patches >>> generated links native when extracting the kerneldoc. What's the >>> solution with spinx? >> >> So I've been trying to figure out what this refers to. Is this the >> cross-reference links within the document? When I did my sphinx hack it >> used a technique that, shall we say, strongly resembles what Jani's >> patches did. One difference is that Sphinx has the concept of >> "functions" built into it, so I use function references for those. > > That's what I meant. As long as I can type in stuff like func(), > &struct and similar and get a link for it automatically (plus anywhere > else in the templated stuff for function headers) I'm really happy. I think that could be made to work in rst just as well as asciidoc. Which is to say, kernel-doc may generate broken refs in both, since it doesn't know if the link target exists outside of the file. Also, in theory, it's possible to generate non-unique targets in the end result if there are same named enums, structs, static functions etc. but I think that's less of a problem. Asciidoc just ignores these issues, I don't know what sphinx does. I think some of that could be alleviated by making the kernel-doc inclusion a directive through a sphinx extension. It could at the very least provide informative error messages. But that's distant future. Worth noting is that, AFAICT, in all of the proposals, including the original where kernel-doc produces docbook, this autoreferencing only works within parts processed by kernel-doc. Not in the template documents themselves. (You can still use the markup's more verbose cross referencing keywords.) BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- 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
Re: Kernel docs: muddying the waters a bit
On Thu, Feb 18, 2016 at 10:11 AM, Jani Nikula wrote: > On Thu, 18 Feb 2016, Daniel Vetter wrote: >> On Wed, Feb 17, 2016 at 11:14 PM, Jonathan Corbet wrote: >>> On Sun, 14 Feb 2016 13:27:04 +0100 >>> Daniel Vetter wrote: >>> One concern/open I have for pro/cons are the hyperlinks from kerneldoc comments. Currently we have the postproc hack, iirc Jani's patches generated links native when extracting the kerneldoc. What's the solution with spinx? >>> >>> So I've been trying to figure out what this refers to. Is this the >>> cross-reference links within the document? When I did my sphinx hack it >>> used a technique that, shall we say, strongly resembles what Jani's >>> patches did. One difference is that Sphinx has the concept of >>> "functions" built into it, so I use function references for those. >> >> That's what I meant. As long as I can type in stuff like func(), >> &struct and similar and get a link for it automatically (plus anywhere >> else in the templated stuff for function headers) I'm really happy. > > I think that could be made to work in rst just as well as > asciidoc. Which is to say, kernel-doc may generate broken refs in both, > since it doesn't know if the link target exists outside of the > file. Also, in theory, it's possible to generate non-unique targets in > the end result if there are same named enums, structs, static functions > etc. but I think that's less of a problem. Asciidoc just ignores these > issues, I don't know what sphinx does. > > I think some of that could be alleviated by making the kernel-doc > inclusion a directive through a sphinx extension. It could at the very > least provide informative error messages. But that's distant future. > > Worth noting is that, AFAICT, in all of the proposals, including the > original where kernel-doc produces docbook, this autoreferencing only > works within parts processed by kernel-doc. Not in the template > documents themselves. (You can still use the markup's more verbose cross > referencing keywords.) It works everywhere, even in the docbook template, as long as you mark it up correctly. Which in docbook means func. That's because it's a post-proc path over the entire doc. But then the entire point here is to move the overview sections all into kerneldoc, so making the links in the templates more verbose shouldn't be a big deal. -Daniel -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch -- 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
Re: V4L docs and docbook
Em Thu, 18 Feb 2016 07:10:14 -0200 Mauro Carvalho Chehab escreveu: > Em Thu, 18 Feb 2016 06:31:14 -0200 > Mauro Carvalho Chehab escreveu: > > > Em Thu, 18 Feb 2016 08:17:00 + > > Russel Winder escreveu: > > > > > On Wed, 2016-02-17 at 21:51 -0200, Mauro Carvalho Chehab wrote: > > > > […] > > > > > > > > We have 2 types of documentation for the Kernel part of the > > > > subsystem, > > > > Both using DocBook: > > > > - The uAPI documentation: > > > > https://linuxtv.org/downloads/v4l-dvb-apis > > > > - The kAPI documentation: > > > > https://linuxtv.org/downloads/v4l-dvb-internals/device-drivers/ > > > > mediadev.html > > > […] > > > > > > I may not be introducing new data here but… > > > > > > Whilst ReStructuredText and Markdown are fairly popular text markup > > > languages, they are not related to the DocBook/XML toolchain. > > > > > > Many people, especially authors of books etc. are not really willing to > > > write in DocBook/XML even though it is the re-purposable representation > > > of choice for most of the major publishers. This led to ASCIIDoc. > > > > > > ASCIIDoc is a plain text markup language in the same way > > > ReStructuredText and Markdown are, but it's intention was always to be > > > a lightweight front end to DocBook/XML so as to allow authors to write > > > in a nice markup language but work with the DocBook/XML toolchain. > > > > > > ASCIIDoc has gained quite a strong following. So much so that it now > > > has a life of its own separate from the DocBook/XML tool chain. There > > > is ASCIIDoctor which generates PDF, HTML,… from the source without > > > using DocBook/XML, yet the source can quite happily go through a > > > DocBook/XML toolchain as well. > > > > > > Many of the open source projects I am involved with are now using > > > ASCIIDoctor as the documentation form. This has increased the number of > > > non-main-contributor contributions via pull requests. It is so much > > > easier to work with ASCIIDoc(tor) source than DocBook/XML source. > > > > Are there any tools that would convert from DocBook to ASCIIDoc? > > Answering myself: > > I found one tool at: > https://github.com/oreillymedia/docbook2asciidoc > > That seemed to work. I ran it with: > $ make DOCBOOKS=media_api.xml htmldocs 2>&1 | grep -v "element.*: > validity error : ID .* already defined" > $ xmllint --noent --postvalid > "$PWD/Documentation/DocBook/media_api.xml" >/tmp/x.xml 2>/dev/null > $ java -jar saxon9he.jar -s /tmp/x.xml -o book.asciidoc d2a_docbook.xsl > chunk-output=true > > And it produced a series of documents, that I stored at: > https://mchehab.fedorapeople.org/media-kabi-docs-test/ > > I noticed, however, that it kept some things using DocBook xml. Perhaps > because some things cannot be translated to markup (see appa.asciidoc)? > > Also, converting them to HTML produced me some errors, but perhaps because > I don't know what I'm doing ;) > > What I did was: > for i in book-docinfo.xml *.asciidoc; do asciidoc $i; done > > errors enclosed. Stupid me: it should be just: asciidoc book.asciidoc Still, there are lots of broken things there, and lots of errors when building it: https://mchehab.fedorapeople.org/media-kabi-docs-test/book.html Ok, I would expect the need to handling some things manually, but it worries that it broke the tables. For example, see "Table 1. Control IDs" at https://mchehab.fedorapeople.org/media-kabi-docs-test/book.html It was mapped as a 3 cols table, but this is how it should be, instead: https://linuxtv.org/downloads/v4l-dvb-apis/control.html As this table has actually 5 cols, because some controls have a list of multiple values (see V4L2_CID_COLORFX for example). -- 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
Re: V4L docs and docbook
On Thu, 18 Feb 2016, Russel Winder wrote: > On Wed, 2016-02-17 at 21:51 -0200, Mauro Carvalho Chehab wrote: >> […] >> >> We have 2 types of documentation for the Kernel part of the >> subsystem, >> Both using DocBook: >> - The uAPI documentation: >> https://linuxtv.org/downloads/v4l-dvb-apis >> - The kAPI documentation: >> https://linuxtv.org/downloads/v4l-dvb-internals/device-drivers/ >> mediadev.html > […] > > I may not be introducing new data here but… > > Whilst ReStructuredText and Markdown are fairly popular text markup > languages, they are not related to the DocBook/XML toolchain. > > Many people, especially authors of books etc. are not really willing to > write in DocBook/XML even though it is the re-purposable representation > of choice for most of the major publishers. This led to ASCIIDoc. > > ASCIIDoc is a plain text markup language in the same way > ReStructuredText and Markdown are, but it's intention was always to be > a lightweight front end to DocBook/XML so as to allow authors to write > in a nice markup language but work with the DocBook/XML toolchain. We have been looking at asciidoc too, so much so that there are draft patches by Jon and me to build some of the documentation from asciidoc source. Both are in the thread starting at [1]. But we really need to consider reStructuredText too [2]. I think this thread is about figuring out how much we really depend on DocBook. There is a lot of pain in dealing with DocBook, especially as a source format, but also as an intermediate format. If we can produce the end results (html, pdf, man, ...) from the source markup directly, it's a win. > ASCIIDoc has gained quite a strong following. So much so that it now > has a life of its own separate from the DocBook/XML tool chain. There > is ASCIIDoctor which generates PDF, HTML,… from the source without > using DocBook/XML, yet the source can quite happily go through a > DocBook/XML toolchain as well. See some of the other threads. Asciidoc seems to be in maintenance mode. Asciidoctor depends on a ruby environment which is not met with enthusiasm. The HTML output can only be chunked (split to several pages) via the DocBook output. Sphinx is active, doesn't add a lot of new dependencies, and seems to be able to natively output all the end results people have so far said they care about. > Many of the open source projects I am involved with are now using > ASCIIDoctor as the documentation form. This has increased the number of > non-main-contributor contributions via pull requests. It is so much > easier to work with ASCIIDoc(tor) source than DocBook/XML source. I'm hopeful this holds for any of the lightweight markups. BR, Jani. [1] http://lkml.kernel.org/r/1453764522-29030-1-git-send-email-cor...@lwn.net [2] http://lkml.kernel.org/r/20160213145317.247c6...@lwn.net -- Jani Nikula, Intel Open Source Technology Center -- 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
Re: V4L docs and docbook
On Thu, 18 Feb 2016, Mauro Carvalho Chehab wrote: > Are there any tools that would convert from DocBook to ASCIIDoc? I used pandoc when I tested the asciidoc pipeline. Something along the lines of this for filtering docbook in stdin to asciidoc in stdout: pandoc --atx-headers -f docbook -t asciidoc BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- 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
Re: V4L docs and docbook
Em Thu, 18 Feb 2016 11:37:41 +0200 Jani Nikula escreveu: > On Thu, 18 Feb 2016, Mauro Carvalho Chehab wrote: > > Are there any tools that would convert from DocBook to ASCIIDoc? > > I used pandoc when I tested the asciidoc pipeline. Something along the > lines of this for filtering docbook in stdin to asciidoc in stdout: > > pandoc --atx-headers -f docbook -t asciidoc > Results are at: https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/ pandoc/asciidoc also broke the tables. 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
Re: V4L docs and docbook
On Thu, 18 Feb 2016, Hans Verkuil wrote: > I looked at ReStructuredText and it looks like it will be a pain to convert > the media DocBook code to that, and the main reason is the poor table support. > The syntax for that looks very painful and the media DocBook is full of > tables. The table support seems to be one point in favor of asciidoc over reStructuredText [citation needed]. > BTW, my daily build scripts also rebuilds the media spec and it is available > here: https://hverkuil.home.xs4all.nl/spec/media.html > > Also missing in ReStructuredText seems to be support for formulas (see for > example the Colorspaces section in the spec), although to be fair standard > DocBook doesn't do a great job at that either. This may be true for vanilla rst as supported by Python docutils, but the Sphinx tool we're considering does support a lot of things through extensions. The builtin extensions include support for rendering math via PNG or javascript [1]. There's also support for embedded graphviz [2] which may be of interest. > Now, I hate DocBook so going to something easier would certainly be nice, > but I think it is going to be a difficult task. > > Someone would have to prove that going to another formatting tool will > produce good results for our documentation. We can certainly give a few > representative sections of our doc to someone to convert, and if that > looks OK, then the full conversion can be done. It would be great to have you actively on board doing this yourself, seeking the solutions, as you're the ones doing your documentation in the end. Speaking only for myself, I'd rather prove we can produce beautiful documentation from lightweight markup for ourselves, and let others make their own conclusions about switching over or sticking with DocBook. > We have (and still are) put a lot of effort into our documentation and > we would like to keep the same level of quality. We are doing this because we (at least in the graphics community) also put a lot of effort into documentation, and we would like to make it *better*! I believe switching to some lightweight markup will be helpful in attracting more contributions to documentation. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- 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
Re: Kernel docs: muddying the waters a bit
Em Thu, 18 Feb 2016 10:24:04 +0100 Daniel Vetter escreveu: > On Thu, Feb 18, 2016 at 10:11 AM, Jani Nikula wrote: > > On Thu, 18 Feb 2016, Daniel Vetter wrote: > >> On Wed, Feb 17, 2016 at 11:14 PM, Jonathan Corbet wrote: > >>> On Sun, 14 Feb 2016 13:27:04 +0100 > >>> Daniel Vetter wrote: > >>> > One concern/open I have for pro/cons are the hyperlinks from kerneldoc > comments. Currently we have the postproc hack, iirc Jani's patches > generated links native when extracting the kerneldoc. What's the > solution with spinx? > >>> > >>> So I've been trying to figure out what this refers to. Is this the > >>> cross-reference links within the document? When I did my sphinx hack it > >>> used a technique that, shall we say, strongly resembles what Jani's > >>> patches did. One difference is that Sphinx has the concept of > >>> "functions" built into it, so I use function references for those. > >> > >> That's what I meant. As long as I can type in stuff like func(), > >> &struct and similar and get a link for it automatically (plus anywhere > >> else in the templated stuff for function headers) I'm really happy. > > > > I think that could be made to work in rst just as well as > > asciidoc. Which is to say, kernel-doc may generate broken refs in both, > > since it doesn't know if the link target exists outside of the > > file. Also, in theory, it's possible to generate non-unique targets in > > the end result if there are same named enums, structs, static functions > > etc. but I think that's less of a problem. Asciidoc just ignores these > > issues, I don't know what sphinx does. > > > > I think some of that could be alleviated by making the kernel-doc > > inclusion a directive through a sphinx extension. It could at the very > > least provide informative error messages. But that's distant future. > > > > Worth noting is that, AFAICT, in all of the proposals, including the > > original where kernel-doc produces docbook, this autoreferencing only > > works within parts processed by kernel-doc. Not in the template > > documents themselves. (You can still use the markup's more verbose cross > > referencing keywords.) > > It works everywhere, even in the docbook template, as long as you mark > it up correctly. Which in docbook means func. > That's because it's a post-proc path over the entire doc. But then the > entire point here is to move the overview sections all into kerneldoc, > so making the links in the templates more verbose shouldn't be a big > deal. For simple documents like the one produced by kernel-doc, I guess all markup languages would work equally. The problem is for complex documents like the media kAPI one, where the document was written to produce a book. So, it uses some complex features found at DocBook. One of such features we use extensively is the capability of having a table with per-line columns. This way, we can produce things like: V4L2_CID_COLOR_KILLER boolean Enable the color killer (i. e. force a black & white image in case of a weak video signal). V4L2_CID_COLORFXenumSelects a color effect. The following values are defined: V4L2_COLORFX_NONE Color effect is disabled. V4L2_COLORFX_ANTIQUEAn aging (old photo) effect. V4L2_COLORFX_ART_FREEZE Frost color effect. In the above example, we have a main 3 columns table, and we embed a 2 columns table at the third field of V4L2_CID_COLORFX to represent possible values for this menu control. See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the complete output of it. This is used extensively inside the media DocBook, and properly supporting it is one of our major concerns. Are there any way to represent those things with the markup languages currently being analyzed? Converting those tables will likely require manual work, as I don't think automatic tools will properly handle it, specially since we use some DocBook macros to help creating such tables. -- 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
Re: [PATCH] x86/intel/quark: Parameterize the kernel's IMR lock logic
On Thu, 2016-02-18 at 08:58 +0100, Ingo Molnar wrote: > So why not simply do the patch below? Very few people use boot > parameters, and the > complexity does not seem to be worth it. > > Furthermore I think an IMR range in itself is safe enough - it's not > like such > register state is going to be randomly corrupted, even with the > 'lock' bit unset. Hi Ingo. I agree - to flip the lock bit you need to be in ring-0 anyway. > So it's a perfectly fine protective measure against accidental memory > corruption > from the DMA space. It should not try to be more than that. > > And once we do this, I suggest we get rid of the 'lock' parameter > altogether - > that will further simplify the code. > > Thanks, > > Ingo That was the V1 of this patch https://groups.google.com/forum/#!topic/linux.kernel/6ZuVOF3TJow Andriy asked for the boot parameter to control the state of the IMR lock bit, I'm just as happy to go back to that version TBH -- 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
Re: V4L docs and docbook
On 02/18/16 11:19, Jani Nikula wrote: > On Thu, 18 Feb 2016, Hans Verkuil wrote: >> I looked at ReStructuredText and it looks like it will be a pain to convert >> the media DocBook code to that, and the main reason is the poor table >> support. >> The syntax for that looks very painful and the media DocBook is full of >> tables. > > The table support seems to be one point in favor of asciidoc over > reStructuredText [citation needed]. > >> BTW, my daily build scripts also rebuilds the media spec and it is available >> here: https://hverkuil.home.xs4all.nl/spec/media.html >> >> Also missing in ReStructuredText seems to be support for formulas (see for >> example the Colorspaces section in the spec), although to be fair standard >> DocBook doesn't do a great job at that either. > > This may be true for vanilla rst as supported by Python docutils, but > the Sphinx tool we're considering does support a lot of things through > extensions. The builtin extensions include support for rendering math > via PNG or javascript [1]. There's also support for embedded graphviz > [2] which may be of interest. > >> Now, I hate DocBook so going to something easier would certainly be nice, >> but I think it is going to be a difficult task. >> >> Someone would have to prove that going to another formatting tool will >> produce good results for our documentation. We can certainly give a few >> representative sections of our doc to someone to convert, and if that >> looks OK, then the full conversion can be done. > > It would be great to have you actively on board doing this yourself, > seeking the solutions, as you're the ones doing your documentation in > the end. > > Speaking only for myself, I'd rather prove we can produce beautiful > documentation from lightweight markup for ourselves, and let others make > their own conclusions about switching over or sticking with DocBook. > >> We have (and still are) put a lot of effort into our documentation and >> we would like to keep the same level of quality. > > We are doing this because we (at least in the graphics community) also > put a lot of effort into documentation, and we would like to make it > *better*! > > I believe switching to some lightweight markup will be helpful in > attracting more contributions to documentation. Just to be clear: I really don't like DocBook at all, so something better and easier would be very much appreciated. But good table handling is a prerequisite for us since we rely heavily on that. Regards, Hans -- 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
congratulation,:contect davidcar...@yahoo.com.hk
This is David and Carol Martin, We both won £33million lottery, we just commenced a Charity Donation by giving out 1,500,000.00 GBP to five (5) individuals; we listed you as a recipient of our cash donation of 1,500,000 GBP. get back to us for more with is email: davidcar...@yahoo.com.hk http://www.chroniclelive.co.uk/news/uk-news/33-million-lottery-winners-named-10726516 -- 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
Re: Kernel docs: muddying the waters a bit
On Thu, 18 Feb 2016, Mauro Carvalho Chehab wrote: > For simple documents like the one produced by kernel-doc, I guess > all markup languages would work equally. > > The problem is for complex documents like the media kAPI one, where > the document was written to produce a book. So, it uses some complex > features found at DocBook. One of such features we use extensively > is the capability of having a table with per-line columns. This way, > we can produce things like: > > V4L2_CID_COLOR_KILLER boolean Enable the color killer (i. e. force a black & > white image in case of a weak video signal). > V4L2_CID_COLORFX enumSelects a color effect. The following values > are defined: > V4L2_COLORFX_NONE Color effect is > disabled. > V4L2_COLORFX_ANTIQUEAn aging (old > photo) effect. > V4L2_COLORFX_ART_FREEZE Frost color > effect. > > In the above example, we have a main 3 columns table, and we embed > a 2 columns table at the third field of V4L2_CID_COLORFX to represent > possible values for this menu control. > > See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the > complete output of it. > > This is used extensively inside the media DocBook, and properly > supporting it is one of our major concerns. > > Are there any way to represent those things with the markup > languages currently being analyzed? > > Converting those tables will likely require manual work, as I don't > think automatic tools will properly handle it, specially since we > use some DocBook macros to help creating such tables. Since I've let myself be told that asciidoc handles tables better than reStructuredText, I tested this a bit with the presumably inferior one. rst has two table types, simple tables and grid tables [1]. It seems like grid tables can do pretty much anything, but they can be cumbersome to work with. So I tried to check what can be done with simple tables. Here's a sample, converted using rst2html (Sphinx will be prettier, but rst2html works for simple things like this): https://people.freedesktop.org/~jani/v4l-table-within-table.rst https://people.freedesktop.org/~jani/v4l-table-within-table.html Rather than using nested tables, you might want to consider using definition lists within tables: https://people.freedesktop.org/~jani/v4l-definition-list-within-table.rst https://people.freedesktop.org/~jani/v4l-definition-list-within-table.html You be the judge, but I think this is workable. BR, Jani. [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables -- Jani Nikula, Intel Open Source Technology Center -- 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
Re: Kernel docs: muddying the waters a bit
Em Thu, 18 Feb 2016 13:23:37 +0200 Jani Nikula escreveu: > On Thu, 18 Feb 2016, Mauro Carvalho Chehab wrote: > > For simple documents like the one produced by kernel-doc, I guess > > all markup languages would work equally. > > > > The problem is for complex documents like the media kAPI one, where > > the document was written to produce a book. So, it uses some complex > > features found at DocBook. One of such features we use extensively > > is the capability of having a table with per-line columns. This way, > > we can produce things like: > > > > V4L2_CID_COLOR_KILLER boolean Enable the color killer (i. e. force a > > black & white image in case of a weak video signal). > > V4L2_CID_COLORFXenumSelects a color effect. The following values > > are defined: > > V4L2_COLORFX_NONE Color effect is > > disabled. > > V4L2_COLORFX_ANTIQUEAn aging (old > > photo) effect. > > V4L2_COLORFX_ART_FREEZE Frost color > > effect. > > > > In the above example, we have a main 3 columns table, and we embed > > a 2 columns table at the third field of V4L2_CID_COLORFX to represent > > possible values for this menu control. > > > > See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the > > complete output of it. > > > > This is used extensively inside the media DocBook, and properly > > supporting it is one of our major concerns. > > > > Are there any way to represent those things with the markup > > languages currently being analyzed? > > > > Converting those tables will likely require manual work, as I don't > > think automatic tools will properly handle it, specially since we > > use some DocBook macros to help creating such tables. > > Since I've let myself be told that asciidoc handles tables better than > reStructuredText, I tested this a bit with the presumably inferior one. > > rst has two table types, simple tables and grid tables [1]. It seems > like grid tables can do pretty much anything, but they can be cumbersome > to work with. So I tried to check what can be done with simple tables. > > Here's a sample, converted using rst2html (Sphinx will be prettier, but > rst2html works for simple things like this): > > https://people.freedesktop.org/~jani/v4l-table-within-table.rst > https://people.freedesktop.org/~jani/v4l-table-within-table.html Yes, this would work. Can we remove the border from the main table? I guess it would be nicer. > > Rather than using nested tables, you might want to consider using > definition lists within tables: > > https://people.freedesktop.org/~jani/v4l-definition-list-within-table.rst > https://people.freedesktop.org/~jani/v4l-definition-list-within-table.html > > You be the judge, but I think this is workable. It is workable, but I guess nested tables produced a better result. I did myself a test with nested tables with asciidoc too: https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.html https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.ascii With looks very decent to me. I had to manually add the nested table, as pandoc conversion sent the DocBook's nested table to /dev/null. 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
Re: Kernel docs: muddying the waters a bit
On 02/18/16 13:04, Mauro Carvalho Chehab wrote: > Em Thu, 18 Feb 2016 13:23:37 +0200 > Jani Nikula escreveu: > >> On Thu, 18 Feb 2016, Mauro Carvalho Chehab wrote: >>> For simple documents like the one produced by kernel-doc, I guess >>> all markup languages would work equally. >>> >>> The problem is for complex documents like the media kAPI one, where >>> the document was written to produce a book. So, it uses some complex >>> features found at DocBook. One of such features we use extensively >>> is the capability of having a table with per-line columns. This way, >>> we can produce things like: >>> >>> V4L2_CID_COLOR_KILLER boolean Enable the color killer (i. e. force a >>> black & white image in case of a weak video signal). >>> V4L2_CID_COLORFXenumSelects a color effect. The following values >>> are defined: >>> V4L2_COLORFX_NONE Color effect is >>> disabled. >>> V4L2_COLORFX_ANTIQUEAn aging (old >>> photo) effect. >>> V4L2_COLORFX_ART_FREEZE Frost color >>> effect. >>> >>> In the above example, we have a main 3 columns table, and we embed >>> a 2 columns table at the third field of V4L2_CID_COLORFX to represent >>> possible values for this menu control. >>> >>> See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the >>> complete output of it. >>> >>> This is used extensively inside the media DocBook, and properly >>> supporting it is one of our major concerns. >>> >>> Are there any way to represent those things with the markup >>> languages currently being analyzed? >>> >>> Converting those tables will likely require manual work, as I don't >>> think automatic tools will properly handle it, specially since we >>> use some DocBook macros to help creating such tables. >> >> Since I've let myself be told that asciidoc handles tables better than >> reStructuredText, I tested this a bit with the presumably inferior one. >> >> rst has two table types, simple tables and grid tables [1]. It seems >> like grid tables can do pretty much anything, but they can be cumbersome >> to work with. So I tried to check what can be done with simple tables. >> >> Here's a sample, converted using rst2html (Sphinx will be prettier, but >> rst2html works for simple things like this): >> >> https://people.freedesktop.org/~jani/v4l-table-within-table.rst >> https://people.freedesktop.org/~jani/v4l-table-within-table.html > > Yes, this would work. Can we remove the border from the main table? > I guess it would be nicer. > >> >> Rather than using nested tables, you might want to consider using >> definition lists within tables: >> >> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.rst >> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.html >> >> You be the judge, but I think this is workable. > > It is workable, but I guess nested tables produced a better result. > > I did myself a test with nested tables with asciidoc too: > > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.html > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.ascii > > With looks very decent to me. It does, except for the vertical alignment of the third column (at least when viewed with google chrome). Hans > > I had to manually add the nested table, as pandoc conversion sent the > DocBook's nested table to /dev/null. > > 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
Re: Kernel docs: muddying the waters a bit
Em Thu, 18 Feb 2016 13:07:03 +0100 Hans Verkuil escreveu: > On 02/18/16 13:04, Mauro Carvalho Chehab wrote: > > Em Thu, 18 Feb 2016 13:23:37 +0200 > > Jani Nikula escreveu: > > > >> On Thu, 18 Feb 2016, Mauro Carvalho Chehab > >> wrote: > >>> For simple documents like the one produced by kernel-doc, I guess > >>> all markup languages would work equally. > >>> > >>> The problem is for complex documents like the media kAPI one, where > >>> the document was written to produce a book. So, it uses some complex > >>> features found at DocBook. One of such features we use extensively > >>> is the capability of having a table with per-line columns. This way, > >>> we can produce things like: > >>> > >>> V4L2_CID_COLOR_KILLER boolean Enable the color killer (i. e. force a > >>> black & white image in case of a weak video signal). > >>> V4L2_CID_COLORFX enumSelects a color effect. The following values > >>> are defined: > >>> V4L2_COLORFX_NONE Color effect is > >>> disabled. > >>> V4L2_COLORFX_ANTIQUEAn aging (old > >>> photo) effect. > >>> V4L2_COLORFX_ART_FREEZE Frost color > >>> effect. > >>> > >>> In the above example, we have a main 3 columns table, and we embed > >>> a 2 columns table at the third field of V4L2_CID_COLORFX to represent > >>> possible values for this menu control. > >>> > >>> See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the > >>> complete output of it. > >>> > >>> This is used extensively inside the media DocBook, and properly > >>> supporting it is one of our major concerns. > >>> > >>> Are there any way to represent those things with the markup > >>> languages currently being analyzed? > >>> > >>> Converting those tables will likely require manual work, as I don't > >>> think automatic tools will properly handle it, specially since we > >>> use some DocBook macros to help creating such tables. > >> > >> Since I've let myself be told that asciidoc handles tables better than > >> reStructuredText, I tested this a bit with the presumably inferior one. > >> > >> rst has two table types, simple tables and grid tables [1]. It seems > >> like grid tables can do pretty much anything, but they can be cumbersome > >> to work with. So I tried to check what can be done with simple tables. > >> > >> Here's a sample, converted using rst2html (Sphinx will be prettier, but > >> rst2html works for simple things like this): > >> > >> https://people.freedesktop.org/~jani/v4l-table-within-table.rst > >> https://people.freedesktop.org/~jani/v4l-table-within-table.html > > > > Yes, this would work. Can we remove the border from the main table? > > I guess it would be nicer. > > > >> > >> Rather than using nested tables, you might want to consider using > >> definition lists within tables: > >> > >> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.rst > >> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.html > >> > >> You be the judge, but I think this is workable. > > > > It is workable, but I guess nested tables produced a better result. > > > > I did myself a test with nested tables with asciidoc too: > > > > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.html > > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.ascii > > > > With looks very decent to me. > > It does, except for the vertical alignment of the third column (at least when > viewed > with google chrome). Not sure what you mean. Here, it looks fine on both Firefox and Chrome, except that the second colum size could be smaller. If this is what you're meaning this can be fixed by changing the second line from: [width="100%",cols="2,1,10a",options="header",frame="none", grid="none"] to: [width="100%",cols="3,1,30a",options="header",frame="none", grid="none"] With regards to ReStructured Text, I've no idea how to control the format of a table in order to do things like hiding the borders and changing the column spacing. So, at least on a first glance, asciidoc seems to fit better. 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
Re: Kernel docs: muddying the waters a bit
On Thu, 18 Feb 2016 10:24:04 +0100 Daniel Vetter wrote: > > Worth noting is that, AFAICT, in all of the proposals, including the > > original where kernel-doc produces docbook, this autoreferencing only > > works within parts processed by kernel-doc. Not in the template > > documents themselves. (You can still use the markup's more verbose cross > > referencing keywords.) > > It works everywhere, even in the docbook template, as long as you mark > it up correctly. Which in docbook means func. In Sphinx that's :func:`function_name`. Not a thing of beauty, but it works. jon -- 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
Re: Kernel docs: muddying the waters a bit
On Thu, 18 Feb 2016 10:44:34 -0200 Mauro Carvalho Chehab wrote: > > > It is workable, but I guess nested tables produced a better > > > result. > > > > > > I did myself a test with nested tables with asciidoc too: > > > > > > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.html > > > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.ascii > > > > > > With looks very decent to me. > > > > It does, except for the vertical alignment of the third column (at > > least when viewed with google chrome). > > Not sure what you mean. Here, it looks fine on both Firefox and > Chrome, except that the second colum size could be smaller. If this > is what you're meaning this can be fixed by changing the second line > from: I think Hans' problem (I see it as well) is coming from css-style of "paragraph" which is: margin-top: 0.5em; margin-bottom: 0.5em; This makes the third column non-vertical-aligned -- Patrick -- 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
Re: Kernel docs: muddying the waters a bit
On Thu, Feb 18, 2016 at 2:01 PM, Jonathan Corbet wrote: > On Thu, 18 Feb 2016 10:24:04 +0100 > Daniel Vetter wrote: > >> > Worth noting is that, AFAICT, in all of the proposals, including the >> > original where kernel-doc produces docbook, this autoreferencing only >> > works within parts processed by kernel-doc. Not in the template >> > documents themselves. (You can still use the markup's more verbose cross >> > referencing keywords.) >> >> It works everywhere, even in the docbook template, as long as you mark >> it up correctly. Which in docbook means func. > > In Sphinx that's :func:`function_name`. Not a thing of beauty, but it > works. Compared to function_name already an improvement. I can very much live with this ;-) -Daniel -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch -- 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
Re: [PATCH] add POWER Virtual Management Channel driver
On 2016-02-17 23:30, Stewart Smith wrote: Steven Royer writes: On 2016-02-17 16:31, Greg Kroah-Hartman wrote: On Wed, Feb 17, 2016 at 03:18:26PM -0600, Steven Royer wrote: On 2016-02-16 16:18, Greg Kroah-Hartman wrote: >On Tue, Feb 16, 2016 at 02:43:13PM -0600, Steven Royer wrote: >>From: Steven Royer >> >>The ibmvmc driver is a device driver for the POWER Virtual Management >>Channel virtual adapter on the PowerVM platform. It is used to >>communicate with the hypervisor for virtualization management. It >>provides both request/response and asynchronous message support through >>the /dev/ibmvmc node. > >What is the protocol for that device node? The protocol is not currently published. I am pushing on getting it published, but that process will take time. If you have a PowerVM system with NovaLink, it would not be hard to reverse engineer it... If you don't have a PowerVM system, then this driver isn't interesting anyway... Stephen - if you need some help pushing for it to be published, let me know, there's a few internal things I could help push. Thanks You can't just expect us to review this code without at least having a clue as to how it is supposed to work? There are two layers to the protocol. The first layer is the only layer that the driver actually cares about. The second layer is just a payload that is between the application and the hypervisor and can change independently from the kernel/driver (this is what is transported over the /dev/ibmvmc node). The first layer technically is published in the PAPR (appendix G), but it is not trivial for most people to access https://members.openpowerfoundation.org/document/dl/469 is LoPAPR which has been published through OpenPower Foundation and anyone can access, although Appendix G there is on EEH. Although VMC (Virtual Management Channel) is mentioned in that document the details aren't there... so it's possible that this is only in some other PAPR version :/ and... looking in internal places, it is. *sigh* With my OpenPower Foundation hat on, I'll say that it's a work-in-progress getting all this documentation in order. The questions of if it's a sensible hypervisor to partition interface and if it's a sensible userspace API are open for debate :) Would we implement this way of communicating between a KVM guest and the host linux system? If not, then it's probably not a generally good idea. That being said, it seems to be what already exists in PowerVM There is no "host" OS on PowerVM. The ibmvmc device makes it possible to emulate that behavior by picking one of the LPARs to be privileged. So this isn't really similar to a KVM guest talking to the KVM host. It's more like this Linux OS becomes the host. ibmvmc is the pipe that enables virtualization management software (i.e., OpenStack via NovaLink) to manage PowerVM: create/destroy/modify guests, etc... The why's and how's of NovaLink are described simply here: https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/Power%20Systems/page/Introducing%20PowerVM%20NovaLink -- 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
Re: [PATCH] x86/intel/quark: Parameterize the kernel's IMR lock logic
* Bryan O'Donoghue wrote: > On Thu, 2016-02-18 at 08:58 +0100, Ingo Molnar wrote: > > So why not simply do the patch below? Very few people use boot > > parameters, and the > > complexity does not seem to be worth it. > > > > Furthermore I think an IMR range in itself is safe enough - it's not > > like such > > register state is going to be randomly corrupted, even with the > > 'lock' bit unset. > > > Hi Ingo. > > I agree - to flip the lock bit you need to be in ring-0 anyway. > > > So it's a perfectly fine protective measure against accidental memory > > corruption > > from the DMA space. It should not try to be more than that. > > > > And once we do this, I suggest we get rid of the 'lock' parameter > > altogether - > > that will further simplify the code. > > > > Thanks, > > > > Ingo > > That was the V1 of this patch > > https://groups.google.com/forum/#!topic/linux.kernel/6ZuVOF3TJow heh ;-) > Andriy asked for the boot parameter to control the state of the IMR > lock bit, I'm just as happy to go back to that version TBH I really think it's over-engineered - especially considering that with the kernel lock-down removed there's no other IMR area that is really locked down - so we could get rid of the whole 'locked' logic that would simplify the code throughout. Yeah, it's a nice looking hardware feature - but I don't think it's particularly useful in terms of extra protection. Thanks, Ingo -- 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
Re: [PATCH 7/9] rfkill: Create "rfkill-airplane_mode" LED trigger
On Mon, 2016-02-08 at 10:41 -0500, João Paulo Rechi Vita wrote: > This creates a new LED trigger to be used by platform drivers as a > default trigger for airplane-mode indicator LEDs. > > By default this trigger will fire when RFKILL_OP_CHANGE_ALL is called > for all types (RFKILL_TYPE_ALL), setting the LED brightness to > LED_FULL > when the changing the state to blocked, and to LED_OFF when the > changing > the state to unblocked. In the future there will be a mechanism for > userspace to override the default policy, so it can implement its > own. > > This trigger will be used by the asus-wireless x86 platform driver. Just one comment - I think you should be consistent with the _ vs - and just use "rfkill-airplane-mode" as the name. johannes -- 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
Re: [PATCH 8/9] rfkill: Userspace control for airplane mode
Hi,
Sorry for the delay reviewing this.
On Mon, 2016-02-08 at 10:41 -0500, João Paulo Rechi Vita wrote:
> Provide an interface for the airplane-mode indicator be controlled
> from
> userspace. User has to first acquire the control through
> RFKILL_OP_AIRPLANE_MODE_ACQUIRE and keep the fd open for the whole
> time
> it wants to be in control of the indicator. Closing the fd or using
> RFKILL_OP_AIRPLANE_MODE_RELEASE restores the default policy.
I've come to the conclusion that the new ops are probably the best
thing to do here.
> +Userspace can also override the default airplane-mode indicator
> policy through
> +/dev/rfkill. Control of the airplane mode indicator has to be
> acquired first,
> +using RFKILL_OP_AIRPLANE_MODE_ACQUIRE, and is only available for one
> userspace
> +application at a time. Closing the fd or using
> RFKILL_OP_AIRPLANE_MODE_RELEASE
> +reverts the airplane-mode indicator back to the default kernel
> policy and makes
> +it available for other applications to take control. Changes to the
> +airplane-mode indicator state can be made using
> RFKILL_OP_AIRPLANE_MODE_CHANGE,
> +passing the new value in the 'soft' field of 'struct rfkill_event'.
I don't really see any value in _RELEASE, since an application can just
close the fd? I'd prefer not having the duplicate functionality
and force us to exercise the single code path every time.
> For further details consult Documentation/ABI/stable/sysfs-class-
> rfkill.
> diff --git a/include/uapi/linux/rfkill.h
> b/include/uapi/linux/rfkill.h
> index 2e00dce..9cb999b 100644
> --- a/include/uapi/linux/rfkill.h
> +++ b/include/uapi/linux/rfkill.h
> @@ -67,6 +67,9 @@ enum rfkill_operation {
> RFKILL_OP_DEL,
> RFKILL_OP_CHANGE,
> RFKILL_OP_CHANGE_ALL,
> + RFKILL_OP_AIRPLANE_MODE_ACQUIRE,
> + RFKILL_OP_AIRPLANE_MODE_RELEASE,
> + RFKILL_OP_AIRPLANE_MODE_CHANGE,
> };
> @@ -1199,7 +1202,7 @@ static ssize_t rfkill_fop_write(struct file
> *file, const char __user *buf,
> if (copy_from_user(&ev, buf, count))
> return -EFAULT;
>
> - if (ev.op != RFKILL_OP_CHANGE && ev.op !=
> RFKILL_OP_CHANGE_ALL)
> + if (ev.op < RFKILL_OP_CHANGE)
> return -EINVAL;
You need to also reject invalid high values, like 27.
> mutex_lock(&rfkill_global_mutex);
>
> + if (ev.op == RFKILL_OP_AIRPLANE_MODE_ACQUIRE) {
> + if (rfkill_apm_owned && !data->is_apm_owner) {
> + count = -EACCES;
> + } else {
> + rfkill_apm_owned = true;
> + data->is_apm_owner = true;
> + }
> + }
> +
> + if (ev.op == RFKILL_OP_AIRPLANE_MODE_RELEASE) {
It would probably be better to simply use "switch (ev.op)" and make the
default case do a reject.
> if (ev.op == RFKILL_OP_CHANGE_ALL)
> rfkill_update_global_state(ev.type, ev.soft);
Also moving the existing code inside the switch, of course.
johannes
--
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
Re: [PATCH] x86/intel/quark: Parameterize the kernel's IMR lock logic
On Thu, 2016-02-18 at 19:53 +0100, Ingo Molnar wrote: > * Bryan O'Donoghue wrote: > > > On Thu, 2016-02-18 at 08:58 +0100, Ingo Molnar wrote: > > > So why not simply do the patch below? Very few people use boot > > > parameters, and the > > > complexity does not seem to be worth it. > > > > > > Furthermore I think an IMR range in itself is safe enough - it's > > > not > > > like such > > > register state is going to be randomly corrupted, even with the > > > 'lock' bit unset. > > > > > > Hi Ingo. > > > > I agree - to flip the lock bit you need to be in ring-0 anyway. > > > > > So it's a perfectly fine protective measure against accidental > > > memory > > > corruption > > > from the DMA space. It should not try to be more than that. > > > > > > And once we do this, I suggest we get rid of the 'lock' parameter > > > altogether - > > > that will further simplify the code. > > > > > > Thanks, > > > > > > Ingo > > > > That was the V1 of this patch > > > > https://groups.google.com/forum/#!topic/linux.kernel/6ZuVOF3TJow > > heh ;-) :) > > Andriy asked for the boot parameter to control the state of the IMR > > lock bit, I'm just as happy to go back to that version TBH > > I really think it's over-engineered - especially considering that > with the kernel > lock-down removed there's no other IMR area that is really locked > down - so we > could get rid of the whole 'locked' logic that would simplify the > code throughout. I'm in favour of that too. Charitably I think locking a register like this makes sense only when you talk about it in a meeting room somewhere; as soon as you go to try to use it in a real situation you find its far more trouble than its really worth. So, I'm going to trim that out of this code unless I hear some pushback from elsewhere in the 1/2 day or so. > > Yeah, it's a nice looking hardware feature - but I don't think it's > particularly > useful in terms of extra protection. > > Thanks, > > Ingo -- 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
