Re: V4L docs and docbook

[Hans Verkuil]

Hi Jon,

On 02/17/2016 10:52 PM, Jonathan Corbet wrote:
> Hey, Mauro,
> 
> There's been a conversation going on that I keep meaning to bring you
> into.  In short, there's a fair amount of interest in improving our
> formatted kernel documentation, and, in particular, making it easier to
> write; I'd like to be sure that work doesn't leave media behind.
> 
> Work pushed by Daniel Vetter and company has been aiming toward the
> ability to use a lightweight markup language in the in-source kerneldoc
> comments.  Initially Markdown was targeted; the most likely choice now
> looks like ReStructuredText, though no decision has been made.  I've been
> pushing for moving all of our formatted documentation to whatever markup
> we use, leaving DocBook behind.  There are, I think, a lot of good
> reasons to want to do that, including consistency between the template
> files and the in-source comments, ease of authoring, and a less unwieldy
> toolchain.

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.

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.

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.

We have (and still are) put a lot of effort into our documentation and
we would like to keep the same level of quality.

Regards,

Hans

> 
> Various proof-of-concept patches have gone around showing that this idea
> seems to be feasible.  The latest discussion is at:
> 
>   http://thread.gmane.org/gmane.linux.documentation/35773
> 
> The media community has a lot of investment in DocBook documentation.
> Converting to another markup form is relatively easy, and it's something
> I would be willing to help with when the time comes.  But it occurred to
> me that I should probably ask what you all think of this.
> 
> There is no flag day here; there's no reason to rip out the current
> DocBook-based build infrastructure as long as somebody's using it.  But
> it would be nice to get rid of it eventually and work toward the creation
> of a more integrated set of kernel documentation.
> 
> So...is this an idea that fills you with horror, or does it maybe have
> some appeal?  Do you have any questions?
> 
> One other question I had for you was: which of the allegedly supported
> output formats are important to you?
> 
> Thanks,
> 
> jon
> --
> 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
> 

--
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

[Stewart Smith]

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.

>> 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

-- 
Stewart Smith
OPAL Architect, IBM.

--
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] Doc: nfs: Fix typos in Documentation/filesystems/nfs

[Randy Dunlap]

On 02/17/16 19:26, Masanari Iida wrote:
> This patch fix spelling typos found in Documentation/filesystems/nfs
> 
> Signed-off-by: Masanari Iida 
> ---
>  Documentation/filesystems/nfs/fault_injection.txt | 4 ++--
>  Documentation/filesystems/nfs/nfs-rdma.txt| 2 +-
>  Documentation/filesystems/nfs/nfsroot.txt | 2 +-
>  Documentation/filesystems/nfs/pnfs.txt| 6 +++---
>  Documentation/filesystems/nfs/rpc-server-gss.txt  | 2 +-
>  5 files changed, 8 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/filesystems/nfs/fault_injection.txt 
> b/Documentation/filesystems/nfs/fault_injection.txt
> index 426d166..f4ecb31 100644
> --- a/Documentation/filesystems/nfs/fault_injection.txt
> +++ b/Documentation/filesystems/nfs/fault_injection.txt
> @@ -49,13 +49,13 @@ forget_locks:
>  forget_delegations:
>   A delegation is used to assure the client that a file, or part of a 
> file,
>   has not changed since the delegation was awarded.  Clearing this list 
> will
> - force the client to reaquire its delegation before accessing the file
> + force the client to require its delegation before accessing the file
>   again.

reacquire

>  recall_delegations:
>   Delegations can be recalled by the server when another client attempts 
> to
>   access a file.  This test will notify the client that its delegation has
> - been revoked, forcing the client to reaquire the delegation before using
> + been revoked, forcing the client to require the delegation before using
>   the file again.

reacquire


-- 
~Randy
--
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

[PATCH] Doc: nfs: Fix typos in Documentation/filesystems/nfs

[Masanari Iida]

This patch fix spelling typos found in Documentation/filesystems/nfs

