Re: [PATCH bpf-next 00/17] Improve BPF syscall command documentation
Joe Stringer writes: > Hey Jon, thanks for the feedback. Absolutely, what you say makes > sense. The intent here wasn't to come up with something new. Based on > your prompt from this email (and a quick look at your KR '19 > presentation), I'm hearing a few observations: > * Storing the documentation in the code next to the things that > contributors edit is a reasonable approach to documentation of this > kind. Yes. At least, it's what we do for a lot of our other documentation in the kernel. The assumption is that it will encourage developers to keep the docs current; in my experience that's somewhat optimistic, but optimism is good...:) > * This series currently proposes adding some new Makefile > infrastructure. However, good use of the "kernel-doc" sphinx directive > + "DOC: " incantations in the header should be able to achieve the > same without adding such dedicated build system logic to the tree. If it can, I would certainly prefer to see it used - or extended, if need be, to meet your needs. > * The changes in patch 16 here extended Documentation/bpf/index.rst, > but to assist in improving the overall kernel documentation > organisation / hierarchy, you would prefer to instead introduce a > dedicated Documentation/userspace-api/bpf/ directory where the bpf > uAPI portions can be documented. An objective I've been working on for some years is reorienting the documentation with a focus on who the readers are. We've tended to organize it by subsystem, requiring people to wade through a lot of stuff that isn't useful to them. So yes, my preference would be to document the kernel's user-space API in the relevant manual. That said, I do tend to get pushback here at times, and the BPF API is arguably a bit different that much of the rest. So while the above preference exists and is reasonably strong, the higher priority is to get good, current documentation in *somewhere* so that it's available to users. I don't want to make life too difficult for people working toward that goal, even if I would paint it a different color. > In addition to this, today the bpf helpers documentation is built > through the bpftool build process as well as the runtime bpf > selftests, mostly as a way to ensure that the API documentation > conforms to a particular style, which then assists with the generation > of ReStructured Text and troff output. I can probably simplify the > make infrastructure involved in triggering the bpf docs build for bpf > subsystem developers and maintainers. I think there's likely still > interest from bpf folks to keep that particular dependency in the > selftests like today and even extend it to include this new > Documentation, so that we don't either introduce text that fails > against the parser or in some other way break the parser. Whether that > validation is done by scripts/kernel-doc or scripts/bpf_helpers_doc.py > doesn't make a big difference to me, other than I have zero experience > with Perl. My first impressions are that the bpf_helpers_doc.py is > providing stricter formatting requirements than what "DOC: " + > kernel-doc would provide, so my baseline inclination would be to keep > those patches to enhance that script and use that for the validation > side (help developers with stronger linting feedback), then use > kernel-doc for the actual html docs generation side, which would help > to satisfy your concern around duplication of the documentation build > systems. This doesn't sound entirely unreasonable. I wonder if the BPF helper could be built into an sphinx extension to make it easy to pull that information into the docs build. The advantage there is that it can be done in Python :) Looking forward to the next set. Thanks, jon
Re: [PATCH bpf-next 00/17] Improve BPF syscall command documentation
[CC += linux-doc] Joe Stringer writes: > From: Joe Stringer > > The state of bpf(2) manual pages today is not exactly ideal. For the > most part, it was written several years ago and has not kept up with the > pace of development in the kernel tree. For instance, out of a total of > ~35 commands to the BPF syscall available today, when I pull the > kernel-man-pages tree today I find just 6 documented commands: The very > basics of map interaction and program load. > > In contrast, looking at bpf-helpers(7), I am able today to run one > command[0] to fetch API documentation of the very latest eBPF helpers > that have been added to the kernel. This documentation is up to date > because kernel maintainers enforce documenting the APIs as part of > the feature submission process. As far as I can tell, we rely on manual > synchronization from the kernel tree to the kernel-man-pages tree to > distribute these more widely, so all locations may not be completely up > to date. That said, the documentation does in fact exist in the first > place which is a major initial hurdle to overcome. > > Given the relative success of the process around bpf-helpers(7) to > encourage developers to document their user-facing changes, in this > patch series I explore applying this technique to bpf(2) as well. So I am totally in favor of improving the BPF docs, this is great work. That said, I am a bit less thrilled about creating a new, parallel documentation-build system in the kernel. I don't think that BPF is so special that it needs to do its own thing here. In particular, I would love to have the bpf() syscall API information incorporated into the userspace-api book with all the rest of the user-space API docs. That could be done now by formatting your information as a DOC: block. If you started that way, you'd get the whole existing build system for free. You would also have started down a path that could, some bright shining day, lead to this kind of documentation for *all* of our system calls. That would be a huge improvement in how we do things. The troff output would still need implementation, but we'd like to have that anyway. We used to create man pages for internal kernel APIs; that was lost in the sphinx transition and hasn't been a priority since people haven't been screaming, but it could still be nice to have it back. So...could I ask you to have a look at doing this within the kernel's docs system instead of in addition to it? Even if it means digging into scripts/kernel-doc, which isn't all that high on my list of Fun Things To Do either? I'm willing to try to help, and maybe we can get some other assistance too - I'm ever the optimist. Thanks, jon
Re: [PATCH v6 00/16] Fix several bad kernel-doc markups
On Thu, 14 Jan 2021 09:04:36 +0100 Mauro Carvalho Chehab wrote: > 1) 10 remaining fixup patches from the series I sent back on Dec, 1st: > >parport: fix a kernel-doc markup >rapidio: fix kernel-doc a markup >fs: fix kernel-doc markups >pstore/zone: fix a kernel-doc markup >firmware: stratix10-svc: fix kernel-doc markups >connector: fix a kernel-doc markup >lib/crc7: fix a kernel-doc markup >memblock: fix kernel-doc markups >w1: fix a kernel-doc markup >selftests: kselftest_harness.h: partially fix kernel-doc markups A week later none of these have shown up in linux-next, so I went ahead and applied the set. Thanks, jon
Re: [RFC v3 08/11] vduse: Introduce VDUSE - vDPA Device in Userspace
On Tue, 19 Jan 2021 13:07:53 +0800 Xie Yongji wrote: > diff --git a/Documentation/driver-api/vduse.rst > b/Documentation/driver-api/vduse.rst > new file mode 100644 > index ..9418a7f6646b > --- /dev/null > +++ b/Documentation/driver-api/vduse.rst > @@ -0,0 +1,85 @@ > +== > +VDUSE - "vDPA Device in Userspace" > +== Thanks for documenting this feature! You will, though, need to add this new document to Documentation/driver-api/index.rst for it to be included in the docs build. That said, this would appear to be documentation for user space, right? So the userspace-api manual is probably a more appropriate place for it. Thanks, jon
Re: [PATCH 0/3] Fix Kernel-doc warnings introduced on next-20200921
On Tue, 22 Sep 2020 20:52:06 +0300 Ville Syrjälä wrote: > Mea culpa. My doc test build was foiled by the sphinx 2 vs. 3 > regression and I was too lazy to start downgrading things. > Any ETA for getting that fixed btw? There's a fix of sorts in docs-next (and thus linux-next) now, has been there for a few weeks. Really fixing that problem properly requires more time than anybody seems to have at the moment. jon
Re: [PATCH] docs: bpf/ringbuf.rst: fix reference to nonexistent document
On Sat, 18 Jul 2020 13:51:01 -0300 "Daniel W. S. Almeida" wrote: > Fix the following warnings: > > ringbuf.rst:197: WARNING: Unknown target name: "bench_ringbuf.c" > > There was no target defined for 'bench_ringbuf.c'. Also, the > syntax used was wrong, in the sense that it would not highlight > the entire path in the browser. > > Signed-off-by: Daniel W. S. Almeida > --- > Documentation/bpf/ringbuf.rst | 5 - > 1 file changed, 4 insertions(+), 1 deletion(-) > > diff --git a/Documentation/bpf/ringbuf.rst b/Documentation/bpf/ringbuf.rst > index 75f943f0009df..8e7c15a927740 100644 > --- a/Documentation/bpf/ringbuf.rst > +++ b/Documentation/bpf/ringbuf.rst > @@ -200,10 +200,13 @@ a self-pacing notifications of new data being > availability. > being available after commit only if consumer has already caught up right up > to > the record being committed. If not, consumer still has to catch up and thus > will see new data anyways without needing an extra poll notification. > -Benchmarks (see tools/testing/selftests/bpf/benchs/bench_ringbuf.c_) show > that > +Benchmarks (see `tools/testing/selftests/bpf/benchs/bench_ringbufs.c`_) show > that > this allows to achieve a very high throughput without having to resort to But this still doesn't lead to anything useful, right? That file is not part of the documentation... It seems better just to take out the "_"... Thanks, jon
Re: [PATCH] docs: core-api/printk-formats.rst: use literal block syntax
On Sat, 18 Jul 2020 13:51:02 -0300 "Daniel W. S. Almeida" wrote: > Fix the following warning: > > WARNING: Definition list ends without a blank line; > unexpected unindent. > > By switching to the literal block syntax. > > Signed-off-by: Daniel W. S. Almeida > --- > Documentation/core-api/printk-formats.rst | 4 +++- > 1 file changed, 3 insertions(+), 1 deletion(-) > > diff --git a/Documentation/core-api/printk-formats.rst > b/Documentation/core-api/printk-formats.rst > index 1beac4719e437..6d26c5c6ac485 100644 > --- a/Documentation/core-api/printk-formats.rst > +++ b/Documentation/core-api/printk-formats.rst > @@ -494,9 +494,11 @@ Time and date > %pt[RT]tHH:MM:SS > %pt[RT][dt][r] > > -For printing date and time as represented by > +For printing date and time as represented by:: > + > R struct rtc_time structure > T time64_t type > + > in human readable format. Applied, thanks. jon
Re: [PATCH] docs: bpf/bpf_devel_QA.rst: fix reference to nonexistent document
On Sat, 18 Jul 2020 13:51:00 -0300 "Daniel W. S. Almeida" wrote: > Fix the following sphinx warning: > > bpf_devel_QA.rst:444: WARNING: Unknown target name: > "documentation/bpf/btf.rst" > > No target was defined for 'btf.rst' in the document. Fix it. > > Signed-off-by: Daniel W. S. Almeida > --- > Documentation/bpf/bpf_devel_QA.rst | 1 + > 1 file changed, 1 insertion(+) > > diff --git a/Documentation/bpf/bpf_devel_QA.rst > b/Documentation/bpf/bpf_devel_QA.rst > index 0b3db91dc1002..a26aa1b9b2595 100644 > --- a/Documentation/bpf/bpf_devel_QA.rst > +++ b/Documentation/bpf/bpf_devel_QA.rst > @@ -643,5 +643,6 @@ when: > .. _selftests: ../../tools/testing/selftests/bpf/ > .. _Documentation/dev-tools/kselftest.rst: > https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html > +.. _Documentation/bpf/btf.rst: btf.rst Applied, thanks. jon
Re: [PATCH] docs: bpf/index.rst: Add ringbuf.rst
On Sat, 18 Jul 2020 13:51:04 -0300 "Daniel W. S. Almeida" wrote: > From: Daniel W. S. Almeida > > Fix the following warning > > Documentation/bpf/ringbuf.rst: WARNING: document isn't > included in any toctree > > By adding it to the index. > > Signed-off-by: Daniel W. S. Almeida > --- > Documentation/bpf/index.rst | 8 > 1 file changed, 8 insertions(+) > > diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst > index 38b4db8be7a2b..0f60b95e83c40 100644 > --- a/Documentation/bpf/index.rst > +++ b/Documentation/bpf/index.rst > @@ -58,6 +58,14 @@ Testing and debugging BPF > s390 > > > +Other > += > + > +.. toctree:: > + :maxdepth: 1 > + > + ringbuf > + > .. Links: Applied, thanks. jon
Re: [PATCH] docs: index.rst: Add watch_queue
On Sat, 18 Jul 2020 13:51:07 -0300 "Daniel W. S. Almeida" wrote: > From: "Daniel W. S. Almeida" > > Fix the following sphinx warning: > > Documentation/watch_queue.rst: > WARNING: document isn't included in any toctree > > By adding watch_queue.rst to the index. > > Signed-off-by: Daniel W. S. Almeida > --- > Documentation/index.rst | 1 + > 1 file changed, 1 insertion(+) > > diff --git a/Documentation/index.rst b/Documentation/index.rst > index 3b491af0122de..57719744774c2 100644 > --- a/Documentation/index.rst > +++ b/Documentation/index.rst > @@ -193,6 +193,7 @@ to ReStructured Text format, or are simply too old. > :maxdepth: 2 > > staging/index > + watch_queue Thanks, I've applied this, but it isn't really the right fix - this document should not be at the top level of Documentation/. I'd be inclined to move it under userspace-api/, even though there's a strange mixture of user-space and kernel material here... jon
Re: [PATCH] docs: core-api/printk-formats.rst: use literal block syntax
On Tue, 21 Jul 2020 23:02:46 +0900 Sergey Senozhatsky wrote: > Jonathan, will you route it via the Documentation tree or do > you want it to land in the printk tree? I'm happy either way. I'll grab it unless you tell me you'd rather pick it up. Thanks, jon
Re: [PATCH for v5.9] RDS: Replace HTTP links with HTTPS ones
On Mon, 20 Jul 2020 17:07:16 +0300 Leon Romanovsky wrote: > > Do *you* want to review that megapatch? The number of issues that have > > come up make it clear that these patches do, indeed, need review... > > Can you point me to the issues? > What can go wrong with such a simple replacement? Some bits of the conversation: https://lore.kernel.org/lkml/20200626110219.7ae21...@lwn.net/ https://lore.kernel.org/lkml/20200626110706.7b5d4...@lwn.net/ https://lore.kernel.org/lkml/20200705142506.1f26a...@lwn.net/ https://lore.kernel.org/lkml/20200713114321.783f0...@lwn.net/ https://lore.kernel.org/lkml/202007081531.085533FC5@keescook/ etc. jon
Re: [PATCH for v5.9] RDS: Replace HTTP links with HTTPS ones
On Mon, 20 Jul 2020 07:56:26 +0300 Leon Romanovsky wrote: > > Documentation/networking/rds.rst | 2 +- > > 1 file changed, 1 insertion(+), 1 deletion(-) > > Why can't it be done in one mega-patch? > It is insane to see patch for every file/link. > > We have more than 4k files with http:// in it. Do *you* want to review that megapatch? The number of issues that have come up make it clear that these patches do, indeed, need review... jon
Re: [PATCH] Replace HTTP links with HTTPS ones: XDP (eXpress Data Path)
On Wed, 8 Jul 2020 15:57:37 +0200 "Alexander A. Klimov" wrote: > Documentation/arm/ixp4xx.rst | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) That's not XDP; something went awry in there somewhere. jon
Re: linux-next: manual merge of the jc_docs tree with the vfs and net-next trees
On Mon, 18 May 2020 12:30:13 +1000
Stephen Rothwell wrote:
> Today's linux-next merge of the jc_docs tree got a conflict in:
>
> kernel/sysctl.c
>
> between commit:
>
> f461d2dcd511 ("sysctl: avoid forward declarations")
>
> from the vfs tree and commit:
>
> 2f4c33063ad7 ("docs: sysctl/kernel: document ngroups_max")
>
> from the jc_docs tree.
Hmm...that's somewhat messy. I somehow managed to miss the change to
kernel/sysctl.c that doesn't have much to do with documentation. Stephen
(Kitt): I've reverted that change for now. Could I ask you to resubmit it
as two different patches? I'll happily take the actual docs change; the
sysctl change can be sent to the VFS tree on top of the changes there.
In general we really don't want to mix unrelated changes like this.
Thanks,
jon
Re: [PATCH 07/14] docs: add IRQ documentation at the core-api book
On Fri, 1 May 2020 17:37:51 +0200 Mauro Carvalho Chehab wrote: > There are 4 IRQ documentation files under Documentation/*.txt. > > Move them into a new directory (core-api/irq) and add a new > index file for it. > > While here, use a title markup for the Debugging section of the > irq-domain.rst file. > > Signed-off-by: Mauro Carvalho Chehab Applied, thanks. jon
Re: [PATCH 00/38] net: manually convert files to ReST format - part 1
On Tue, 28 Apr 2020 13:11:43 -0700 (PDT) David Miller wrote: > Jon, do you mind if I merge this via the networking tree? Not at all, that's what I was expecting you would do. Thanks, jon
Re: [PATCH net-next 1/2] UDP tunnel encapsulation module for tunnelling different protocols like MPLS,IP,NSH etc.
On Tue, 8 Oct 2019 15:18:53 +0530 Martin Varghese wrote: > diff --git a/Documentation/networking/bareudp.txt > b/Documentation/networking/bareudp.txt > new file mode 100644 > index 000..d2530e2 > --- /dev/null > +++ b/Documentation/networking/bareudp.txt > @@ -0,0 +1,23 @@ > +Bare UDP Tunnelling Module Documentation > + > + > +There are various L3 encapsulation standards using UDP being discussed to > +leverage the UDP based load balancing capability of different networks. > +MPLSoUDP (https://tools.ietf.org/html/rfc7510)is one among them. > + > +The Bareudp tunnel module provides a generic L3 encapsulation tunnelling > +support for tunnelling different L3 protocols like MPLS, IP, NSH etc. inside > +a UDP tunnel. > + > +Usage > +-- > + > +1. Device creation & deletion > + > +a. ip link add dev bareudp0 type bareudp dstport 6635 ethertype 0x8847 > + > +This creates a bareudp tunnel device which tunnels L3 traffic with ethertype > +0x8847 (MPLS traffic).The destination port of the UDP header will be set to > 6635 > +The device will listen on UDP port 6635 to receive traffic. > + > +b. ip link delete bareudp0 Please add new documentation in the RST format if at all possible. This document is 95% RST already; doing the last bit of work will save somebody else the effort of converting it in the future. Thanks, jon
Re: [PATCH 0/2] doc: net: ieee802154: move from plain text to rst
On Wed, 27 Feb 2019 20:59:12 +0100 Stefan Schmidt wrote: > The patches are based on net-next, but they only touch the networking book so > I > would not expect and trouble. From what I have seen they would go through > Jonathan's tree after being acked by Dave? If you want this patches against a > different tree let me know. Usually Dave takes networking documentation patches directly, so that is what I would expect here. I took a quick look anyway; seems generally good. The main comment I would make is that much of what's there would be better placed as kerneldoc comments in the code itself that can then be pulled into the formatted docs. But that can be a job for another day... Thanks, jon
Re: [PATCH] stable-kernel-rules.rst: add link to networking patch queue
On Tue, 22 Jan 2019 19:46:32 +0100 Greg Kroah-Hartman wrote: > The networking maintainer keeps a public list of the patches being > queued up for the next round of stable releases. Be sure to check there > before asking for a patch to be applied so that you do not waste > people's time. > > Signed-off-by: Greg Kroah-Hartman > Acked-by: David S. Miller > --- > > Jon, I can take this through one of my trees if you don't want to, which > ever is easier for you. I'm back from my wanderings finally and have just applied it. Thanks, jon
Re: [PATCH v2 1/1] doc: networking: integrate scaling document into doc tree
On Fri, 18 Jan 2019 21:38:32 +0100
Otto Sabart wrote:
> Convert scaling document into reStructuredText and add reference to
> scaling document into main table of contents in network documentation.
>
> There are no semantic changes.
>
> There are no references to "scaling.txt" file. Whole kernel tree was
> checked using:
> $ grep -r "scaling\.txt"
>
> Signed-off-by: Otto Sabart
So this didn't apply cleanly to docs-next due to a conflict with
commit d96bedb2b248 ("doc: networking: add offload documents into main
index file") by one Otto Sabart. I've fixed that up, but in the future
it will be helpful if you can be sure that your patches are against the
docs tree if you want me to merge them.
Thanks,
jon
Re: [PATCH v5] coding-style: Clarify the expectations around bool
On Fri, 18 Jan 2019 15:50:47 -0700 Jason Gunthorpe wrote: > There has been some confusion since checkpatch started warning about bool > use in structures, and people have been avoiding using it. > > Many people feel there is still a legitimate place for bool in structures, > so provide some guidance on bool usage derived from the entire thread that > spawned the checkpatch warning. > > Link: > https://lkml.kernel.org/r/ca+55afwvzk1ofb9t2v014ptakfhtvan_zj2dojncy3x6e4u...@mail.gmail.com > Signed-off-by: Joe Perches > Acked-by: Joe Perches > Reviewed-by: Bart Van Assche > Acked-by: Jani Nikula > Reviewed-by: Joey Pabalinas > Signed-off-by: Jason Gunthorpe So this seems ready; I've applied it. Thanks, jon
Re: [PATCH 1/3] doc: networking: prepare scaling document for conversion into RST
On Wed, 9 Jan 2019 20:57:22 +0100 Otto Sabart wrote: > Add markups which are necessary for successful conversion into > reStructuredText. > > There are no semantic changes. > > Signed-off-by: Otto Sabart This seems generally good, except: > Documentation/networking/scaling.txt | 131 +-- > 1 file changed, 85 insertions(+), 46 deletions(-) > > diff --git a/Documentation/networking/scaling.txt > b/Documentation/networking/scaling.txt > index b7056a8a0540..0ce13ed103bd 100644 > --- a/Documentation/networking/scaling.txt > +++ b/Documentation/networking/scaling.txt > @@ -1,4 +1,8 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > += > Scaling in the Linux Networking Stack > += > > > Introduction > @@ -10,11 +14,11 @@ multi-processor systems. > > The following technologies are described: > > - RSS: Receive Side Scaling > - RPS: Receive Packet Steering > - RFS: Receive Flow Steering > - Accelerated Receive Flow Steering > - XPS: Transmit Packet Steering > +- RSS: Receive Side Scaling > +- RPS: Receive Packet Steering > +- RFS: Receive Flow Steering > +- Accelerated Receive Flow Steering > +- XPS: Transmit Packet Steering > > > RSS: Receive Side Scaling > @@ -45,7 +49,9 @@ programmable filters. For example, webserver bound TCP port > 80 packets > can be directed to their own receive queue. Such “n-tuple” filters can > be configured from ethtool (--config-ntuple). > > - RSS Configuration > + > +RSS Configuration > +` The use of the heading levels is kind of strange; I'm not really sure why you did it that way? I'd rather this adhered to our normal hierarchy, so it should be: RSS Configuration - All of the other bottom-level headings should be as well. Fix that up, please, and I can take these. The whole series can also be squashed into a single patch (though I don't feel really strongly about that either way). Thanks, jon
Re: [PATCH v2 0/4] doc: network: integrate offload documents into doc tree
On Mon, 07 Jan 2019 07:30:29 -0800 (PST) David Miller wrote: > Jon, do you want to integrate these? I'm fine with that and I don't > anticiapte > any serious conflicts. I'll do that shortly, thanks. jon
Re: [PATCH RFC 00/15] Zero ****s, hugload of hugs <3
On Fri, 30 Nov 2018 14:12:19 -0800 Jarkko Sakkinen wrote: > As a maintainer myself (and based on somewhat disturbed feedback from > other maintainers) I can only make the conclusion that nobody knows what > the responsibility part here means. > > I would interpret, if I read it like at lawyer at least, that even for > existing code you would need to do the changes postmorterm. > > Is this wrong interpretation? Should I conclude that I made a mistake > by reading the CoC and trying to understand what it *actually* says? > After this discussion, I can say that I understand it less than before. Have you read Documentation/process/code-of-conduct-interpretation.rst? As has been pointed out, it contains a clear answer to how things should be interpreted here. Thanks, jon
Re: [PATCH RFC 00/15] Zero ****s, hugload of hugs <3
On Fri, 30 Nov 2018 12:55:21 -0800 Jarkko Sakkinen wrote: > This a direct quote from the CoC: > > "Harassment includes the use of abusive, offensive or degrading > language, intimidation, stalking, harassing photography or recording, > inappropriate physical contact, sexual imagery and unwelcome sexual > advances or requests for sexual favors." ...and this is from the interpretation document: > Contributions submitted for the kernel should use appropriate language. > Content that already exists predating the Code of Conduct will not be > addressed now as a violation. So existing code is explicitly not a CoC violation and need not be treated as such. That said, improvements to the comments are always welcome, as long as they are actually improvements. Thanks, jon
Re: [PATCH] Documentation: Add HOWTO Korean translation into BPF and XDP Reference Guide.
On Wed, 26 Sep 2018 18:11:42 +0900 Chang-an Song wrote: > > - The original document has a copyright assertion but no associated > >license. Do we know what the license is? I assume it's something > >that is free and GPL-compatible, but that would be good to know for > >sure. > > 3. I asked to main author Daniel that apache 2.0 license for this document. That is a bit of a problem, since Apache v2 is not compatible with GPLv2. If the license of the document cannot be changed, I don't think we can accept it into the kernel tree. Thanks, jon
Re: [PATCH] Documentation: Add HOWTO Korean translation into BPF and XDP Reference Guide.
On Fri, 21 Sep 2018 13:22:38 +0900 Changan Song wrote: > Signed-off-by: Changan Song > --- > Documentation/translations/ko_KR/bpf-xdp.txt | 3511 ++ > 1 file changed, 3511 insertions(+) > create mode 100644 Documentation/translations/ko_KR/bpf-xdp.txt I can't judge the quality of the translation, of course, but I do have a couple of related questions: - Since you're adding a new document, could you please format it as RST and add it to index.rst with the other Korean translations? The original will have been in RST, so this should be relatively easy to do. - The original document has a copyright assertion but no associated license. Do we know what the license is? I assume it's something that is free and GPL-compatible, but that would be good to know for sure. Thanks for doing this work, jon
Re: [PATCH net-next 0/2] docs: net: Convert netdev-FAQ to RST
On Wed, 25 Jul 2018 13:28:10 +1000 "Tobin C. Harding" wrote: > Since I've already botched it can I ask for guidance here. The problem > is updating the links means making changes that will cause merge > conflicts if they go through net-dev tree (since most references are in > Documentation/*.rst). But we can't go through docs tree either since > that could lead to merge conflicts later as well. Merge conflicts are a way of life in Documentation/ - everybody messes with it. They are usually pretty easy to resolve. I only see a handful of references to netdev-FAQ.txt in the tree; I would suggest just making the change and being done with it. There shouldn't be any need to do a more complicated dance than that. And to answer your other question, yes of course it's fine (and expected) for this to go through Dave's tree. Thanks, jon
Re: [PATCH net-next 4/5] tcp: implement mmap() for zero copy receive
On Thu, 19 Apr 2018 18:01:32 -0700 Eric Dumazet wrote: > We can keep mmap() nice interface, granted we can add one hook like in > following patch. > > David, do you think such patch would be acceptable by lkml and mm/fs > maintainers ? > > Alternative would be implementing an ioctl() or getsockopt() operation, > but it seems less natural... So I have little standing here, but what the heck, not letting that bother me has earned me a living for the last 20 years or so...:) I think you should consider switching over to an interface where you mmap() the region once, and use ioctl() to move the data into that region, for a couple of reasons beyond the locking issues you've already found: - The "mmap() consumes data" semantics are a bit ... strange, IMO. That's not what mmap() normally does. People expect ioctl() to do magic things, instead. - I would expect it to be a tiny bit faster, since you wouldn't be doing the VMA setup and teardown each time. Thanks, jon
[PATCH net-next] MAINTAINERS: Direct networking documentation changes to netdev
Networking docs changes go through the networking tree, so patch the MAINTAINERS file to direct authors to the right place. Signed-off-by: Jonathan Corbet --- MAINTAINERS | 1 + 1 file changed, 1 insertion(+) diff --git a/MAINTAINERS b/MAINTAINERS index 0a1410d5a621..bf4be491d4d9 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -9765,6 +9765,7 @@ F:include/uapi/linux/net_namespace.h F: tools/testing/selftests/net/ F: lib/net_utils.c F: lib/random32.c +F: Documentation/networking/ NETWORKING [IPSEC] M: Steffen Klassert -- 2.14.3
Re: [RFC PATCH ghak32 V2 01/13] audit: add container id
On Thu, 29 Mar 2018 05:01:32 -0400 Richard Guy Briggs wrote: > > A little detail, but still... > > I am understanding that you would prefer more context (as opposed to > operational detail) in the description, laying out the use case for this > patch(set)? No, sorry, "a little detail" was referring to my comment. The use case, I believe, has been well described. Thanks, jon
Re: [RFC PATCH ghak32 V2 01/13] audit: add container id
On Fri, 16 Mar 2018 05:00:28 -0400
Richard Guy Briggs wrote:
> Implement the proc fs write to set the audit container ID of a process,
> emitting an AUDIT_CONTAINER record to document the event.
A little detail, but still...
> +static int audit_set_containerid_perm(struct task_struct *task, u64
> containerid)
> +{
> + struct task_struct *parent;
> + u64 pcontainerid, ccontainerid;
> +
> + /* Don't allow to set our own containerid */
> + if (current == task)
> + return -EPERM;
> + /* Don't allow the containerid to be unset */
> + if (!cid_valid(containerid))
> + return -EINVAL;
I went looking for cid_valid(), but it turns out you don't add it until
patch 5. That, I expect, will not be good for bisectability (or patch
review).
Thanks,
jon
Re: [PATCH] docs-rst: networking: wire up msg_zerocopy
On Tue, 09 Jan 2018 11:50:49 -0500 (EST) David Miller wrote: > From: Mike Rapoport > Date: Mon, 8 Jan 2018 08:50:17 +0200 > > > Fix the following 'make htmldocs' complaint: > > > > Documentation/networking/msg_zerocopy.rst:: WARNING: document isn't > > included in any toctree. > > > > Signed-off-by: Mike Rapoport > > Does someone else want to take this? > > Otherwise I can. I can certainly take it (or the equivalent patch posted by Tobin a few days earlier) through the docs tree. I've been holding off, though, under the impression that you'd rather take networking docs patches yourself. Either is fine. Unless you say you've grabbed it, I'll do so in the near future. Thanks, jon
Re: [PATCH 02/18] Documentation: document nospec helpers
On Mon, 8 Jan 2018 17:09:59 + Mark Rutland wrote: > > I have just a couple of overall comments. > > > > - It would be nice if the document were done in RST and placed in the > >core-API manual, perhaps using kerneldoc comments for the macros > >themselves. It's already 99.9% RST now, so the changes required would > >be minimal. > > Is there any quickstart guide to RST that you can recommend? http://docutils.sourceforge.net/docs/user/rst/quickref.html works reasonably well. We have some info in the kernel documentation as well, see http://static.lwn.net/kerneldoc/doc-guide/sphinx.html Thanks, jon
Re: [PATCH 02/18] Documentation: document nospec helpers
On Fri, 05 Jan 2018 17:10:03 -0800 Dan Williams wrote: > Document the rationale and usage of the new nospec*() helpers. I have just a couple of overall comments. - It would be nice if the document were done in RST and placed in the core-API manual, perhaps using kerneldoc comments for the macros themselves. It's already 99.9% RST now, so the changes required would be minimal. - More importantly: is there any way at all to give guidance to developers wondering *when* they should use these primitives? I think it would be easy to create a situation where they don't get used where they are really needed; meanwhile, there may well be a flood of "helpful" patches adding them where they make no sense at all. Thanks, jon
Re: [PATCH v7 1/5] add infrastructure for tagging functions as error injectable
On Wed, 22 Nov 2017 16:23:30 -0500 Josef Bacik wrote: > From: Josef Bacik > > Using BPF we can override kprob'ed functions and return arbitrary > values. Obviously this can be a bit unsafe, so make this feature opt-in > for functions. Simply tag a function with KPROBE_ERROR_INJECT_SYMBOL in > order to give BPF access to that function for error injection purposes. > > Signed-off-by: Josef Bacik > Acked-by: Ingo Molnar > --- > arch/x86/include/asm/asm.h| 6 ++ > include/asm-generic/vmlinux.lds.h | 10 +++ > include/linux/bpf.h | 11 +++ > include/linux/kprobes.h | 1 + > include/linux/module.h| 5 ++ > kernel/kprobes.c | 163 > ++ > kernel/module.c | 6 +- > 7 files changed, 201 insertions(+), 1 deletion(-) > > diff --git a/arch/x86/include/asm/asm.h b/arch/x86/include/asm/asm.h > index b0dc91f4bedc..340f4cc43255 100644 > --- a/arch/x86/include/asm/asm.h > +++ b/arch/x86/include/asm/asm.h > @@ -85,6 +85,12 @@ > _ASM_PTR (entry); \ > .popsection > > +# define _ASM_KPROBE_ERROR_INJECT(entry) \ > + .pushsection "_kprobe_error_inject_list","aw" ; \ > + _ASM_ALIGN ;\ > + _ASM_PTR (entry); \ > + .popseciton So this stuff is not my area of greatest expertise, but I do have to wonder how ".popseciton" can work ... ? Thanks, jon
Re: [PATCH] New Chapter on CodingStyle .
On Sat, 12 Aug 2017 14:23:18 +0300 Corcodel Marian wrote: > --- > Documentation/CodingStyle | 28 > 1 file changed, 28 insertions(+) > > diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle > index 9a70ddd..864dd8b 100644 > --- a/Documentation/CodingStyle > +++ b/Documentation/CodingStyle > @@ -922,6 +922,34 @@ expression used. For instance: > ... > #endif /* CONFIG_SOMETHING */ > > + Chapter 20: Put values on initialisers without exception > + > +When declaring variables on functions must put values: Thanks for sending a patch for the kernel's documentation. Unfortunately, I can't accept this patch for a couple of reasons: - Kernel patches must include a changelog describing *why* the change is being made and a proper signoff line. See Documentation/process/submitting-patches.rst for details. - The coding style document is there to describe the community's standards for kernel code. It is *not* a mechanism for imposing new standards. If you really think that the kernel community should adopt this rule, you will need to argue for it on the mailing lists. I will say, though, that I do not expect that this effort would be successful. Can I make a suggestion? If you have found kernel functions with bugs related to use of uninitialized variables, please submit fixes for those specific bugs, along with a clear description of how the bug happens and what its effects are. Thanks, jon
Re: [PATCH] b43legacy: Fix a sleep-in-atomic bug in b43legacy_attr_interfmode_store
On Thu, 01 Jun 2017 09:05:07 +0800 Jia-Ju Bai wrote: > I admit my patches are not well tested, and they may not well fix the bugs. > I am looking forward to opinions and suggestions :) May I politely suggest that sending out untested locking changes is a dangerous thing to do? You really should not be changing the locking in a piece of kernel code without understanding very well what the lock is protecting and being able to say why your changes are safe. Without that, the risk of introducing subtle bugs is very high. It looks like you have written a useful tool that could help us to make the kernel more robust. If you are interested in my suggestion, I would recommend that you post the sleep-in-atomic scenarios that you are finding, but refrain from "fixing" them in any case where you cannot offer a strong explanation of why your fix is correct. Thanks for working to find bugs in the kernel! jon
Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter
On Tue, 7 Feb 2017 21:51:49 +0100 Jesper Dangaard Brouer wrote: > I sounds like Daniel (see other email) have bigger plans for what > Documentation/BPF/ should contain. E.g. consolidating > Documentation/networking/filter.txt which covers the cBPF/eBPF internals. > If that is the case (and I like the idea), then it goes beyond a > "userspace-guide". And perhaps "BPF" is a "book" of its own? One of the real problems with the kernel's documentation is that there is really almost no thought given to who the audience is. We have docs for kernel developers, for system admins, for user-space developers, etc., and it's all mixed up into one big jumble. An objective of mine in launching into this whole project is to try to fix that, so that people can readily find the documentation they need. So I don't think a single top-level directory, with a mix of user-space API info and "internals", is the right direction to go. The internals docs should, IMO, go elsewhere, probably in the core-api manual. See what I'm getting at here? > And it seems Daniel is proposing capital-letters BPF for the directory > name "Documentation/BPF/"? Any opinions on that? (I'm neutral) I think we should paint it green; otherwise I'm not too concerned about this particular point...:) Thanks, jon
Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter
On Tue, 7 Feb 2017 17:09:08 +0100 Jesper Dangaard Brouer wrote: > > > Question: What kernel tree should this go into??? > > > > > > If going through Jonathan Corbet, will it appear sooner here??? > > > https://www.kernel.org/doc/html/latest/ > > What about this question? Or let me ask in another way, what tree is > https://www.kernel.org/doc/html/latest/ based on? I believe it's generated from the current -rc. If this stuff goes into 4.11, it should show up there next week. > Yes, I was also wondering hard where to put it... and a book for > user-space developer documentation would likely be the right place, but > it was not there, as you mention ;-) > > I'm fine with moving it later under another "book". Linking to it as > HTML would still be the same right? > (https://www.kernel.org/doc/html/latest/bpf/index.html) > And is the Documentation/bpf/ directory the correct place? Moving it would change the URL, of course. If we want to avoid that, we should try to come up with the proper placement from the outset. And we would want to move it; I really want to clean up the mess that is the top-level directory. How about if it goes into Documentation/userspace-guide/bpf ? The intermediate directory could just be empty for now, I'll put the book structure into place later on. Then the URL for the BPF guide itself wouldn't change. jon
Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter
On Tue, 07 Feb 2017 15:30:11 +0100 Jesper Dangaard Brouer wrote: > Question: What kernel tree should this go into??? > > If going through Jonathan Corbet, will it appear sooner here??? > https://www.kernel.org/doc/html/latest/ > If it will not appear sooner that way, then it's likely best to keep > it in sync with the tree that takes eBPF code changes. I've developed a fairly strong preference for carrying patches touching index.rst; otherwise I spend a lot of time explaining merge conflicts to Linus. If the consensus is that this is ready to go, I expect I can squeeze it in for 4.11. I'm not too worried about regressions...:) I haven't actually built it yet, but from a first look it seems like an awfully good start. The one thing that comes to mind is that I'm likely to want to move it at some point. I'd really like to start a separate book for user-space developer documentation, and this would certainly belong there. That book doesn't exist yet, though, so I can't quite blame you, hard as I might try, for not putting this document there. Thanks, jon
Re: [PATCH v9 7/8] thunderbolt: Networking doc
On Wed, 9 Nov 2016 17:00:02 +0100 Greg KH wrote: > > Documentation/00-INDEX | 2 + > > Documentation/thunderbolt/networking.txt | 132 > > +++ > > Note, new files should be in .rst format, and live in the new > subdirectory for them (somewhere in Documentation, don't know off the > top of my head...) This one's almost in RST already, happily. We haven't really figured out a hierarchy for device-specific docs like this yet; I should get on that, I guess. I do believe that we should separate documents for end users from those aimed at kernel developers; those are two very different audiences looking for different kinds of information. Thanks, jon
Re: [PATCH v2 0/6] Move runnable code (tests) from Documentation to selftests
On Tue, 13 Sep 2016 14:18:39 -0600 Shuah Khan wrote: > Move runnable code (tests) from Documentation to selftests and update > Makefiles to work under selftests. This all seems good to me. Acked-by: Jonathan Corbet jon
Re: [PATCH 0/9] Move runnable code (tests) from Documentation to selftests
On Fri, 9 Sep 2016 16:22:41 -0600 Shuah Khan wrote: > Move runnable code (tests) from Documentation to selftests and update > Makefiles to work under selftests. > > Jon Corbet and I discussed this in an email thread and as per that > discussion, this patch series moves all the tests that are under the > Documentation directory to selftests. There is more runnable code in > the form of examples and utils and that is going to be another patch > series. I moved just the tests and left the documentation files as is. I'm fine with the idea, but it looks like a couple of tweaks are needed, in particular to avoid leaving behind dangling references in Documentation/Makefile that cause build errors. I think the individual patches probably need a wider CC list as well. I'd use the get_maintainer script (or git) to see who has taken an interest in the individual tests and make sure they are aware of the move. Thanks, jon
Re: possible patch
On Wed, 10 Feb 2016 19:49:11 -0500
Justin Keller wrote:
> I am new to submitting patches, so sorry if I am doing it wrong. My idea was
> to change line 147 in drivers/isdn/pcbit/callbacks.c from
> if (cbdata->data.setup.CallingPN == NULL) {
>
> to
>
> if (cbdata->data.setup.CallingPN == NULL ||
> sizeof(cbdata->data.setup.CallingPN)>sizeof(ictl.parm.setup.phone) {
If you want to patch the kernel, the best way to describe what you want to
do is to ... send a patch.
Before you do so, though:
- Please read the available documentation, including SubmittingPatches and
development-process/*
- Prepare a proper changelog saying *why* you want to make this change.
You are trying to change the ISDN subsystem, which is pretty static
these days; what current problem are you running into that makes you
think this change needs to be applied to the kernel?
Thanks,
jon
Re: [PATCH RESEND] net: Documentation: Fix default value tcp_limit_output_bytes
On Wed, 11 Nov 2015 11:57:24 -0500 (EST) David Miller wrote: > > I left this last time because Dave usually likes to pick up networking > > docs patches himself. This wasn't sent to netdev, though, so that's > > unlikely to happen. I've gone ahead and applied it, since it seems > > clearly correct. > > I already took this into my tree as per: > > http://marc.info/?l=linux-netdev&m=144708947814679&w=2 > > and patchwork entry: > > http://patchwork.ozlabs.org/patch/541786/ > > and since Linus pulled my tree in earlier today it's now in > his tree as well. Ah...I'm so behind the times...then I won't take it here after all. Thanks, jon -- To unsubscribe from this list: send the line "unsubscribe netdev" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH RESEND] net: Documentation: Fix default value tcp_limit_output_bytes
On Mon, 9 Nov 2015 14:58:49 +0100
Niklas Cassel wrote:
> Commit c39c4c6abb89 ("tcp: double default TSQ output bytes limit")
> updated default value for tcp_limit_output_bytes
I left this last time because Dave usually likes to pick up networking
docs patches himself. This wasn't sent to netdev, though, so that's
unlikely to happen. I've gone ahead and applied it, since it seems
clearly correct.
Thanks,
jon
> Signed-off-by: Niklas Cassel
> ---
> Documentation/networking/ip-sysctl.txt | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/networking/ip-sysctl.txt
> b/Documentation/networking/ip-sysctl.txt
> index 05915be..2ea4c45 100644
> --- a/Documentation/networking/ip-sysctl.txt
> +++ b/Documentation/networking/ip-sysctl.txt
> @@ -709,7 +709,7 @@ tcp_limit_output_bytes - INTEGER
> typical pfifo_fast qdiscs.
> tcp_limit_output_bytes limits the number of bytes on qdisc
> or device to reduce artificial RTT/cwnd and reduce bufferbloat.
> - Default: 131072
> + Default: 262144
>
> tcp_challenge_ack_limit - INTEGER
> Limits number of Challenge ACK sent per second, as recommended
> --
> 2.1.4
>
--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: make mandocs build failure with next-20150407
On Thu, 16 Apr 2015 08:33:15 +0900 Masanari Iida wrote: > On Wed, Apr 8, 2015 at 7:41 AM, Jim Davis wrote: > > DOCPROC Documentation/DocBook/80211.xml > > Error(.//include/net/mac80211.h:329): Cannot parse enum! > > Error(.//include/net/mac80211.h:367): Cannot parse enum! > > Warning(.//include/net/mac80211.h:381): No description found for > > parameter 'type' > > -- > > This error start to appear on Linus's tree. > make xmldocs stops after this error. > Then run it again, make xmldocs process rest of the files. > > Add TO: netdev and patch authors for reporting the issue. It's the result of some incomplete changes in the wireless tree; I sent a fix to Johannes that he applied a couple of days ago. Once that hits mainline the problem should go away. Thanks, jon -- To unsubscribe from this list: send the line "unsubscribe netdev" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH RFC] [1/9] Core module symbol namespaces code and intro.
Rusty said: > Well, introduce an EXPORT_SYMBOL_INTERNAL(). It's a lot less code. But > you'd > still need to show that people are having trouble knowing what APIs to use. Might the recent discussion on the exporting of sys_open() and sys_read() be an example here? There would appear to be a consensus that people should not have used those functions, but they are now proving difficult to unexport. Perhaps the best use of the namespace stuff might be for *future* exports which are needed to help make the mainline kernel fully modular, but which are not meant to be part of a more widely-used API? jon - To unsubscribe from this list: send the line "unsubscribe netdev" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Van Jacobson net channels
Andi writes: > But I don't think Van's design is supposed to be exposed to user space. > It's just a better way to implement BSD sockets. Actually, it can, indeed, go all the way to user space - connecting channels to the socket layer was one of the intermediate steps. FWIW, I did an article on this, going mostly from the slides. Here's a get-out-of-subscription-jail-free card for it: http://lwn.net/SubscriberLink/169961/776b6c53d1c1673a/ jon - To unsubscribe from this list: send the line "unsubscribe netdev" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: doubt in DMAing
> can any1 point me to a good linux memory management stuff. Actually i > want to know the conversion of virtual to physical address and when u > need to do it. The DMA chapter of LDD3 covers this topic in detail: http://lwn.net/Kernel/LDD3/ jon Jonathan Corbet Executive editor, LWN.net [EMAIL PROTECTED] - To unsubscribe from this list: send the line "unsubscribe netdev" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