Signed-off-by: Masanari Iida 
---
 Documentation/filesystems/nfs/fault_injection.txt | 4 ++--
 Documentation/filesystems/nfs/nfs-rdma.txt| 2 +-
 Documentation/filesystems/nfs/nfsroot.txt | 2 +-
 Documentation/filesystems/nfs/pnfs.txt| 6 +++---
 Documentation/filesystems/nfs/rpc-server-gss.txt  | 2 +-
 5 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/filesystems/nfs/fault_injection.txt 
b/Documentation/filesystems/nfs/fault_injection.txt
index 426d166..f4ecb31 100644
--- a/Documentation/filesystems/nfs/fault_injection.txt
+++ b/Documentation/filesystems/nfs/fault_injection.txt
@@ -49,13 +49,13 @@ forget_locks:
 forget_delegations:
  A delegation is used to assure the client that a file, or part of a file,
  has not changed since the delegation was awarded.  Clearing this list will
- force the client to reaquire its delegation before accessing the file
+ force the client to require its delegation before accessing the file
  again.
 
 recall_delegations:
  Delegations can be recalled by the server when another client attempts to
  access a file.  This test will notify the client that its delegation has
- been revoked, forcing the client to reaquire the delegation before using
+ been revoked, forcing the client to require the delegation before using
  the file again.
 
 
diff --git a/Documentation/filesystems/nfs/nfs-rdma.txt 
b/Documentation/filesystems/nfs/nfs-rdma.txt
index 906b6c2..1e65645 100644
--- a/Documentation/filesystems/nfs/nfs-rdma.txt
+++ b/Documentation/filesystems/nfs/nfs-rdma.txt
@@ -218,7 +218,7 @@ NFS/RDMA Setup
 /vol0   192.168.0.0/255.255.255.0(fsid=0,rw,async,insecure,no_root_squash)
 
 The IP address(es) is(are) the client's IPoIB address for an InfiniBand
-HCA or the cleint's iWARP address(es) for an RNIC.
+HCA or the client's iWARP address(es) for an RNIC.
 
 NOTE: The "insecure" option must be used because the NFS/RDMA client does
 not use a reserved port.
diff --git a/Documentation/filesystems/nfs/nfsroot.txt 
b/Documentation/filesystems/nfs/nfsroot.txt
index bb5ab6d..0b2883b 100644
--- a/Documentation/filesystems/nfs/nfsroot.txt
+++ b/Documentation/filesystems/nfs/nfsroot.txt
@@ -166,7 +166,7 @@ 
ip=:::
Value gets exported by /proc/net/pnp which is often linked
on embedded systems by /etc/resolv.conf.
 
-  IP address of secound nameserver.
+  IP address of second nameserver.
Same as above.
 
 
diff --git a/Documentation/filesystems/nfs/pnfs.txt 
b/Documentation/filesystems/nfs/pnfs.txt
index 44a9f24..8de578a 100644
--- a/Documentation/filesystems/nfs/pnfs.txt
+++ b/Documentation/filesystems/nfs/pnfs.txt
@@ -64,8 +64,8 @@ table which are called by the nfs-client pnfs-core to 
implement the
 different layout types.
 
 Files-layout-driver code is in: fs/nfs/filelayout/.. directory
-Objects-layout-deriver code is in: fs/nfs/objlayout/.. directory
-Blocks-layout-deriver code is in: fs/nfs/blocklayout/.. directory
+Objects-layout-driver code is in: fs/nfs/objlayout/.. directory
+Blocks-layout-driver code is in: fs/nfs/blocklayout/.. directory
 Flexfiles-layout-driver code is in: fs/nfs/flexfilelayout/.. directory
 
 objects-layout setup
@@ -91,7 +91,7 @@ The API to the login script is as follows:
Usage: $0 -u  -o  -s 
Options:
-u  target uri e.g. iscsi://:
-   (allways exists)
+   (always exists)
(More protocols can be defined in the future.
 The client does not interpret this string it is
 passed unchanged as received from the Server)
diff --git a/Documentation/filesystems/nfs/rpc-server-gss.txt 
b/Documentation/filesystems/nfs/rpc-server-gss.txt
index 716f4be..310bbba 100644
--- a/Documentation/filesystems/nfs/rpc-server-gss.txt
+++ b/Documentation/filesystems/nfs/rpc-server-gss.txt
@@ -57,7 +57,7 @@ the Kerberos tickets, that needs to be sent through the GSS 
layer in
 order to perform context establishment.
 
 B) It does not properly handle creds where the user is member of more
-than a few housand groups (the current hard limit in the kernel is 65K
+than a few thousand groups (the current hard limit in the kernel is 65K
 groups) due to limitation on the size of the buffer that can be send
 back to the kernel (4KiB).
 
-- 
2.7.1.339.g0233b80

--
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

[Mauro Carvalho Chehab]

Hi Jon,

Em Wed, 17 Feb 2016 14:52:54 -0700
Jonathan Corbet  escreveu:

> Hey, Mauro,
> 
> There's been a conversation going on that I keep meaning to bring you
> into.  In short, there's a fair amount of interest in improving our
> formatted kernel documentation, and, in particular, making it easier to
> write; I'd like to be sure that work doesn't leave media behind.
> 
> Work pushed by Daniel Vetter and company has been aiming toward the
> ability to use a lightweight markup language in the in-source kerneldoc
> comments.  Initially Markdown was targeted; the most likely choice now
> looks like ReStructuredText, though no decision has been made.  I've been
> pushing for moving all of our formatted documentation to whatever markup
> we use, leaving DocBook behind.  There are, I think, a lot of good
> reasons to want to do that, including consistency between the template
> files and the in-source comments, ease of authoring, and a less unwieldy
> toolchain.
> 
> Various proof-of-concept patches have gone around showing that this idea
> seems to be feasible.  The latest discussion is at:
> 
>   http://thread.gmane.org/gmane.linux.documentation/35773
> 
> The media community has a lot of investment in DocBook documentation.
> Converting to another markup form is relatively easy, and it's something
> I would be willing to help with when the time comes.  But it occurred to
> me that I should probably ask what you all think of this.
> 
> There is no flag day here; there's no reason to rip out the current
> DocBook-based build infrastructure as long as somebody's using it.  But
> it would be nice to get rid of it eventually and work toward the creation
> of a more integrated set of kernel documentation.
> 
> So...is this an idea that fills you with horror, or does it maybe have
> some appeal?  Do you have any questions?

As you can see at:
https://linuxtv.org/docs.php

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

The kAPI uses kernel-doc. I believe it should be easy to convert and/or
add markup tags there to improve it. Actually, this is one of the things
we currently miss. So, anything to improve it will be very welcomed.

The uAPI is a different story. What we have there is a join of two
different documents:
- The V4L2 documentation, written directly in DocBook
- The DVB API documentation, written originally in LaTex and later
  migrated to DocBook.

Such documentation uses extensive usage of the DocBook features,
so, I think it won't be trivial to convert it.

In addition, we have some scripts embedded at the DocBook/media
Makefile that create cross-references between the public API
headers and the DocBook, warning us if some new ioctl, define,
enum, ... was created without the corresponding documentation.

While not perfect, those scripts help a lot for us to be sure that
no uAPI changes would reach upstream without the corresponding
documentation. They work by parsing the uapi/*.h files we use and
adding references to (almost) every data type there. As those
headers are included at the documentation as appendices, DocBook
generation with xmllint will check if all references exist and will
produce an alert if something is missing. I even run xmllint manually
to make it pedantic, using the script below:

make cleanmediadocs
make DOCBOOKS=media_api.xml htmldocs 2>&1 | grep -v "element.*: 
validity error : ID .* already defined"
echo
echo "Do some pedantic checks and generate DocBook/media/media_api.html 
without chunks"
echo
xmllint --noent --postvalid "$PWD/Documentation/DocBook/media_api.xml" 
>/tmp/x.xml 2>/dev/null
xmllint --noent --postvalid --noout /tmp/x.xml
xmlto html-nochunks -m ./Documentation/DocBook/stylesheet.xsl -o 
Documentation/DocBook/media Documentation/DocBook/media_api.

I run the above script every time a patch touches on one of the public
API headers, as part of my reviewing process.

I believe that porting it to whatever other documentation system we
decide would be painful and would require a lot of effort.

Also, as we're touching the documentation on almost all Kernel versions, 
such porting effort should happen quickly, as otherwise it would either
prevent us from adding new features at the subsystem, or we would need to
keep 2 copies of the documentation, and the ones porting it would have to
port later the new additions.

So, I guess we'll likely need to postpone converting the uAPI document
until we can find someone with time and knowledge to do it quicky.

> One other question I had for you was: which of the allegedly supported
> output formats are important to you?

The most important format is html, on both on multiple docs, like the one
hosted at 

Re: [PATCH] add POWER Virtual Management Channel driver

[Steven Royer]

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...


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 
online.  I'll put together some documentation that describes that first 
layer of the protocol in my next revision of the patch.  In many 
respects, the interface between driver and hypervisor is similar to 
ibmvscsi.  Both are CRQ based devices.  ibmvmc is actually a little 
closer to the old ibmvstgt driver since it is a CRQ server device.



>Where is the documentation here?  Why does this have to be a character
>device?  Why can't it fit in with other drivers of this type?
This is a character device for historical reasons.  The short version 
is
that this driver is a clean-room rewrite of an AIX driver which made 
it a
character device.  The user space application was ported from AIX to 
Linux
and it is convenient to have the AIX and Linux drivers match behavior 
where

possible.


Note that we don't let random userspace applications dictate kernel api
decisions, please make the best choice for this interface without being
influenced by AIX.
That is fair.  I actually started down the path of using a block 
interface early on, and I ran into some complications that made it seem 
less desirable than character.  Specifically the interface has variable 
length messages from 32 bytes to 4kb (mostly closer to 32 bytes than 4kb 
per message) and I was worried about overhead of dealing with all the 
zeros in the majority of the messages.  I've never made a block 
interface before and it's entirely possible (likely) I missed something 
obvious.  I'll revisit before I post the next revision.



>>+/*
>>+ * IBM Power Systems Virtual Management Channel Support.
>>+ *
>>+ * Copyright (c) 2004, 2016 IBM Corp.
>>+ *   Dave Engebretsen engeb...@us.ibm.com
>>+ *   Steven Royer sero...@linux.vnet.ibm.com
>>+ *   Adam Reznechek adrez...@linux.vnet.ibm.com
>>+ *
>>+ * This program is free software; you can redistribute it and/or
>>+ * modify it under the terms of the GNU General Public License
>>+ * as published by the Free Software Foundation; either version 2
>>+ * of the License, or (at your option) any later version.
>
>I have to ask, but do you really mean "or any later version"?
This actually matches closely to other similar PowerVM virtual device
drivers, like ibmvscsi or ibmveth.


That did not answer the question, picking a license in a cargo-cult
manner is not a wise decision :(
This is boilerplate for IBM provided PowerVM drivers.  So yes, I did 
mean this.


--
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

[Greg Kroah-Hartman]

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...

You can't just expect us to review this code without at least having a
clue as to how it is supposed to work?

> >Where is the documentation here?  Why does this have to be a character
> >device?  Why can't it fit in with other drivers of this type?
> This is a character device for historical reasons.  The short version is
> that this driver is a clean-room rewrite of an AIX driver which made it a
> character device.  The user space application was ported from AIX to Linux
> and it is convenient to have the AIX and Linux drivers match behavior where
> possible.

Note that we don't let random userspace applications dictate kernel api
decisions, please make the best choice for this interface without being
influenced by AIX.

> >>+/*
> >>+ * IBM Power Systems Virtual Management Channel Support.
> >>+ *
> >>+ * Copyright (c) 2004, 2016 IBM Corp.
> >>+ *   Dave Engebretsen engeb...@us.ibm.com
> >>+ *   Steven Royer sero...@linux.vnet.ibm.com
> >>+ *   Adam Reznechek adrez...@linux.vnet.ibm.com
> >>+ *
> >>+ * This program is free software; you can redistribute it and/or
> >>+ * modify it under the terms of the GNU General Public License
> >>+ * as published by the Free Software Foundation; either version 2
> >>+ * of the License, or (at your option) any later version.
> >
> >I have to ask, but do you really mean "or any later version"?
> This actually matches closely to other similar PowerVM virtual device
> drivers, like ibmvscsi or ibmveth.

That did not answer the question, picking a license in a cargo-cult
manner is not a wise decision :(

--
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

[Daniel Vetter]

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(),
 and similar and get a link for it automatically (plus anywhere
else in the templated stuff for function headers) I'm really happy.
-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

V4L docs and docbook

[Jonathan Corbet]

Hey, Mauro,

There's been a conversation going on that I keep meaning to bring you
into.  In short, there's a fair amount of interest in improving our
formatted kernel documentation, and, in particular, making it easier to
write; I'd like to be sure that work doesn't leave media behind.

Work pushed by Daniel Vetter and company has been aiming toward the
ability to use a lightweight markup language in the in-source kerneldoc
comments.  Initially Markdown was targeted; the most likely choice now
looks like ReStructuredText, though no decision has been made.  I've been
pushing for moving all of our formatted documentation to whatever markup
we use, leaving DocBook behind.  There are, I think, a lot of good
reasons to want to do that, including consistency between the template
files and the in-source comments, ease of authoring, and a less unwieldy
toolchain.

Various proof-of-concept patches have gone around showing that this idea
seems to be feasible.  The latest discussion is at:

http://thread.gmane.org/gmane.linux.documentation/35773

The media community has a lot of investment in DocBook documentation.
Converting to another markup form is relatively easy, and it's something
I would be willing to help with when the time comes.  But it occurred to
me that I should probably ask what you all think of this.

There is no flag day here; there's no reason to rip out the current
DocBook-based build infrastructure as long as somebody's using it.  But
it would be nice to get rid of it eventually and work toward the creation
of a more integrated set of kernel documentation.

So...is this an idea that fills you with horror, or does it maybe have
some appeal?  Do you have any questions?

One other question I had for you was: which of the allegedly supported
output formats are important to you?

Thanks,

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: [PATCH] add POWER Virtual Management Channel driver

[Steven Royer]

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...


Where is the documentation here?  Why does this have to be a character
device?  Why can't it fit in with other drivers of this type?
This is a character device for historical reasons.  The short version is 
that this driver is a clean-room rewrite of an AIX driver which made it 
a character device.  The user space application was ported from AIX to 
Linux and it is convenient to have the AIX and Linux drivers match 
behavior where possible.




Signed-off-by: Steven Royer 
---
This is used by the PowerVM NovaLink project.  You can see development 
history on github:

https://github.com/powervm/ibmvmc

 Documentation/ioctl/ioctl-number.txt |1 +
 MAINTAINERS  |5 +
 arch/powerpc/include/asm/hvcall.h|3 +-
 drivers/misc/Kconfig |9 +
 drivers/misc/Makefile|1 +
 drivers/misc/ibmvmc.c| 1882 
++

 drivers/misc/ibmvmc.h|  203 
 7 files changed, 2103 insertions(+), 1 deletion(-)
 create mode 100644 drivers/misc/ibmvmc.c
 create mode 100644 drivers/misc/ibmvmc.h

diff --git a/Documentation/ioctl/ioctl-number.txt 
b/Documentation/ioctl/ioctl-number.txt

index 91261a3..d5f5f4f 100644
--- a/Documentation/ioctl/ioctl-number.txt
+++ b/Documentation/ioctl/ioctl-number.txt
@@ -324,6 +324,7 @@ Code  Seq#(hex) Include FileComments
 0xCA   80-8F   uapi/scsi/cxlflash_ioctl.h
 0xCB   00-1F   CBM serial IEC bus  in development:


+0xCC   00-0F   drivers/misc/ibmvmc.h   pseries VMC driver
 0xCD   01  linux/reiserfs_fs.h
 0xCF   02  fs/cifs/ioctl.c
 0xDB   00-0F   drivers/char/mwave/mwavepub.h
diff --git a/MAINTAINERS b/MAINTAINERS
index cc2f753..c39dca2 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -5353,6 +5353,11 @@ L:   net...@vger.kernel.org
 S: Supported
 F: drivers/net/ethernet/ibm/ibmvnic.*

+IBM Power Virtual Management Channel Driver
+M: Steven Royer 
+S: Supported
+F: drivers/misc/ibmvmc.*
+
 IBM Power Virtual SCSI Device Drivers
 M: Tyrel Datwyler 
 L: linux-s...@vger.kernel.org
diff --git a/arch/powerpc/include/asm/hvcall.h 
b/arch/powerpc/include/asm/hvcall.h

index e3b54dd..1ee6f2b 100644
--- a/arch/powerpc/include/asm/hvcall.h
+++ b/arch/powerpc/include/asm/hvcall.h
@@ -274,7 +274,8 @@
 #define H_COP  0x304
 #define H_GET_MPP_X0x314
 #define H_SET_MODE 0x31C
-#define MAX_HCALL_OPCODE   H_SET_MODE
+#define H_REQUEST_VMC  0x360
+#define MAX_HCALL_OPCODE   H_REQUEST_VMC

 /* H_VIOCTL functions */
 #define H_GET_VIOA_DUMP_SIZE   0x01
diff --git a/drivers/misc/Kconfig b/drivers/misc/Kconfig
index 054fc10..f8d9113 100644
--- a/drivers/misc/Kconfig
+++ b/drivers/misc/Kconfig
@@ -526,6 +526,15 @@ config VEXPRESS_SYSCFG
  bus. System Configuration interface is one of the possible means
  of generating transactions on this bus.

+config IBMVMC
+   tristate "IBM Virtual Management Channel support"
+   depends on PPC_PSERIES
+   help
+ This is the IBM POWER Virtual Management Channel
+
+ To compile this driver as a module, choose M here: the
+ module will be called ibmvmc.
+
 source "drivers/misc/c2port/Kconfig"
 source "drivers/misc/eeprom/Kconfig"
 source "drivers/misc/cb710/Kconfig"
diff --git a/drivers/misc/Makefile b/drivers/misc/Makefile
index 537d7f3..08336b3 100644
--- a/drivers/misc/Makefile
+++ b/drivers/misc/Makefile
@@ -56,3 +56,4 @@ obj-$(CONFIG_GENWQE)  += genwqe/
 obj-$(CONFIG_ECHO) += echo/
 obj-$(CONFIG_VEXPRESS_SYSCFG)  += vexpress-syscfg.o
 obj-$(CONFIG_CXL_BASE) += cxl/
+obj-$(CONFIG_IBMVMC)   += ibmvmc.o
diff --git a/drivers/misc/ibmvmc.c b/drivers/misc/ibmvmc.c
new file mode 100644
index 000..fb943b7
--- /dev/null
+++ b/drivers/misc/ibmvmc.c
@@ -0,0 +1,1882 @@
+/*
+ * IBM Power Systems Virtual Management Channel Support.
+ *
+ * Copyright (c) 2004, 2016 IBM Corp.
+ *   Dave Engebretsen engeb...@us.ibm.com
+ *   Steven 

Re: [PATCH] Documentation/ko_KR: update maintainer information

[Jonathan Corbet]

On Sun, 14 Feb 2016 11:51:23 +0900
SeongJae Park  wrote:

> Maintainer informations of Documentation/ko_KR is outdated. This commit
> update the informations to the latest ones.

Applied to the docs tree, thanks.

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: [PATCH v2] Documentation: Chinese translation of arm64/silicon-errata.txt

[Jonathan Corbet]

On Tue, 16 Feb 2016 16:40:39 +0800
w...@redhat.com wrote:

> This is a Chinese translated version of Documentation/arm64/silicon-errata.txt

Applied to the docs tree, thanks.

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