* Re: [PATCH v2 2/2] f2fs: Support case-insensitive file name lookups
From: Daniel Rosenberg @ 2019-07-18 21:31 UTC (permalink / raw)
To: Chao Yu, Jaegeuk Kim, Jonathan Corbet, linux-f2fs-devel
Cc: linux-kernel, linux-doc, linux-fsdevel, kernel-team
In-Reply-To: <cbaf59d4-0bd3-6980-4750-fbab14941bdb@huawei.com>
On 7/17/19 3:11 AM, Chao Yu wrote:
> We need to add one more entry f2fs_fsflags_map[] to map F2FS_CASEFOLD_FL to
> FS_CASEFOLD_FL correctly and adapt F2FS_GETTABLE_FS_FL/F2FS_SETTABLE_FS_FL as well.
I don't see FS_CASEFOLD_FL. It would make sense for it to exist, but unless it's in some recent patch I don't think that's currently in the kernel. Or are you suggesting adding it in this patch?
^ permalink raw reply
* Re: [PATCH v2 08/11] kbuild: create *.mod with full directory path and remove MODVERDIR
From: Joe Lawrence @ 2019-07-18 20:18 UTC (permalink / raw)
To: Masahiro Yamada
Cc: Linux Kbuild mailing list, Sam Ravnborg, Nicolas Pitre,
open list:DOCUMENTATION, Jonathan Corbet,
Linux Kernel Mailing List, Michal Marek
In-Reply-To: <CAK7LNAQ41NhPPO6xoVObgFctTO6WewSXPfZkE7_bZXsdAtKSpA@mail.gmail.com>
On 7/17/19 1:21 AM, Masahiro Yamada wrote:
>> Hi Masahiro,
>>
>> I'm following this patchset changes as they will affect the klp-convert
>> series [1] that the livepatching folks have been working on...
>
> Empty files .tmp_versions/*.livepatch are touched
> to keep track of 'LIVEPATCH_* := y', right?
>
Pretty much. From that patchset I think the rework would need to modify..
- [PATCH v4 02/10] kbuild: Support for Symbols.list creation: creates a
Symbols.list file of kernel and module symbols, but *not* including any
from LIVEPATCH_* modules.
- [PATCH v4 05/10] modpost: Integrate klp-convert: if a LIVEPATCH_*
module has changed, call a newly introduced klp-convert script on it.
- [PATCH v4 06/10] modpost: Add modinfo flag to livepatch modules: find
any LIVEPATCH_* mod, add it to a livepatchmods file, then pass that file
to modpost
> Perhaps, adding a new field
> to *.mod files might be cleaner.
I can look into that. By "field" you mean a new row in the file?
Regards,
-- Joe
^ permalink raw reply
* Re: [PATCH v9 04/18] kunit: test: add kunit_stream a std::stream like logger
From: Brendan Higgins @ 2019-07-18 19:22 UTC (permalink / raw)
To: Stephen Boyd
Cc: Frank Rowand, Greg KH, Josh Poimboeuf, Kees Cook, Kieran Bingham,
Luis Chamberlain, Peter Zijlstra, Rob Herring, shuah,
Theodore Ts'o, Masahiro Yamada, devicetree, dri-devel,
kunit-dev, open list:DOCUMENTATION, linux-fsdevel, linux-kbuild,
Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK,
linux-nvdimm, linux-um, Sasha Levin, Bird, Timothy,
Amir Goldstein, Dan Carpenter, Daniel Vetter, Jeff Dike,
Joel Stanley, Julia Lawall, Kevin Hilman, Knut Omang,
Logan Gunthorpe, Michael Ellerman, Petr Mladek, Randy Dunlap,
Richard Weinberger, David Rientjes, Steven Rostedt, wfg
In-Reply-To: <20190718175024.C3EC421019@mail.kernel.org>
On Thu, Jul 18, 2019 at 10:50 AM Stephen Boyd <sboyd@kernel.org> wrote:
>
> Quoting Brendan Higgins (2019-07-16 11:52:01)
> > On Tue, Jul 16, 2019 at 10:50 AM Stephen Boyd <sboyd@kernel.org> wrote:
> > >
> >
> > > The only hypothetical case where this can't be done is a complicated
> > > assertion or expectation that does more than one check and can't be
> > > written as a function that dumps out what went wrong. Is this a real
> > > problem? Maybe such an assertion should just open code that logic so we
> > > don't have to build up a string for all the other simple cases.
> >
> > I have some expectations in follow up patchsets for which I created a
> > set of composable matchers for matching structures and function calls
> > that by their nature cannot be written as a single function. The
> > matcher thing is a bit speculative, I know, but for any kind of
> > function call matching, you need to store a record of functions you
> > are expecting to have called and then each one needs to have a set of
> > expectations defined by the user; I don't think there is a way to do
> > that that doesn't involve having multiple separate functions each
> > having some information useful to constructing the message.
> >
> > I know the code in question isn't in this patchset; the function
> > matching code was in one of the earlier versions of the RFC, but I
> > dropped it to make this patchset smaller and more manageable. So I get
> > it if you would like me to drop it and add it back in when I try to
> > get the function and structure matching stuff in, but I would really
> > prefer to keep it as is if you don't care too much.
>
> Do you have a link to those earlier patches?
This is the first patchset:
https://www.mail-archive.com/linux-kernel@vger.kernel.org/msg1788057.html
In particular you can see the code for matching functions here:
https://www.mail-archive.com/linux-kernel@vger.kernel.org/msg1788073.html
And parameter matching code here:
https://www.mail-archive.com/linux-kernel@vger.kernel.org/msg1788072.html
https://www.mail-archive.com/linux-kernel@vger.kernel.org/msg1788086.html
My apologies in advance, but the code at this early stage had not
adopted the kunit_* prefix and was still using the test_* and mock_*
prefix. (Hence, struct kunit_stream was known as struct test_stream).
> > > It seems far simpler to get rid of the string stream API and just have a
> > > struct for this.
> > >
> > > struct kunit_fail_msg {
> > > const char *line;
> > > const char *file;
> > > const char *func;
> > > const char *msg;
> > > };
> > >
> > > Then you can have the assertion macros create this on the stack (with
> > > another macro?).
> > >
> > > #define DEFINE_KUNIT_FAIL_MSG(name, _msg) \
> > > struct kunit_fail_msg name = { \
> > > .line = __LINE__, \
> > > .file = __FILE__, \
> > > .func = __func__, \
> > > .msg = _msg, \
> > > }
> > >
> > > I don't want to derail this whole series on this topic, but it seems
> > > like a bunch of code is there to construct this same set of information
> > > over and over again into a buffer a little bit at a time and then throw
> > > it away when nothing fails just because we may want to support the case
> > > where we have some unstructured data to inform the user about.
> >
> > Yeah, that's fair. I think there are a number of improvements to be
> > made with how the expectations are defined other than that, but I was
> > hoping I could do that after this patchset is merged. I just figured
> > with the kinds of things I would like to do, it would lead to a whole
> > new round of discussion.
> >
> > In either case, I think I would still like to use the `struct
> > kunit_stream` as part of the interface to share the failure message
> > with the test case runner code in test.c, at least eventually, so that
> > I only have to have one way to receive data from expectations, but I
> > think I can do that and still do what you suggest by just constructing
> > the kunit_stream at the end of expectations where it is feasible.
> >
> > All in all I agree with what you are saying, but I would rather do it
> > as a follow up possibly once we have some more code on the table. I
> > could just see this opening up a whole new can of worms where we
> > debate about exactly how expectations and assertions work for another
> > several months, only to rip it all out shortly there after. I know
> > that's how these things go, but that's my preference.
> >
> > I can do what you suggest if you feel strongly about it, but I would
> > prefer to hold off until later. It's your call.
> >
>
> The crux of my complaint is that the string stream API is too loosely
> defined to be usable. It allows tests to build up a string of
> unstructured information, but with certain calling constraints so we
> have to tread carefully. If there was more structure to the data that's
> being recorded then the test case runner could operate on the data
> without having to do string/stream operations, allocations, etc. This
> would make the assertion logic much more concrete and specific to kunit,
> instead of this small kunit wrapper that's been placed on top of string
> stream.
Yeah, I can see the point of wanting something that provides more
structure than the raw `struct kunit_stream` interface. In fact, it is
something I had already started working on, when I had determined it
would be a large effort to capture all the variations. I was further
put off from the idea when I had been asked to convert the KUnit
intermediate format from what I was using to TAP, because, as it is,
the current data printed out by KUnit doesn't contain all the data I
would like to put in it in a way that best takes advantage of the TAP
specification. One problematic area in particular: TAP already
provides a way to present a lot of the data I would like to export,
but it involves JSON serialization which was an idea that some of the
other reviewers understandably weren't too keen on. TAP also wants to
report data some time after it is available, which is generally not a
good idea for test debug information; you want to make it available as
soon as you can or you risk crashing with the data still inside.
Hence, I decided we could probably spend a good long while debating
how I present the information. So the idea of having a loose
definition seemed attractive to me in its own right since it would
likely conform to whatever we ended up deciding in the long run. Also,
all the better that it was what I already had and no one seemed to
mind too much.
The only constant I expect is that `struct kunit` will likely need to
take an abstract object with a `commit` method, or a `format` method
or whatever so it could control when data was going to be printed out
to the user. We will probably also use a string builder in there
somewhere.
> TL;DR: If we can get rid of the string stream API I'd view that as an
> improvement because building arbitrary strings in the kernel is complex,
> error prone and has calling context concerns.
True. No argument there.
> Is the intention that other code besides unit tests will use this string
> stream API to build up strings? Any targets in mind? This would be a
> good way to get the API merged upstream given that its 2019 and we
> haven't had such an API in the kernel so far.
Someone, (was it you?) asked about code sharing with a string builder
thingy that was used for creating structured human readable files, but
that seemed like a pretty massive undertaking.
Aside from that, no. I would kind of prefered that nobody used it for
anything else because I the issues you described.
Nevertheless, I think the debate over the usefulness of the
string_stream and kunit_stream are separate topics. Even if we made
kunit_stream more structured, I am pretty sure I would want to use
string_stream or some variation for constructing the message.
> An "object oriented" (strong quotes!) approach where kunit_fail_msg is
> the innermost struct in some assertion specific structure might work
> nicely and allow the test runner to call a generic 'format' function to
> print out the message based on the type of assertion/expectation it is.
> It probably would mean less code size too because the strings that are
> common will be in the common printing function instead of created twice,
> in the macros/code and then copied to the heap for the string stream.
>
> struct kunit_assert {
> const char *line;
> const char *file;
> const char *func;
> void (*format)(struct kunit_assert *assert);
> };
>
> struct kunit_comparison_assert {
> enum operator operator;
> const char *left;
> const char *right;
> struct kunit_assert assert;
> };
>
> struct kunit_bool_assert {
> const char *truth;
> const char *statement;
> struct kunit_assert assert;
> };
>
> void kunit_format_comparison(struct kunit_assert *assert)
> {
> struct kunit_comparison_assert *comp = container_of(assert, ...)
>
> kunit_printk(...)
> }
I started working on something similarish, but by the time I ended up
coming up with a parent object whose definition was loose enough to
satisfy all the properties required by the child classes it ended up
basically being the same as what I have now just with a more complex
hierarchy of message manipulation logic.
On the other hand, I didn't have the idea of doing the parent object
quite the way you did and that would clean up a lot of the duplicated
first line logic.
I would like to give it a try, but I am afraid I am going to get
sucked down a really deep rabbit hole.
> Maybe other people have opinions here on if you should do it now or
> later. Future coding is not a great argument because it's hard to
> predict the future. On the other hand, this patchset is in good shape to
Yeah, that's kind of why I am afraid to go down this road when I have
something that works now and I know works with the mocking stuff I
want to do.
I would like to try your suggestion, but I want to try to make it work
with my mocking patches before I commit to it because otherwise I am
just going to have to back it out in a follow up patchset.
> merge and I'd like to use it to write unit tests for code I maintain so
> I don't want to see this stall out. Sorry if I'm opening the can of
> worms you're talking about.
Don't be sorry. I agree with you that the kunit_stream stuff is not very pretty.
Shuah, have we missed the merge window for 5.3?
I saw you only sent one PR out so far for this release, and there
wasn't much in it; I imagine you are going to send at least one more?
I figure, if we still got time to try out your suggestion, Stephen, no
harm in trying.
Also if we missed it, then I have another couple months to play around with it.
What do you think?
^ permalink raw reply
* Re: Using rst2pdf for PDF output - Was: Re: [PATCH 0/5] PDF output fixes
From: Markus Heiser @ 2019-07-18 17:56 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Jonathan Corbet; +Cc: linux-doc
In-Reply-To: <20190718144655.5aa7deb4@coco.lan>
Am 18.07.19 um 19:46 schrieb Mauro Carvalho Chehab:
> Em Sat, 13 Jul 2019 00:41:25 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
>
>> Em Fri, 12 Jul 2019 19:27:05 -0300
>> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
>>
>>> Em Fri, 12 Jul 2019 14:19:21 -0600
>>> Jonathan Corbet <corbet@lwn.net> escreveu:
>>>
>>>> Can't you just make rst2pdf work instead? :)
>>>
>>> Well, we can try.
Thanks a lot for your investigation on this. I also checked the rst2pdf sources
a while ago, for me it was crap with crap requirements [1] .. my tip: don't
waste to much time on it.
[1] https://github.com/mchehab/rst2pdf/blob/master/requirements.txt#L31
-- Markus --
^ permalink raw reply
* Re: [PATCH v9 04/18] kunit: test: add kunit_stream a std::stream like logger
From: Stephen Boyd @ 2019-07-18 17:50 UTC (permalink / raw)
To: Brendan Higgins
Cc: Frank Rowand, Greg KH, Josh Poimboeuf, Kees Cook, Kieran Bingham,
Luis Chamberlain, Peter Zijlstra, Rob Herring, shuah,
Theodore Ts'o, Masahiro Yamada, devicetree, dri-devel,
kunit-dev, open list:DOCUMENTATION, linux-fsdevel, linux-kbuild,
Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK,
linux-nvdimm, linux-um, Sasha Levin, Bird, Timothy,
Amir Goldstein, Dan Carpenter, Daniel Vetter, Jeff Dike,
Joel Stanley, Julia Lawall, Kevin Hilman, Knut Omang,
Logan Gunthorpe, Michael Ellerman, Petr Mladek, Randy Dunlap,
Richard Weinberger, David Rientjes, Steven Rostedt, wfg
In-Reply-To: <CAFd5g453vXeSUCZenCk_CzJ-8a1ym9RaPo0NVF=FujF9ac-5Ag@mail.gmail.com>
Quoting Brendan Higgins (2019-07-16 11:52:01)
> On Tue, Jul 16, 2019 at 10:50 AM Stephen Boyd <sboyd@kernel.org> wrote:
> >
>
> > The only hypothetical case where this can't be done is a complicated
> > assertion or expectation that does more than one check and can't be
> > written as a function that dumps out what went wrong. Is this a real
> > problem? Maybe such an assertion should just open code that logic so we
> > don't have to build up a string for all the other simple cases.
>
> I have some expectations in follow up patchsets for which I created a
> set of composable matchers for matching structures and function calls
> that by their nature cannot be written as a single function. The
> matcher thing is a bit speculative, I know, but for any kind of
> function call matching, you need to store a record of functions you
> are expecting to have called and then each one needs to have a set of
> expectations defined by the user; I don't think there is a way to do
> that that doesn't involve having multiple separate functions each
> having some information useful to constructing the message.
>
> I know the code in question isn't in this patchset; the function
> matching code was in one of the earlier versions of the RFC, but I
> dropped it to make this patchset smaller and more manageable. So I get
> it if you would like me to drop it and add it back in when I try to
> get the function and structure matching stuff in, but I would really
> prefer to keep it as is if you don't care too much.
Do you have a link to those earlier patches?
>
> > It seems far simpler to get rid of the string stream API and just have a
> > struct for this.
> >
> > struct kunit_fail_msg {
> > const char *line;
> > const char *file;
> > const char *func;
> > const char *msg;
> > };
> >
> > Then you can have the assertion macros create this on the stack (with
> > another macro?).
> >
> > #define DEFINE_KUNIT_FAIL_MSG(name, _msg) \
> > struct kunit_fail_msg name = { \
> > .line = __LINE__, \
> > .file = __FILE__, \
> > .func = __func__, \
> > .msg = _msg, \
> > }
> >
> > I don't want to derail this whole series on this topic, but it seems
> > like a bunch of code is there to construct this same set of information
> > over and over again into a buffer a little bit at a time and then throw
> > it away when nothing fails just because we may want to support the case
> > where we have some unstructured data to inform the user about.
>
> Yeah, that's fair. I think there are a number of improvements to be
> made with how the expectations are defined other than that, but I was
> hoping I could do that after this patchset is merged. I just figured
> with the kinds of things I would like to do, it would lead to a whole
> new round of discussion.
>
> In either case, I think I would still like to use the `struct
> kunit_stream` as part of the interface to share the failure message
> with the test case runner code in test.c, at least eventually, so that
> I only have to have one way to receive data from expectations, but I
> think I can do that and still do what you suggest by just constructing
> the kunit_stream at the end of expectations where it is feasible.
>
> All in all I agree with what you are saying, but I would rather do it
> as a follow up possibly once we have some more code on the table. I
> could just see this opening up a whole new can of worms where we
> debate about exactly how expectations and assertions work for another
> several months, only to rip it all out shortly there after. I know
> that's how these things go, but that's my preference.
>
> I can do what you suggest if you feel strongly about it, but I would
> prefer to hold off until later. It's your call.
>
The crux of my complaint is that the string stream API is too loosely
defined to be usable. It allows tests to build up a string of
unstructured information, but with certain calling constraints so we
have to tread carefully. If there was more structure to the data that's
being recorded then the test case runner could operate on the data
without having to do string/stream operations, allocations, etc. This
would make the assertion logic much more concrete and specific to kunit,
instead of this small kunit wrapper that's been placed on top of string
stream.
TL;DR: If we can get rid of the string stream API I'd view that as an
improvement because building arbitrary strings in the kernel is complex,
error prone and has calling context concerns.
Is the intention that other code besides unit tests will use this string
stream API to build up strings? Any targets in mind? This would be a
good way to get the API merged upstream given that its 2019 and we
haven't had such an API in the kernel so far.
An "object oriented" (strong quotes!) approach where kunit_fail_msg is
the innermost struct in some assertion specific structure might work
nicely and allow the test runner to call a generic 'format' function to
print out the message based on the type of assertion/expectation it is.
It probably would mean less code size too because the strings that are
common will be in the common printing function instead of created twice,
in the macros/code and then copied to the heap for the string stream.
struct kunit_assert {
const char *line;
const char *file;
const char *func;
void (*format)(struct kunit_assert *assert);
};
struct kunit_comparison_assert {
enum operator operator;
const char *left;
const char *right;
struct kunit_assert assert;
};
struct kunit_bool_assert {
const char *truth;
const char *statement;
struct kunit_assert assert;
};
void kunit_format_comparison(struct kunit_assert *assert)
{
struct kunit_comparison_assert *comp = container_of(assert, ...)
kunit_printk(...)
}
Maybe other people have opinions here on if you should do it now or
later. Future coding is not a great argument because it's hard to
predict the future. On the other hand, this patchset is in good shape to
merge and I'd like to use it to write unit tests for code I maintain so
I don't want to see this stall out. Sorry if I'm opening the can of
worms you're talking about.
^ permalink raw reply
* Using rst2pdf for PDF output - Was: Re: [PATCH 0/5] PDF output fixes
From: Mauro Carvalho Chehab @ 2019-07-18 17:46 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc
In-Reply-To: <20190713004125.6009b661@coco.lan>
Em Sat, 13 Jul 2019 00:41:25 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> Em Fri, 12 Jul 2019 19:27:05 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
>
> > Em Fri, 12 Jul 2019 14:19:21 -0600
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >
> > > Can't you just make rst2pdf work instead? :)
> >
> > Well, we can try.
Doing some tests right now with upstream version of it. I actually
created a fork:
https://github.com/mchehab/rst2pdf
basically upstream + some pending PRs + 2 fixes and a hack:
https://github.com/mchehab/rst2pdf/commits/master
> > Also, right now, rst2pdf only supports Python 2.7.
> >
> > I would wait for it to support Python 3.x before doing the actual
> > migration.
The upstream version runs on python 3.x. There are a few issues there
yet to be solved.
> There are a few issues with the quick hack to use rst2pdf. The
> enclosed one works better.
Did another improvement (see enclosed). This one should be applied
after my PDF fixes branch:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=pdf_fixes_v1
I suspect that we'll also need a patch for kfigure.py, in order for it
to support kernel-figure output.
>
> Yet, from the existing 70 books (on my experimental tree), rst2pdf breaks
> with 14 ones.
I was able to find one of the reason some books failed: rst2pdf has a
"hidden" dependency:
svglib
Without that, it will silently ignore SVG images, causing the script
to break.
Even with that, it will still break (reporting success), even on not
so complex books. For example:
$ make SPHINXDIRS=hwmon pdfdocs
writing hwmon...
[ERROR] pdfbuilder.py:150 More than 10 pages generated without content - halting layout. Likely that a flowable is too large for any frame.
Traceback (most recent call last):
File "/devel/v4l/docs_temp/sphinx_2.0.1/lib/python3.7/site-packages/rst2pdf-0.95.dev0-py3.7.egg/rst2pdf/pdfbuilder.py", line 147, in write
docwriter.write(doctree, destination)
File "/devel/v4l/docs_temp/sphinx_2.0.1/lib/python3.7/site-packages/docutils/writers/__init__.py", line 80, in write
self.translate()
File "/devel/v4l/docs_temp/sphinx_2.0.1/lib/python3.7/site-packages/rst2pdf-0.95.dev0-py3.7.egg/rst2pdf/pdfbuilder.py", line 643, in translate
compressed=self.compressed)
File "/devel/v4l/docs_temp/sphinx_2.0.1/lib/python3.7/site-packages/rst2pdf-0.95.dev0-py3.7.egg/rst2pdf/createpdf.py", line 643, in createPdf
pdfdoc.multiBuild(elements)
File "/devel/v4l/docs_temp/sphinx_2.0.1/lib/python3.7/site-packages/reportlab/platypus/doctemplate.py", line 1144, in multiBuild
self.build(tempStory, **buildKwds)
File "/devel/v4l/docs_temp/sphinx_2.0.1/lib/python3.7/site-packages/reportlab/platypus/doctemplate.py", line 1057, in build
self.handle_flowable(flowables)
File "/devel/v4l/docs_temp/sphinx_2.0.1/lib/python3.7/site-packages/rst2pdf-0.95.dev0-py3.7.egg/rst2pdf/createpdf.py", line 791, in handle_flowable
self.handle_frameEnd()
File "/devel/v4l/docs_temp/sphinx_2.0.1/lib/python3.7/site-packages/reportlab/platypus/doctemplate.py", line 709, in handle_frameEnd
self.handle_pageEnd()
File "/devel/v4l/docs_temp/sphinx_2.0.1/lib/python3.7/site-packages/reportlab/platypus/doctemplate.py", line 651, in handle_pageEnd
raise LayoutError(ident)
reportlab.platypus.doctemplate.LayoutError: More than 10 pages generated without content - halting layout. Likely that a flowable is too large for any frame.
FAILED
build succeeded.
Patch enclosed.
Thanks,
Mauro
---
[PATCH] docs: experimental: build PDF with rst2pdf
Change the logic to use rst2pdf instead of LaTeX.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 638c4c11d102..565acf6e6ee7 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -94,18 +94,22 @@ latexdocs:
ifeq ($(HAVE_PDFLATEX),0)
-pdfdocs:
+oldpdfdocs:
$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
@echo " SKIP Sphinx $@ target."
else # HAVE_PDFLATEX
-pdfdocs: latexdocs
+oldpdfdocs: latexdocs
@$(srctree)/scripts/sphinx-pre-install --version-check
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
endif # HAVE_PDFLATEX
+pdfdocs:
+ @$(srctree)/scripts/sphinx-pre-install --version-check
+ @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,pdf,$(var),pdf,$(var)))
+
epubdocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
@@ -131,6 +135,7 @@ dochelp:
@echo ' htmldocs - HTML'
@echo ' latexdocs - LaTeX'
@echo ' pdfdocs - PDF'
+ @echo ' rst2pdf - PDF, using experimental rst2pdf support'
@echo ' epubdocs - EPUB'
@echo ' xmldocs - XML'
@echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
diff --git a/Documentation/conf.py b/Documentation/conf.py
index c698f453bfab..4aa76e4b30ab 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -46,6 +46,8 @@ if (major == 1 and minor > 3) or (major > 1):
else:
extensions.append("sphinx.ext.pngmath")
+extensions.append("rst2pdf.pdfbuilder")
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -574,12 +576,15 @@ epub_exclude_files = ['search.html']
#
# See the Sphinx chapter of http://ralsina.me/static/manual.pdf
#
-# FIXME: Do not add the index file here; the result will be too big. Adding
-# multiple PDF files here actually tries to get the cross-referencing right
-# *between* PDF files.
-pdf_documents = [
- ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
-]
+
+# Add all LaTeX files to PDF documents as well
+pdf_documents = []
+for l in latex_documents:
+ doc = l[0]
+ fn = l[1].replace(".tex", "")
+ name = l[2]
+ authors = l[3]
+ pdf_documents.append((doc, fn, name, authors))
# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
# the Docs). In a normal build, these are supplied from the Makefile via command
diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index d75d70f191bc..3050136ed489 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -53,12 +53,13 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception
# Media build rules
-.PHONY: all html epub xml latex
+.PHONY: all html epub xml latex pdf
all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
html: all
epub: all
xml: all
+pdf: all
latex: $(IMGPDF) all
linkcheck:
diff --git a/Documentation/sphinx/load_config.py b/Documentation/sphinx/load_config.py
index 101e6f0b0fcf..a89d642d520e 100644
--- a/Documentation/sphinx/load_config.py
+++ b/Documentation/sphinx/load_config.py
@@ -43,6 +43,17 @@ def loadConfig(namespace):
namespace['latex_documents'] = new_latex_docs
+ # Add LaTeX files to PDF documents as well
+ pdf_documents = []
+ for l in new_latex_docs:
+ doc = l[0]
+ fn = l[1].replace(".tex", "")
+ name = l[2]
+ authors = l[3]
+ pdf_documents.append((doc, fn, name, authors))
+
+ namespace['pdf_documents'] = pdf_documents
+
# If there is an extra conf.py file, load it
if os.path.isfile(config_file):
sys.stdout.write("load additional sphinx-config: %s\n" % config_file)
diff --git a/Makefile b/Makefile
index ec21ebbd12c2..2a749335d0df 100644
--- a/Makefile
+++ b/Makefile
@@ -1564,7 +1564,7 @@ $(help-board-dirs): help-%:
# Documentation targets
# ---------------------------------------------------------------------------
DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
- linkcheckdocs dochelp refcheckdocs
+ linkcheckdocs dochelp refcheckdocs oldpdfdocs
PHONY += $(DOC_TARGETS)
$(DOC_TARGETS): scripts_basic FORCE
$(Q)$(MAKE) $(build)=Documentation $@
^ permalink raw reply related
* Re: [PATCH v2] Documentation/security-bugs: provide more information about linux-distros
From: Solar Designer @ 2019-07-18 14:14 UTC (permalink / raw)
To: Will Deacon
Cc: Sasha Levin, corbet, keescook, peterz, gregkh, tyhicks, linux-doc,
linux-kernel
In-Reply-To: <20190718094057.e4nclrw6qd2t4vw7@willie-the-truck>
On Thu, Jul 18, 2019 at 10:40:58AM +0100, Will Deacon wrote:
> On Wed, Jul 17, 2019 at 07:11:03PM -0400, Sasha Levin wrote:
> > Provide more information about how to interact with the linux-distros
> > mailing list for disclosing security bugs.
> >
> > Reference the linux-distros list policy and clarify that the reporter
> > must read and understand those policies as they differ from
> > security@kernel.org's policy.
> >
> > Suggested-by: Solar Designer <solar@openwall.com>
> > Signed-off-by: Sasha Levin <sashal@kernel.org>
> > ---
> >
> > Changes in v2:
> > - Focus more on pointing to the linux-distros wiki and policies.
> > - Remove explicit linux-distros email.
> > - Remove various explanations of linux-distros policies.
> >
> > Documentation/admin-guide/security-bugs.rst | 19 +++++++++----------
> > 1 file changed, 9 insertions(+), 10 deletions(-)
> >
> > diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst
> > index dcd6c93c7aac..380d44fd618d 100644
> > --- a/Documentation/admin-guide/security-bugs.rst
> > +++ b/Documentation/admin-guide/security-bugs.rst
> > @@ -60,16 +60,15 @@ Coordination
> > ------------
> >
> > Fixes for sensitive bugs, such as those that might lead to privilege
> > -escalations, may need to be coordinated with the private
> > -<linux-distros@vs.openwall.org> mailing list so that distribution vendors
> > -are well prepared to issue a fixed kernel upon public disclosure of the
> > -upstream fix. Distros will need some time to test the proposed patch and
> > -will generally request at least a few days of embargo, and vendor update
> > -publication prefers to happen Tuesday through Thursday. When appropriate,
> > -the security team can assist with this coordination, or the reporter can
> > -include linux-distros from the start. In this case, remember to prefix
> > -the email Subject line with "[vs]" as described in the linux-distros wiki:
> > -<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>
> > +escalations, may need to be coordinated with the private linux-distros mailing
> > +list so that distribution vendors are well prepared to issue a fixed kernel
> > +upon public disclosure of the upstream fix. Please read and follow the policies
> > +of linux-distros as specified in the linux-distros wiki page before reporting:
>
> can we add a "there" at the end of this sentence, so it can't be misread as
> implying that you must follow the linux-distros policies before reporting to
> security@kernel.org ?
Sasha's patch above and the addition suggested by Will look good to me.
Thanks!
Alexander
^ permalink raw reply
* Re: [PATCH] docs/vm: transhuge: fix typo in madvise reference
From: Mike Rapoport @ 2019-07-18 11:17 UTC (permalink / raw)
To: Jeremy Cline; +Cc: Jonathan Corbet, linux-doc, linux-kernel
In-Reply-To: <20190716144908.25843-1-jcline@redhat.com>
On Tue, Jul 16, 2019 at 10:49:08AM -0400, Jeremy Cline wrote:
> Fix an off-by-one typo in the transparent huge pages admin
> documentation.
>
> Signed-off-by: Jeremy Cline <jcline@redhat.com>
Acked-by: Mike Rapoport <rppt@linux.ibm.com>
> ---
> Documentation/admin-guide/mm/transhuge.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst
> index 7ab93a8404b9..bd5714547cee 100644
> --- a/Documentation/admin-guide/mm/transhuge.rst
> +++ b/Documentation/admin-guide/mm/transhuge.rst
> @@ -53,7 +53,7 @@ disabled, there is ``khugepaged`` daemon that scans memory and
> collapses sequences of basic pages into huge pages.
>
> The THP behaviour is controlled via :ref:`sysfs <thp_sysfs>`
> -interface and using madivse(2) and prctl(2) system calls.
> +interface and using madvise(2) and prctl(2) system calls.
>
> Transparent Hugepage Support maximizes the usefulness of free memory
> if compared to the reservation approach of hugetlbfs by allowing all
> --
> 2.21.0
>
--
Sincerely yours,
Mike.
^ permalink raw reply
* Re: [PATCH v2] Documentation/security-bugs: provide more information about linux-distros
From: Will Deacon @ 2019-07-18 9:40 UTC (permalink / raw)
To: Sasha Levin
Cc: corbet, solar, keescook, peterz, gregkh, tyhicks, linux-doc,
linux-kernel
In-Reply-To: <20190717231103.13949-1-sashal@kernel.org>
On Wed, Jul 17, 2019 at 07:11:03PM -0400, Sasha Levin wrote:
> Provide more information about how to interact with the linux-distros
> mailing list for disclosing security bugs.
>
> Reference the linux-distros list policy and clarify that the reporter
> must read and understand those policies as they differ from
> security@kernel.org's policy.
>
> Suggested-by: Solar Designer <solar@openwall.com>
> Signed-off-by: Sasha Levin <sashal@kernel.org>
> ---
>
> Changes in v2:
> - Focus more on pointing to the linux-distros wiki and policies.
> - Remove explicit linux-distros email.
> - Remove various explanations of linux-distros policies.
>
> Documentation/admin-guide/security-bugs.rst | 19 +++++++++----------
> 1 file changed, 9 insertions(+), 10 deletions(-)
>
> diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst
> index dcd6c93c7aac..380d44fd618d 100644
> --- a/Documentation/admin-guide/security-bugs.rst
> +++ b/Documentation/admin-guide/security-bugs.rst
> @@ -60,16 +60,15 @@ Coordination
> ------------
>
> Fixes for sensitive bugs, such as those that might lead to privilege
> -escalations, may need to be coordinated with the private
> -<linux-distros@vs.openwall.org> mailing list so that distribution vendors
> -are well prepared to issue a fixed kernel upon public disclosure of the
> -upstream fix. Distros will need some time to test the proposed patch and
> -will generally request at least a few days of embargo, and vendor update
> -publication prefers to happen Tuesday through Thursday. When appropriate,
> -the security team can assist with this coordination, or the reporter can
> -include linux-distros from the start. In this case, remember to prefix
> -the email Subject line with "[vs]" as described in the linux-distros wiki:
> -<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>
> +escalations, may need to be coordinated with the private linux-distros mailing
> +list so that distribution vendors are well prepared to issue a fixed kernel
> +upon public disclosure of the upstream fix. Please read and follow the policies
> +of linux-distros as specified in the linux-distros wiki page before reporting:
can we add a "there" at the end of this sentence, so it can't be misread as
implying that you must follow the linux-distros policies before reporting to
security@kernel.org ?
Will
^ permalink raw reply
* Re: [PATCH v6 0/6] KASan for arm
From: Arnd Bergmann @ 2019-07-18 7:51 UTC (permalink / raw)
To: Florian Fainelli
Cc: Linus Walleij, Florian Fainelli, Mark Rutland, Alexandre Belloni,
Michal Hocko, Julien Thierry, Catalin Marinas,
linux-kernel@vger.kernel.org, David Howells, Masahiro Yamada,
Andrey Ryabinin, Alexander Potapenko, kvmarm, Jonathan Corbet,
Abbott Liu, Daniel Lezcano, Russell King, kasan-dev,
bcm-kernel-feedback-list, Dmitry Vyukov, Geert Uytterhoeven,
drjones, Vladimir Murzin, Kees Cook, Marc Zyngier, Andre Przywara,
philip, Jinbum Park, Thomas Gleixner, Linux ARM, Nicolas Pitre,
Greg KH, Ard Biesheuvel, Linux Doc Mailing List, Christoffer Dall,
Rob Landley, Philippe Ombredanne, Andrew Morton, Thomas Garnier,
Kirill A . Shutemov
In-Reply-To: <0ba50ae2-be09-f633-ab1f-860e8b053882@broadcom.com>
On Thu, Jul 11, 2019 at 7:00 PM Florian Fainelli
<florian.fainelli@broadcom.com> wrote:
> On 7/2/19 2:06 PM, Linus Walleij wrote:
>
> Great, thanks a lot for taking a look. FYI, I will be on holiday from
> July 19th till August 12th, if you think you have more feedback between
> now and then, I can try to pick it up and submit a v7 with that feedback
> addressed, or it will happen when I return, or you can pick it up if you
> refer, all options are possible!
>
> @Arnd, should we squash your patches in as well?
Yes, please do. I don't remember if I sent you all of them already,
here is the list of patches that I have applied locally on top of your
series to get a clean randconfig build:
123c3262f872 KASAN: push back KASAN_STACK to clang-10
d63dd9e2afd9 [HACK] ARM: disable KASAN+XIP_KERNEL
879eb3c22240 kasan: increase 32-bit stack frame warning limit
053555034bdf kasan: disable CONFIG_KASAN_STACK with clang on arm32
6c1a78a448c2 ARM: fix kasan link failures
Arnd
^ permalink raw reply
* [PATCH 2/2] doc:it_IT: rephrase statement
From: Federico Vaga @ 2019-07-18 7:47 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Federico Vaga
The statement sounds more like a literal translation
Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
Documentation/translations/it_IT/doc-guide/sphinx.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst
index d9ee4b1f098f..f1ad4504b734 100644
--- a/Documentation/translations/it_IT/doc-guide/sphinx.rst
+++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst
@@ -242,9 +242,9 @@ del kernel:
* Per inserire blocchi di testo con caratteri a dimensione fissa (codici di
esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario
evidenziare la sintassi, specialmente per piccoli frammenti; invece,
- utilizzate ``.. code-block:: <language>`` per blocchi di più lunghi che
- potranno beneficiare dell'avere la sintassi evidenziata. Per un breve pezzo
- di codice da inserire nel testo, usate \`\`.
+ utilizzate ``.. code-block:: <language>`` per blocchi più lunghi che
+ beneficeranno della sintassi evidenziata. Per un breve pezzo di codice da
+ inserire nel testo, usate \`\`.
Il dominio C
--
2.21.0
^ permalink raw reply related
* [PATCH 1/2] doc:it_IT: align translation to mainline
From: Federico Vaga @ 2019-07-18 7:47 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Federico Vaga
The patch translates the following patches in Italian:
d9d7c0c497b8 docs: Note that :c:func: should no longer be used
83e8b971f81c sphinx.rst: Add note about code snippets embedded in the text
cca5e0b8a430 Documentation: PGP: update for newer HW devices
Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
.../translations/it_IT/doc-guide/sphinx.rst | 17 +++++++------
.../it_IT/process/maintainer-pgp-guide.rst | 25 ++++++++++++-------
2 files changed, 26 insertions(+), 16 deletions(-)
diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst
index 1739cba8863e..d9ee4b1f098f 100644
--- a/Documentation/translations/it_IT/doc-guide/sphinx.rst
+++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst
@@ -243,7 +243,8 @@ del kernel:
esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario
evidenziare la sintassi, specialmente per piccoli frammenti; invece,
utilizzate ``.. code-block:: <language>`` per blocchi di più lunghi che
- potranno beneficiare dell'avere la sintassi evidenziata.
+ potranno beneficiare dell'avere la sintassi evidenziata. Per un breve pezzo
+ di codice da inserire nel testo, usate \`\`.
Il dominio C
@@ -267,12 +268,14 @@ molto comune come ``open`` o ``ioctl``:
Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo
riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce
-nell'indice cambia in ``VIDIOC_LOG_STATUS`` e si potrà quindi fare riferimento
-a questa funzione scrivendo:
-
-.. code-block:: rst
-
- :c:func:`VIDIOC_LOG_STATUS`
+nell'indice cambia in ``VIDIOC_LOG_STATUS``.
+
+Notate che per una funzione non c'è bisogno di usare ``c:func:`` per generarne
+i riferimenti nella documentazione. Grazie a qualche magica estensione a
+Sphinx, il sistema di generazione della documentazione trasformerà
+automaticamente un riferimento ad una ``funzione()`` in un riferimento
+incrociato quando questa ha una voce nell'indice. Se trovate degli usi di
+``c:func:`` nella documentazione del kernel, sentitevi liberi di rimuoverli.
Tabelle a liste
diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst
index 276db0e37f43..118fb4153e8f 100644
--- a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst
+++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst
@@ -248,7 +248,10 @@ possano ricevere la vostra nuova sottochiave::
kernel.
Se per qualche ragione preferite rimanere con sottochiavi RSA, nel comando
- precedente, sostituite "ed25519" con "rsa2048".
+ precedente, sostituite "ed25519" con "rsa2048". In aggiunta, se avete
+ intenzione di usare un dispositivo hardware che non supporta le chiavi
+ ED25519 ECC, come la Nitrokey Pro o la Yubikey, allora dovreste usare
+ "nistp256" al posto di "ed25519".
Copia di riserva della chiave primaria per gestire il recupero da disastro
--------------------------------------------------------------------------
@@ -449,23 +452,27 @@ implementi le funzionalità delle smartcard. Sul mercato ci sono diverse
soluzioni disponibili:
- `Nitrokey Start`_: è Open hardware e Free Software, è basata sul progetto
- `GnuK`_ della FSIJ. Ha il supporto per chiavi ECC, ma meno funzionalità di
- sicurezza (come la resistenza alla manomissione o alcuni attacchi ad un
- canale laterale).
+ `GnuK`_ della FSIJ. Questo è uno dei pochi dispositivi a supportare le chiavi
+ ECC ED25519, ma offre meno funzionalità di sicurezza (come la resistenza
+ alla manomissione o alcuni attacchi ad un canale laterale).
- `Nitrokey Pro`_: è simile alla Nitrokey Start, ma è più resistente alla
- manomissione e offre più funzionalità di sicurezza, ma l'ECC.
-- `Yubikey 4`_: l'hardware e il software sono proprietari, ma è più economica
+ manomissione e offre più funzionalità di sicurezza. La Pro 2 supporta la
+ crittografia ECC (NISTP).
+- `Yubikey 5`_: l'hardware e il software sono proprietari, ma è più economica
della Nitrokey Pro ed è venduta anche con porta USB-C il che è utile con i
computer portatili più recenti. In aggiunta, offre altre funzionalità di
- sicurezza come FIDO, U2F, ma non l'ECC
+ sicurezza come FIDO, U2F, e ora supporta anche le chiavi ECC (NISTP)
`Su LWN c'è una buona recensione`_ dei modelli elencati qui sopra e altri.
+La scelta dipenderà dal costo, dalla disponibilità nella vostra area
+geografica e vostre considerazioni sull'hardware aperto/proprietario.
+
Se volete usare chiavi ECC, la vostra migliore scelta sul mercato è la
Nitrokey Start.
.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6
-.. _`Nitrokey Pro`: https://shop.nitrokey.com/shop/product/nitrokey-pro-3
-.. _`Yubikey 4`: https://www.yubico.com/product/yubikey-4-series/
+.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3
+.. _`Yubikey 5`: https://www.yubico.com/product/yubikey-5-overview/
.. _Gnuk: http://www.fsij.org/doc-gnuk/
.. _`Su LWN c'è una buona recensione`: https://lwn.net/Articles/736231/
--
2.21.0
^ permalink raw reply related
* [PATCH v2] Documentation/security-bugs: provide more information about linux-distros
From: Sasha Levin @ 2019-07-17 23:11 UTC (permalink / raw)
To: corbet, solar
Cc: will, keescook, peterz, gregkh, tyhicks, linux-doc, linux-kernel,
Sasha Levin
Provide more information about how to interact with the linux-distros
mailing list for disclosing security bugs.
Reference the linux-distros list policy and clarify that the reporter
must read and understand those policies as they differ from
security@kernel.org's policy.
Suggested-by: Solar Designer <solar@openwall.com>
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
Changes in v2:
- Focus more on pointing to the linux-distros wiki and policies.
- Remove explicit linux-distros email.
- Remove various explanations of linux-distros policies.
Documentation/admin-guide/security-bugs.rst | 19 +++++++++----------
1 file changed, 9 insertions(+), 10 deletions(-)
diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst
index dcd6c93c7aac..380d44fd618d 100644
--- a/Documentation/admin-guide/security-bugs.rst
+++ b/Documentation/admin-guide/security-bugs.rst
@@ -60,16 +60,15 @@ Coordination
------------
Fixes for sensitive bugs, such as those that might lead to privilege
-escalations, may need to be coordinated with the private
-<linux-distros@vs.openwall.org> mailing list so that distribution vendors
-are well prepared to issue a fixed kernel upon public disclosure of the
-upstream fix. Distros will need some time to test the proposed patch and
-will generally request at least a few days of embargo, and vendor update
-publication prefers to happen Tuesday through Thursday. When appropriate,
-the security team can assist with this coordination, or the reporter can
-include linux-distros from the start. In this case, remember to prefix
-the email Subject line with "[vs]" as described in the linux-distros wiki:
-<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>
+escalations, may need to be coordinated with the private linux-distros mailing
+list so that distribution vendors are well prepared to issue a fixed kernel
+upon public disclosure of the upstream fix. Please read and follow the policies
+of linux-distros as specified in the linux-distros wiki page before reporting:
+<https://oss-security.openwall.org/wiki/mailing-lists/distros>. When
+appropriate, the security team can assist with this coordination, or the
+reporter can include linux-distros from the start. In this case, remember to
+prefix the email Subject line with "[vs]" as described in the linux-distros
+wiki.
CVE assignment
--------------
--
2.20.1
^ permalink raw reply related
* Re: [PATCH v5 02/11] of/platform: Add functional dependency link from DT bindings
From: Saravana Kannan @ 2019-07-17 20:38 UTC (permalink / raw)
To: Rob Herring
Cc: Mark Rutland, Greg Kroah-Hartman, Rafael J. Wysocki, Frank Rowand,
Jonathan Corbet,
open list:OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS,
linux-kernel@vger.kernel.org, David Collins, Android Kernel Team,
Linux Doc Mailing List
In-Reply-To: <CAL_Jsq+Dfm8ng1OVcB+1N2ack05v8+u1VydfxM4Ukefqd9XK2w@mail.gmail.com>
On Wed, Jul 17, 2019 at 7:35 AM Rob Herring <robh+dt@kernel.org> wrote:
>
> On Tue, Jul 16, 2019 at 5:54 PM Saravana Kannan <saravanak@google.com> wrote:
> >
> > On Tue, Jul 16, 2019 at 4:43 PM Rob Herring <robh+dt@kernel.org> wrote:
> > >
> > > On Fri, Jul 12, 2019 at 5:52 PM Saravana Kannan <saravanak@google.com> wrote:
> > > >
> > > > Add device-links after the devices are created (but before they are
> > > > probed) by looking at common DT bindings like clocks and
> > > > interconnects.
> > > >
> > > > Automatically adding device-links for functional dependencies at the
> > > > framework level provides the following benefits:
> > > >
> > > > - Optimizes device probe order and avoids the useless work of
> > > > attempting probes of devices that will not probe successfully
> > > > (because their suppliers aren't present or haven't probed yet).
> > > >
> > > > For example, in a commonly available mobile SoC, registering just
> > > > one consumer device's driver at an initcall level earlier than the
> > > > supplier device's driver causes 11 failed probe attempts before the
> > > > consumer device probes successfully. This was with a kernel with all
> > > > the drivers statically compiled in. This problem gets a lot worse if
> > > > all the drivers are loaded as modules without direct symbol
> > > > dependencies.
> > > >
> > > > - Supplier devices like clock providers, interconnect providers, etc
> > > > need to keep the resources they provide active and at a particular
> > > > state(s) during boot up even if their current set of consumers don't
> > > > request the resource to be active. This is because the rest of the
> > > > consumers might not have probed yet and turning off the resource
> > > > before all the consumers have probed could lead to a hang or
> > > > undesired user experience.
> > > >
> > > > Some frameworks (Eg: regulator) handle this today by turning off
> > > > "unused" resources at late_initcall_sync and hoping all the devices
> > > > have probed by then. This is not a valid assumption for systems with
> > > > loadable modules. Other frameworks (Eg: clock) just don't handle
> > > > this due to the lack of a clear signal for when they can turn off
> > > > resources. This leads to downstream hacks to handle cases like this
> > > > that can easily be solved in the upstream kernel.
> > > >
> > > > By linking devices before they are probed, we give suppliers a clear
> > > > count of the number of dependent consumers. Once all of the
> > > > consumers are active, the suppliers can turn off the unused
> > > > resources without making assumptions about the number of consumers.
> > > >
> > > > By default we just add device-links to track "driver presence" (probe
> > > > succeeded) of the supplier device. If any other functionality provided
> > > > by device-links are needed, it is left to the consumer/supplier
> > > > devices to change the link when they probe.
> > > >
> > > > Signed-off-by: Saravana Kannan <saravanak@google.com>
> > > > ---
> > > > .../admin-guide/kernel-parameters.txt | 5 ++
> > > > drivers/of/platform.c | 57 +++++++++++++++++++
> > > > 2 files changed, 62 insertions(+)
> > > >
> > > > diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> > > > index 138f6664b2e2..109b4310844f 100644
> > > > --- a/Documentation/admin-guide/kernel-parameters.txt
> > > > +++ b/Documentation/admin-guide/kernel-parameters.txt
> > > > @@ -3141,6 +3141,11 @@
> > > > This can be set from sysctl after boot.
> > > > See Documentation/sysctl/vm.txt for details.
> > > >
> > > > + of_devlink [KNL] Make device links from common DT bindings. Useful
> > > > + for optimizing probe order and making sure resources
> > > > + aren't turned off before the consumer devices have
> > > > + probed.
> > > > +
> > > > ohci1394_dma=early [HW] enable debugging via the ohci1394 driver.
> > > > See Documentation/debugging-via-ohci1394.txt for more
> > > > info.
> > > > diff --git a/drivers/of/platform.c b/drivers/of/platform.c
> > > > index 04ad312fd85b..0930f9f89571 100644
> > > > --- a/drivers/of/platform.c
> > > > +++ b/drivers/of/platform.c
> > > > @@ -509,6 +509,62 @@ int of_platform_default_populate(struct device_node *root,
> > > > }
> > > > EXPORT_SYMBOL_GPL(of_platform_default_populate);
> > > >
> > > > +static int of_link_binding(struct device *dev,
> > > > + const char *binding, const char *cell)
> > > > +{
> > > > + struct of_phandle_args sup_args;
> > > > + struct platform_device *sup_dev;
> > > > + unsigned int i = 0, links = 0;
> > > > + u32 dl_flags = DL_FLAG_AUTOPROBE_CONSUMER;
> > > > +
> > > > + while (!of_parse_phandle_with_args(dev->of_node, binding, cell, i,
> > > > + &sup_args)) {
> > > > + i++;
> > > > + sup_dev = of_find_device_by_node(sup_args.np);
> > > > + of_node_put(sup_args.np);
> > > > + if (!sup_dev)
> > > > + continue;
> > > > + if (device_link_add(dev, &sup_dev->dev, dl_flags))
> > > > + links++;
> > > > + put_device(&sup_dev->dev);
> > > > + }
> > > > + if (links < i)
> > > > + return -ENODEV;
> > > > + return 0;
> > > > +}
> > > > +
> > > > +static bool of_devlink;
> > > > +core_param(of_devlink, of_devlink, bool, 0);
> > > > +
> > > > +/*
> > > > + * List of bindings and their cell names (use NULL if no cell names) from which
> > > > + * device links need to be created.
> > > > + */
> > > > +static const char * const link_bindings[] = {
> > > > + "clocks", "#clock-cells",
> > > > + "interconnects", "#interconnect-cells",
> > > > +};
> > > > +
> > > > +static int of_link_to_suppliers(struct device *dev)
> > > > +{
> > > > + unsigned int i = 0;
> > > > + bool done = true;
> > > > +
> > > > + if (!of_devlink)
> > > > + return 0;
> > > > + if (unlikely(!dev->of_node))
> > > > + return 0;
> > > > +
> > > > + for (i = 0; i < ARRAY_SIZE(link_bindings) / 2; i++)
> > > > + if (of_link_binding(dev, link_bindings[i * 2],
> > > > + link_bindings[i * 2 + 1]))
> > > > + done = false;
> > >
> > > Given the pending addition of regulators I think this should be
> > > structured a bit differently so that we abstract out the matching and
> > > phandle look-up so there's a clean separation of binding specifics.
> > > It's kind of messy with 2 patterns to parse already and if we added a
> > > 3rd? I would iterate over the properties as you do for regulators in
> > > both cases and for each property call a binding specific match
> > > function. The common pattern can of course be a common function. Let
> > > me know if that makes sense. If not I can try to flesh it out some
> > > more.
> >
> > I've added regulator support in this series and I've refactored this
> > code as I went along. I fully expect to squash some of the refactors
> > once the final result of the series is acceptable.
>
> It would be easier to review the final result than incremental changes
> which change the prior patches especially if the latter patches are
> ultimately required.
>
> > It's not clear to me if you got to the end of the series and still
> > think the final result needs to be refactored. Let me know what you
> > think about this towards the end of the series and I can clean it up
> > if you still think it needs some clean up.
>
> I probably should have replied on the regulator addition, but yes,
> looking at that is what prompted my concerns here.
Sounds good. Let me refactor the series and send it out again. Btw, if
you have other issues you noticed, I'd be happy to fix those too
before sending out the v6 of the series again.
-Saravana
^ permalink raw reply
* Re: [RFC v1 0/4] arm64: MMU enabled kexec kernel relocation
From: Pavel Tatashin @ 2019-07-17 19:13 UTC (permalink / raw)
To: James Morse
Cc: James Morris, Sasha Levin, Eric W. Biederman, kexec mailing list,
LKML, Jonathan Corbet, Catalin Marinas, will,
Linux Doc Mailing List, Linux ARM
In-Reply-To: <4c8a3a11-adc2-efa4-f765-6be338546ae4@arm.com>
Hi James,
Thank you for taking a look at this work.
> After a quick skim:
>
> This will map 'nomap' regions of memory with cacheable attributes. This is a non-starter.
> These regions were described by firmware as having content that was/is written with
> different attributes. The attributes must match whenever it is mapped, otherwise we have a
> loss of coherency. Mapping this stuff as cacheable means the CPU can prefetch it into the
> cache whenever it likes.
> It may be important that we do not ever map some of these regions, even though its
> described as memory. On AMD-Seattle the bottom page of memory is reserved by firmware for
> its own use; it is made secure-only, and any access causes an
> external-abort/machine-check. UEFI describes this as 'Reserved', and we preserve this in
> the kernel as 'nomap'. The equivalent DT support uses memreserve, possibly with the
> 'nomap' attribute.
>
> Mapping a 'new'/unknown region with cacheable attributes can never be safe, even if we
> trusted kexec-tool to only write the kernel to memory. The host may be using a bigger page
> size causing more memory to become cacheable than was intended.
> Linux's EFI support rounds the UEFI memory map to the largest support page size, (and
> winges about firmware bugs).
> If we're allowing kexec to load images in a region not described as IORESOURCE_SYSTEM_RAM,
> that is a bug we should fix.
We are allowing this. If you consider this to be a bug, I will fix it,
and this will actually simplify the idmap page table. User will
receive an error during kexec load if a request is made to load into
!IORESOURCE_SYSTEM_RAM region.
>
> The only way to do this properly is to copy the linear mapping. The arch code has lots of
> complex code to generate it correctly at boot, we do not want to duplicate it.
> (this is why hibernate copies the linear mapping)
As I understand, you would like to take a copy of idmap page table,
and add entries only for segment
sources and destinations into the new page table?
If so, there is a slight problem: arch hook machine_kexec_prepare() is
called prior to loading segments from userland. We can solve this by
adding another hook that is called after kimage_terminate().
> These patches do not remove the running page tables from TTBR1. As you overwrite the live
> page tables you will corrupt the state of the CPU. The page-table walker may access things
> that aren't memory, cache memory that shouldn't be cached (see above), and allocate
> conflicting entries in the TLB.
Indeed. However, I was following what is done in create_safe_exec_page():
https://soleen.com/source/xref/linux/arch/arm64/kernel/hibernate.c?r=af873fce#263
ttbr1 is not removed there. Am I missing something, or is not yet
configured there?
I will set ttbr1 to zero page.
> You cannot use the mm page table helpers to build an idmap on arm64. The mm page table
> helpers have a compile-time VA_BITS, and we support systems where there is no memory below
> 1<<VA_BITS. (crazy huh!). Picking on AMD-Seattle again: if you boot a 4K 39bit VA kernel,
> the idmap will have more page table levels than the page table helpers can build. This is
> why there are special helpers to load the idmap, and twiddle TCR_EL1.T0SZ.
> You already need to copy the linear-map, so using an idmap is extra work. You want to work
> with linear-map addresses, you probably need to add the field to the appropriate structure.
OK. Makes sense. I will do the way hibernate setup this table. I was
indeed following x86, hoping that eventually it would be possible to
unite: kasan, hibernate, and kexec implementation of this page table.
>
> The kexec relocation code still runs at EL2. You can't use a copy of the linear map here
> as there is only one TTBR on v8.0, and you'd need to setup EL2 as its been torn back to
> the hyp-stub.
As I understand normally on baremetal kexec runs at EL1 not EL2. On my
machine is_kernel_in_hyp_mode() == false in cpu_soft_restart.
This is the reason hibernate posts EL2 in a holding pen while it rewrites
> all of memory, then calls back to fixup EL2. Keeping the rewrite phase at EL1 means it
> doesn't need independently tweaking/testing. You need to do something similar, either
> calling EL2 to start the new image, or disabling the MMU at EL1 to start the new image there.
OK, I will study how hibernate does this. I was thinking that if we
are running in EL2 we can simply configure TTBR0_EL2 instead of
TTBR0_EL1. But, I need to understand this better.
>
> You will need to alter the relocation code to do nothing for kdump, as no relocation is
> required and building page-tables is extra work where the kernel may croak, preventing us
> from reaching kdump.
Yes, I was planning to do nothing for kdump, which involves not
allocating page table. It is not part of the current patchest, as the
current series is not ready.
>
> Finally, having this independent idmap machinery isn't desirable from a maintenance
> perspective. Please start with the hibernate code that already solves a very similar
> problem, as it already has most of these problems covered.
OK.
> > This patch series works in terms, that I can kexec-reboot both in QEMU
>
> I wouldn't expect Qemu's emulation of the MMU and caches to be performance accurate.
I am not measuring performance in QEMU, I use it for
development/verification only. The performance is measured on real
hardware only.
>
> > and on a physical machine. However, I do not see performance improvement
> > during relocation. The performance is just as slow as before with disabled
> > caches.
>
> > Am I missing something? Perhaps, there is some flag that I should also
> > enable in page table? Please provide me with any suggestions.
>
> Some information about the physical machine you tested this on would help.
> I'm guessing its v8.0, and booted at EL2....
I am using Broadcom's Stingray SoC. Because is_kernel_in_hyp_mode()
returns false, I believe it is EL1. How can I boot it at EL2?
So, I am still confused why I do not see performance improvements
during relocation on this machine. Any theories?
Thank you,
Pasha
^ permalink raw reply
* Re: [RFC v1 0/4] arm64: MMU enabled kexec kernel relocation
From: James Morse @ 2019-07-17 17:51 UTC (permalink / raw)
To: Pavel Tatashin
Cc: jmorris, sashal, ebiederm, kexec, linux-kernel, corbet,
catalin.marinas, will, linux-doc, linux-arm-kernel
In-Reply-To: <20190716165641.6990-1-pasha.tatashin@soleen.com>
Hi Pavel,
On 16/07/2019 17:56, Pavel Tatashin wrote:
> Added identity mapped page table, and keep MMU enabled while
> kernel is being relocated from sparse pages to the final
> destination during kexec.
The 'tl;dr' version of this: I strongly urge you to start with the hibernate code that
already covers all these known corner cases. x86 was not a good starting point.
After a quick skim:
This will map 'nomap' regions of memory with cacheable attributes. This is a non-starter.
These regions were described by firmware as having content that was/is written with
different attributes. The attributes must match whenever it is mapped, otherwise we have a
loss of coherency. Mapping this stuff as cacheable means the CPU can prefetch it into the
cache whenever it likes.
It may be important that we do not ever map some of these regions, even though its
described as memory. On AMD-Seattle the bottom page of memory is reserved by firmware for
its own use; it is made secure-only, and any access causes an
external-abort/machine-check. UEFI describes this as 'Reserved', and we preserve this in
the kernel as 'nomap'. The equivalent DT support uses memreserve, possibly with the
'nomap' attribute.
Mapping a 'new'/unknown region with cacheable attributes can never be safe, even if we
trusted kexec-tool to only write the kernel to memory. The host may be using a bigger page
size causing more memory to become cacheable than was intended.
Linux's EFI support rounds the UEFI memory map to the largest support page size, (and
winges about firmware bugs).
If we're allowing kexec to load images in a region not described as IORESOURCE_SYSTEM_RAM,
that is a bug we should fix.
The only way to do this properly is to copy the linear mapping. The arch code has lots of
complex code to generate it correctly at boot, we do not want to duplicate it.
(this is why hibernate copies the linear mapping)
These patches do not remove the running page tables from TTBR1. As you overwrite the live
page tables you will corrupt the state of the CPU. The page-table walker may access things
that aren't memory, cache memory that shouldn't be cached (see above), and allocate
conflicting entries in the TLB.
You cannot use the mm page table helpers to build an idmap on arm64. The mm page table
helpers have a compile-time VA_BITS, and we support systems where there is no memory below
1<<VA_BITS. (crazy huh!). Picking on AMD-Seattle again: if you boot a 4K 39bit VA kernel,
the idmap will have more page table levels than the page table helpers can build. This is
why there are special helpers to load the idmap, and twiddle TCR_EL1.T0SZ.
You already need to copy the linear-map, so using an idmap is extra work. You want to work
with linear-map addresses, you probably need to add the field to the appropriate structure.
The kexec relocation code still runs at EL2. You can't use a copy of the linear map here
as there is only one TTBR on v8.0, and you'd need to setup EL2 as its been torn back to
the hyp-stub. This is the reason hibernate posts EL2 in a holding pen while it rewrites
all of memory, then calls back to fixup EL2. Keeping the rewrite phase at EL1 means it
doesn't need independently tweaking/testing. You need to do something similar, either
calling EL2 to start the new image, or disabling the MMU at EL1 to start the new image there.
You will need to alter the relocation code to do nothing for kdump, as no relocation is
required and building page-tables is extra work where the kernel may croak, preventing us
from reaching kdump.
Finally, having this independent idmap machinery isn't desirable from a maintenance
perspective. Please start with the hibernate code that already solves a very similar
problem, as it already has most of these problems covered.
> This patch series works in terms, that I can kexec-reboot both in QEMU
I wouldn't expect Qemu's emulation of the MMU and caches to be performance accurate.
> and on a physical machine. However, I do not see performance improvement
> during relocation. The performance is just as slow as before with disabled
> caches.
> Am I missing something? Perhaps, there is some flag that I should also
> enable in page table? Please provide me with any suggestions.
Some information about the physical machine you tested this on would help.
I'm guessing its v8.0, and booted at EL2....
Thanks,
James
^ permalink raw reply
* Re: [PATCH v4 13/15] docs: ABI: testing: make the files compatible with ReST output
From: Jonathan Cameron @ 2019-07-17 16:13 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: gregkh, Rafael J. Wysocki, Len Brown, Jonathan Cameron,
Hartmut Knaack, Lars-Peter Clausen, Peter Meerwald-Stadler,
Peter Rosin, Benson Leung, Enric Balletbo i Serra, Guenter Roeck,
Maxime Coquelin, Alexandre Torgue, Fabrice Gasnier,
Frederic Barrat, Andrew Donnellan, Sebastian Reichel,
Heikki Krogerus, Boris Ostrovsky, Juergen Gross,
Stefano Stabellini, Mike Kravetz, Nicolas Ferre,
Alexandre Belloni, Ludovic Desroches, Richard Cochran,
Jonathan Corbet, linux-acpi, linux-iio, linux-stm32,
linux-arm-kernel, linuxppc-dev, linux-pm, linux-usb, xen-devel,
linux-mm, netdev, linux-doc
In-Reply-To: <88d15fa38167e3f2e73e65e1c1a1f39bca0267b4.1563365880.git.mchehab+samsung@kernel.org>
On Wed, 17 Jul 2019 09:28:17 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Some files over there won't parse well by Sphinx.
>
> Fix them.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Hi Mauro,
Does feel like this one should perhaps have been broken up a touch!
For the IIO ones I've eyeballed it rather than testing the results
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
^ permalink raw reply
* Re: [PATCH v5 02/11] of/platform: Add functional dependency link from DT bindings
From: Rob Herring @ 2019-07-17 14:35 UTC (permalink / raw)
To: Saravana Kannan
Cc: Mark Rutland, Greg Kroah-Hartman, Rafael J. Wysocki, Frank Rowand,
Jonathan Corbet,
open list:OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS,
linux-kernel@vger.kernel.org, David Collins, Android Kernel Team,
Linux Doc Mailing List
In-Reply-To: <CAGETcx-5ykD=9X1Lo2-G+T5uokFncbY2FmiJM8eZrgQ9JaBgxw@mail.gmail.com>
On Tue, Jul 16, 2019 at 5:54 PM Saravana Kannan <saravanak@google.com> wrote:
>
> On Tue, Jul 16, 2019 at 4:43 PM Rob Herring <robh+dt@kernel.org> wrote:
> >
> > On Fri, Jul 12, 2019 at 5:52 PM Saravana Kannan <saravanak@google.com> wrote:
> > >
> > > Add device-links after the devices are created (but before they are
> > > probed) by looking at common DT bindings like clocks and
> > > interconnects.
> > >
> > > Automatically adding device-links for functional dependencies at the
> > > framework level provides the following benefits:
> > >
> > > - Optimizes device probe order and avoids the useless work of
> > > attempting probes of devices that will not probe successfully
> > > (because their suppliers aren't present or haven't probed yet).
> > >
> > > For example, in a commonly available mobile SoC, registering just
> > > one consumer device's driver at an initcall level earlier than the
> > > supplier device's driver causes 11 failed probe attempts before the
> > > consumer device probes successfully. This was with a kernel with all
> > > the drivers statically compiled in. This problem gets a lot worse if
> > > all the drivers are loaded as modules without direct symbol
> > > dependencies.
> > >
> > > - Supplier devices like clock providers, interconnect providers, etc
> > > need to keep the resources they provide active and at a particular
> > > state(s) during boot up even if their current set of consumers don't
> > > request the resource to be active. This is because the rest of the
> > > consumers might not have probed yet and turning off the resource
> > > before all the consumers have probed could lead to a hang or
> > > undesired user experience.
> > >
> > > Some frameworks (Eg: regulator) handle this today by turning off
> > > "unused" resources at late_initcall_sync and hoping all the devices
> > > have probed by then. This is not a valid assumption for systems with
> > > loadable modules. Other frameworks (Eg: clock) just don't handle
> > > this due to the lack of a clear signal for when they can turn off
> > > resources. This leads to downstream hacks to handle cases like this
> > > that can easily be solved in the upstream kernel.
> > >
> > > By linking devices before they are probed, we give suppliers a clear
> > > count of the number of dependent consumers. Once all of the
> > > consumers are active, the suppliers can turn off the unused
> > > resources without making assumptions about the number of consumers.
> > >
> > > By default we just add device-links to track "driver presence" (probe
> > > succeeded) of the supplier device. If any other functionality provided
> > > by device-links are needed, it is left to the consumer/supplier
> > > devices to change the link when they probe.
> > >
> > > Signed-off-by: Saravana Kannan <saravanak@google.com>
> > > ---
> > > .../admin-guide/kernel-parameters.txt | 5 ++
> > > drivers/of/platform.c | 57 +++++++++++++++++++
> > > 2 files changed, 62 insertions(+)
> > >
> > > diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> > > index 138f6664b2e2..109b4310844f 100644
> > > --- a/Documentation/admin-guide/kernel-parameters.txt
> > > +++ b/Documentation/admin-guide/kernel-parameters.txt
> > > @@ -3141,6 +3141,11 @@
> > > This can be set from sysctl after boot.
> > > See Documentation/sysctl/vm.txt for details.
> > >
> > > + of_devlink [KNL] Make device links from common DT bindings. Useful
> > > + for optimizing probe order and making sure resources
> > > + aren't turned off before the consumer devices have
> > > + probed.
> > > +
> > > ohci1394_dma=early [HW] enable debugging via the ohci1394 driver.
> > > See Documentation/debugging-via-ohci1394.txt for more
> > > info.
> > > diff --git a/drivers/of/platform.c b/drivers/of/platform.c
> > > index 04ad312fd85b..0930f9f89571 100644
> > > --- a/drivers/of/platform.c
> > > +++ b/drivers/of/platform.c
> > > @@ -509,6 +509,62 @@ int of_platform_default_populate(struct device_node *root,
> > > }
> > > EXPORT_SYMBOL_GPL(of_platform_default_populate);
> > >
> > > +static int of_link_binding(struct device *dev,
> > > + const char *binding, const char *cell)
> > > +{
> > > + struct of_phandle_args sup_args;
> > > + struct platform_device *sup_dev;
> > > + unsigned int i = 0, links = 0;
> > > + u32 dl_flags = DL_FLAG_AUTOPROBE_CONSUMER;
> > > +
> > > + while (!of_parse_phandle_with_args(dev->of_node, binding, cell, i,
> > > + &sup_args)) {
> > > + i++;
> > > + sup_dev = of_find_device_by_node(sup_args.np);
> > > + of_node_put(sup_args.np);
> > > + if (!sup_dev)
> > > + continue;
> > > + if (device_link_add(dev, &sup_dev->dev, dl_flags))
> > > + links++;
> > > + put_device(&sup_dev->dev);
> > > + }
> > > + if (links < i)
> > > + return -ENODEV;
> > > + return 0;
> > > +}
> > > +
> > > +static bool of_devlink;
> > > +core_param(of_devlink, of_devlink, bool, 0);
> > > +
> > > +/*
> > > + * List of bindings and their cell names (use NULL if no cell names) from which
> > > + * device links need to be created.
> > > + */
> > > +static const char * const link_bindings[] = {
> > > + "clocks", "#clock-cells",
> > > + "interconnects", "#interconnect-cells",
> > > +};
> > > +
> > > +static int of_link_to_suppliers(struct device *dev)
> > > +{
> > > + unsigned int i = 0;
> > > + bool done = true;
> > > +
> > > + if (!of_devlink)
> > > + return 0;
> > > + if (unlikely(!dev->of_node))
> > > + return 0;
> > > +
> > > + for (i = 0; i < ARRAY_SIZE(link_bindings) / 2; i++)
> > > + if (of_link_binding(dev, link_bindings[i * 2],
> > > + link_bindings[i * 2 + 1]))
> > > + done = false;
> >
> > Given the pending addition of regulators I think this should be
> > structured a bit differently so that we abstract out the matching and
> > phandle look-up so there's a clean separation of binding specifics.
> > It's kind of messy with 2 patterns to parse already and if we added a
> > 3rd? I would iterate over the properties as you do for regulators in
> > both cases and for each property call a binding specific match
> > function. The common pattern can of course be a common function. Let
> > me know if that makes sense. If not I can try to flesh it out some
> > more.
>
> I've added regulator support in this series and I've refactored this
> code as I went along. I fully expect to squash some of the refactors
> once the final result of the series is acceptable.
It would be easier to review the final result than incremental changes
which change the prior patches especially if the latter patches are
ultimately required.
> It's not clear to me if you got to the end of the series and still
> think the final result needs to be refactored. Let me know what you
> think about this towards the end of the series and I can clean it up
> if you still think it needs some clean up.
I probably should have replied on the regulator addition, but yes,
looking at that is what prompted my concerns here.
Rob
^ permalink raw reply
* If interested
From: Tk Allen @ 2019-07-17 13:32 UTC (permalink / raw)
To: all.en.m61.2.0
My name is Mr. Allen, I have a Business Proposal of Four million five hundred thousand united states dollars for you to handle with me from my bank. I will need you to assist me in executing this Business .
^ permalink raw reply
* Re: [PATCH v3 06/20] docs: kernel_abi.py: fix UTF-8 support
From: Mauro Carvalho Chehab @ 2019-07-17 12:30 UTC (permalink / raw)
To: Markus Heiser; +Cc: gregkh, Jonathan Corbet, linux-doc
In-Reply-To: <fd4ae75a-3cb3-3f26-8891-e503451355b9@darmarit.de>
Em Wed, 17 Jul 2019 13:44:40 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:
> Hi Mauro,
>
> just nitpicking ..
>
> Am 17.07.19 um 13:05 schrieb Mauro Carvalho Chehab:
> > The parser breaks with UTF-8 characters with Sphinx 1.4.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> > Documentation/sphinx/kernel_abi.py | 20 +++++++-------------
> > 1 file changed, 7 insertions(+), 13 deletions(-)
> >
> > diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
> > index 32ce90775d96..0f3e51e67e8d 100644
> > --- a/Documentation/sphinx/kernel_abi.py
> > +++ b/Documentation/sphinx/kernel_abi.py
> > @@ -1,4 +1,5 @@
> > -# -*- coding: utf-8; mode: python -*-
> > +# coding=utf-8
>
> Can we use the more common::
>
> # -*- coding: utf-8 -*-
>
> notation? See [1] """using formats recognized by popular editors"""
>
> If I'am not wrong, I remember we had this 'magic comment' discussion in the past.
Changed. I ended by merging this change, together with the SPDX one at
the initial patch and did some other patch merges, in order to provide
a cleaner history.
Thanks,
Mauro
^ permalink raw reply
* [PATCH v4 12/15] docs: ABI: stable: make files ReST compatible
From: Mauro Carvalho Chehab @ 2019-07-17 12:28 UTC (permalink / raw)
To: gregkh
Cc: Mauro Carvalho Chehab, Srinivas Kandagatla, Johannes Berg,
Benjamin Herrenschmidt, Paul Mackerras, Michael Ellerman,
Boris Ostrovsky, Juergen Gross, Stefano Stabellini,
Jonathan Corbet, linux-wireless, linuxppc-dev, xen-devel,
linux-doc
In-Reply-To: <cover.1563365880.git.mchehab+samsung@kernel.org>
Several entries at the stable ABI files won't parse if we pass
them directly to the ReST output.
Adjust them, in order to allow adding their contents as-is at
the stable ABI book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/stable/firewire-cdev | 4 +
Documentation/ABI/stable/sysfs-acpi-pmprofile | 22 +++--
Documentation/ABI/stable/sysfs-bus-firewire | 3 +
Documentation/ABI/stable/sysfs-bus-nvmem | 19 ++--
Documentation/ABI/stable/sysfs-bus-usb | 6 +-
.../ABI/stable/sysfs-class-backlight | 1 +
.../ABI/stable/sysfs-class-infiniband | 95 +++++++++++++------
Documentation/ABI/stable/sysfs-class-rfkill | 13 ++-
Documentation/ABI/stable/sysfs-class-tpm | 90 +++++++++---------
Documentation/ABI/stable/sysfs-devices | 5 +-
Documentation/ABI/stable/sysfs-driver-ib_srp | 1 +
.../ABI/stable/sysfs-firmware-efi-vars | 4 +
.../ABI/stable/sysfs-firmware-opal-dump | 5 +
.../ABI/stable/sysfs-firmware-opal-elog | 2 +
Documentation/ABI/stable/sysfs-hypervisor-xen | 3 +
Documentation/ABI/stable/vdso | 5 +-
Documentation/admin-guide/abi-stable.rst | 1 +
17 files changed, 179 insertions(+), 100 deletions(-)
diff --git a/Documentation/ABI/stable/firewire-cdev b/Documentation/ABI/stable/firewire-cdev
index f72ed653878a..c9e8ff026154 100644
--- a/Documentation/ABI/stable/firewire-cdev
+++ b/Documentation/ABI/stable/firewire-cdev
@@ -14,12 +14,14 @@ Description:
Each /dev/fw* is associated with one IEEE 1394 node, which can
be remote or local nodes. Operations on a /dev/fw* file have
different scope:
+
- The 1394 node which is associated with the file:
- Asynchronous request transmission
- Get the Configuration ROM
- Query node ID
- Query maximum speed of the path between this node
and local node
+
- The 1394 bus (i.e. "card") to which the node is attached to:
- Isochronous stream transmission and reception
- Asynchronous stream transmission and reception
@@ -31,6 +33,7 @@ Description:
manager
- Query cycle time
- Bus reset initiation, bus reset event reception
+
- All 1394 buses:
- Allocation of IEEE 1212 address ranges on the local
link layers, reception of inbound requests to such
@@ -43,6 +46,7 @@ Description:
userland implement different access permission models, some
operations are restricted to /dev/fw* files that are associated
with a local node:
+
- Addition of descriptors or directories to the local
nodes' Configuration ROM
- PHY packet transmission and reception
diff --git a/Documentation/ABI/stable/sysfs-acpi-pmprofile b/Documentation/ABI/stable/sysfs-acpi-pmprofile
index 964c7a8afb26..fd97d22b677f 100644
--- a/Documentation/ABI/stable/sysfs-acpi-pmprofile
+++ b/Documentation/ABI/stable/sysfs-acpi-pmprofile
@@ -6,17 +6,21 @@ Description: The ACPI pm_profile sysfs interface exports the platform
power management (and performance) requirement expectations
as provided by BIOS. The integer value is directly passed as
retrieved from the FADT ACPI table.
-Values: For possible values see ACPI specification:
+
+Values: For possible values see ACPI specification:
5.2.9 Fixed ACPI Description Table (FADT)
Field: Preferred_PM_Profile
Currently these values are defined by spec:
- 0 Unspecified
- 1 Desktop
- 2 Mobile
- 3 Workstation
- 4 Enterprise Server
- 5 SOHO Server
- 6 Appliance PC
- 7 Performance Server
+
+ == =================
+ 0 Unspecified
+ 1 Desktop
+ 2 Mobile
+ 3 Workstation
+ 4 Enterprise Server
+ 5 SOHO Server
+ 6 Appliance PC
+ 7 Performance Server
>7 Reserved
+ == =================
diff --git a/Documentation/ABI/stable/sysfs-bus-firewire b/Documentation/ABI/stable/sysfs-bus-firewire
index 41e5a0cd1e3e..9ac9eddb82ef 100644
--- a/Documentation/ABI/stable/sysfs-bus-firewire
+++ b/Documentation/ABI/stable/sysfs-bus-firewire
@@ -47,6 +47,7 @@ Description:
IEEE 1394 node device attribute.
Read-only and immutable.
Values: 1: The sysfs entry represents a local node (a controller card).
+
0: The sysfs entry represents a remote node.
@@ -125,7 +126,9 @@ Description:
Read-only attribute, immutable during the target's lifetime.
Format, as exposed by firewire-sbp2 since 2.6.22, May 2007:
Colon-separated hexadecimal string representations of
+
u64 EUI-64 : u24 directory_ID : u16 LUN
+
without 0x prefixes, without whitespace. The former sbp2 driver
(removed in 2.6.37 after being superseded by firewire-sbp2) used
a somewhat shorter format which was not as close to SAM.
diff --git a/Documentation/ABI/stable/sysfs-bus-nvmem b/Documentation/ABI/stable/sysfs-bus-nvmem
index 9ffba8576f7b..c399323f37de 100644
--- a/Documentation/ABI/stable/sysfs-bus-nvmem
+++ b/Documentation/ABI/stable/sysfs-bus-nvmem
@@ -9,13 +9,14 @@ Description:
Note: This file is only present if CONFIG_NVMEM_SYSFS
is enabled
- ex:
- hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+ ex::
- 0000000 0000 0000 0000 0000 0000 0000 0000 0000
- *
- 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
- 0000000 0000 0000 0000 0000 0000 0000 0000 0000
- ...
- *
- 0001000
+ hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ *
+ 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ ...
+ *
+ 0001000
diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb
index b832eeff9999..cad4bc232520 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -50,8 +50,10 @@ Description:
Tools can use this file and the connected_duration file to
compute the percentage of time that a device has been active.
- For example,
- echo $((100 * `cat active_duration` / `cat connected_duration`))
+ For example::
+
+ echo $((100 * `cat active_duration` / `cat connected_duration`))
+
will give an integer percentage. Note that this does not
account for counter wrap.
Users:
diff --git a/Documentation/ABI/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight
index 70302f370e7e..023fb52645f8 100644
--- a/Documentation/ABI/stable/sysfs-class-backlight
+++ b/Documentation/ABI/stable/sysfs-class-backlight
@@ -4,6 +4,7 @@ KernelVersion: 2.6.12
Contact: Richard Purdie <rpurdie@rpsys.net>
Description:
Control BACKLIGHT power, values are FB_BLANK_* from fb.h
+
- FB_BLANK_UNBLANK (0) : power on.
- FB_BLANK_POWERDOWN (4) : power off
Users: HAL
diff --git a/Documentation/ABI/stable/sysfs-class-infiniband b/Documentation/ABI/stable/sysfs-class-infiniband
index aed21b8916a2..ac774d36a512 100644
--- a/Documentation/ABI/stable/sysfs-class-infiniband
+++ b/Documentation/ABI/stable/sysfs-class-infiniband
@@ -8,12 +8,14 @@ Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===========================================
node_type: (RO) Node type (CA, RNIC, usNIC, usNIC UDP,
switch or router)
node_guid: (RO) Node GUID
sys_image_guid: (RO) System image GUID
+ =============== ===========================================
What: /sys/class/infiniband/<device>/node_desc
@@ -47,6 +49,7 @@ KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===============================================
lid: (RO) Port LID
rate: (RO) Port data rate (active width * active
@@ -66,8 +69,9 @@ Description:
cap_mask: (RO) Port capability mask. 2 bits here are
settable- IsCommunicationManagementSupported
- (set when CM module is loaded) and IsSM (set via
- open of issmN file).
+ (set when CM module is loaded) and IsSM (set
+ via open of issmN file).
+ =============== ===============================================
What: /sys/class/infiniband/<device>/ports/<port-num>/link_layer
@@ -103,8 +107,7 @@ Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
- Errors info:
- -----------
+ **Errors info**:
symbol_error: (RO) Total number of minor link errors detected on
one or more physical lanes.
@@ -142,8 +145,7 @@ Description:
intervention. It can also indicate hardware issues or extremely
poor link signal integrity
- Data info:
- ---------
+ **Data info**:
port_xmit_data: (RO) Total number of data octets, divided by 4
(lanes), transmitted on all VLs. This is 64 bit counter
@@ -176,8 +178,7 @@ Description:
transmitted on all VLs from the port. This may include multicast
packets with errors.
- Misc info:
- ---------
+ **Misc info**:
port_xmit_discards: (RO) Total number of outbound packets
discarded by the port because the port is down or congested.
@@ -244,9 +245,11 @@ Description:
two umad devices and two issm devices, while a switch will have
one device of each type (for switch port 0).
+ ======= =====================================
ibdev: (RO) Show Infiniband (IB) device name
port: (RO) Display port number
+ ======= =====================================
What: /sys/class/infiniband_mad/abi_version
@@ -281,10 +284,12 @@ Date: Sept, 2005
KernelVersion: v2.6.14
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===========================================
ibdev: (RO) Display Infiniband (IB) device name
abi_version: (RO) Show ABI version of IB device specific
interfaces.
+ =============== ===========================================
What: /sys/class/infiniband_verbs/abi_version
@@ -306,12 +311,14 @@ Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ================================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host Channel Adapter type: MT23108, MT25208
(MT23108 compat mode), MT25208 or MT25204
board_id: (RO) Manufacturing board ID
+ =============== ================================================
sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
@@ -324,6 +331,7 @@ Date: Feb, 2007
KernelVersion: v2.6.21
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==============================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) HCA type. Here it is a driver short name.
@@ -331,6 +339,7 @@ Description:
driver structure (e.g. pci_driver::name).
board_id: (RO) Manufacturing board id
+ =============== ==============================================
sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
@@ -343,11 +352,13 @@ Date: Sep, 2007
KernelVersion: v2.6.24
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===============================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
board_id: (RO) Manufacturing board ID
+ =============== ===============================
What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/gids/<n>
@@ -373,6 +384,7 @@ Description:
example, ports/1/pkeys/10 contains the value at index 10 in port
1's P_Key table.
+ ======================= ==========================================
gids/<n>: (RO) The physical port gids n = 0..127
admin_guids/<n>: (RW) Allows examining or changing the
@@ -401,6 +413,7 @@ Description:
guest, whenever it uses its pkey index
1, will actually be using the real pkey
index 10.
+ ======================= ==========================================
What: /sys/class/infiniband/mlx4_X/iov/<pci-slot-num>/ports/<m>/smi_enabled
@@ -412,12 +425,14 @@ Description:
Enabling QP0 on VFs for selected VF/port. By default, no VFs are
enabled for QP0 operation.
- smi_enabled: (RO) Indicates whether smi is currently enabled
- for the indicated VF/port
+ ================= ==== ===========================================
+ smi_enabled: (RO) Indicates whether smi is currently enabled
+ for the indicated VF/port
- enable_smi_admin:(RW) Used by the admin to request that smi
- capability be enabled or disabled for the
- indicated VF/port. 0 = disable, 1 = enable.
+ enable_smi_admin: (RW) Used by the admin to request that smi
+ capability be enabled or disabled for the
+ indicated VF/port. 0 = disable, 1 = enable.
+ ================= ==== ===========================================
The requested enablement will occur at the next reset of the VF
(e.g. driver restart on the VM which owns the VF).
@@ -434,6 +449,7 @@ KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== =============================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Driver short name. Should normally match
@@ -442,6 +458,7 @@ Description:
board_id: (RO) Manufacturing board id. (Vendor + device
information)
+ =============== =============================================
sysfs interface for Intel IB driver qib
@@ -462,6 +479,7 @@ Date: May, 2010
KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ======================================================
version: (RO) Display version information of installed software
and drivers.
@@ -488,6 +506,7 @@ Description:
chip_reset: (WO) Reset the chip if possible by writing
"reset" to this file. Only allowed if no user
contexts are open that use chip resources.
+ =============== ======================================================
What: /sys/class/infiniband/qibX/ports/N/sl2vl/[0-15]
@@ -507,14 +526,16 @@ Contact: linux-rdma@vger.kernel.org
Description:
Per-port congestion control. Both are binary attributes.
- cc_table_bin: (RO) Congestion control table size followed by
+ =============== ================================================
+ cc_table_bin (RO) Congestion control table size followed by
table entries.
- cc_settings_bin:(RO) Congestion settings: port control, control
+ cc_settings_bin (RO) Congestion settings: port control, control
map and an array of 16 entries for the
congestion entries - increase, timer, event log
trigger threshold and the minimum injection rate
delay.
+ =============== ================================================
What: /sys/class/infiniband/qibX/ports/N/linkstate/loopback
What: /sys/class/infiniband/qibX/ports/N/linkstate/led_override
@@ -527,6 +548,7 @@ Contact: linux-rdma@vger.kernel.org
Description:
[to be documented]
+ =============== ===============================================
loopback: (WO)
led_override: (WO)
hrtbt_enable: (RW)
@@ -537,6 +559,7 @@ Description:
errors. Possible states are- "Initted",
"Present", "IB_link_up", "IB_configured" or
"Fatal_Hardware_Error".
+ =============== ===============================================
What: /sys/class/infiniband/qibX/ports/N/diag_counters/rc_resends
What: /sys/class/infiniband/qibX/ports/N/diag_counters/seq_naks
@@ -585,6 +608,7 @@ Contact: Christian Benvenuti <benve@cisco.com>,
linux-rdma@vger.kernel.org
Description:
+ =============== ===============================================
board_id: (RO) Manufacturing board id
config: (RO) Report the configuration for this PF
@@ -597,6 +621,7 @@ Description:
iface: (RO) Shows which network interface this usNIC
entry is associated to (visible with ifconfig).
+ =============== ===============================================
What: /sys/class/infiniband/usnic_X/qpn/summary
What: /sys/class/infiniband/usnic_X/qpn/context
@@ -641,6 +666,7 @@ Date: May, 2016
KernelVersion: v4.6
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== =============================================
hw_rev: (RO) Hardware revision number
board_id: (RO) Manufacturing board id
@@ -659,6 +685,7 @@ Description:
available.
tempsense: (RO) Thermal sense information
+ =============== =============================================
What: /sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_settings_bin
@@ -670,19 +697,21 @@ Contact: linux-rdma@vger.kernel.org
Description:
Per-port congestion control.
- cc_table_bin: (RO) CCA tables used by PSM2 Congestion control
+ =============== ================================================
+ cc_table_bin (RO) CCA tables used by PSM2 Congestion control
table size followed by table entries. Binary
attribute.
- cc_settings_bin:(RO) Congestion settings: port control, control
+ cc_settings_bin (RO) Congestion settings: port control, control
map and an array of 16 entries for the
congestion entries - increase, timer, event log
trigger threshold and the minimum injection rate
delay. Binary attribute.
- cc_prescan: (RW) enable prescanning for faster BECN
+ cc_prescan (RW) enable prescanning for faster BECN
response. Write "on" to enable and "off" to
disable.
+ =============== ================================================
What: /sys/class/infiniband/hfi1_X/ports/N/sc2vl/[0-31]
What: /sys/class/infiniband/hfi1_X/ports/N/sl2sc/[0-31]
@@ -691,11 +720,13 @@ Date: May, 2016
KernelVersion: v4.6
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===================================================
sc2vl/: (RO) 32 files (0 - 31) used to translate sl->vl
sl2sc/: (RO) 32 files (0 - 31) used to translate sl->sc
vl2mtu/: (RO) 16 files (0 - 15) used to determine MTU for vl
+ =============== ===================================================
What: /sys/class/infiniband/hfi1_X/sdma_N/cpu_list
@@ -706,26 +737,28 @@ Contact: linux-rdma@vger.kernel.org
Description:
sdma<N>/ contains one directory per sdma engine (0 - 15)
+ =============== ==============================================
cpu_list: (RW) List of cpus for user-process to sdma
engine assignment.
vl: (RO) Displays the virtual lane (vl) the sdma
engine maps to.
+ =============== ==============================================
This interface gives the user control on the affinity settings
for the device. As an example, to set an sdma engine irq
affinity and thread affinity of a user processes to use the
sdma engine, which is "near" in terms of NUMA configuration, or
- physical cpu location, the user will do:
+ physical cpu location, the user will do::
- echo "3" > /proc/irq/<N>/smp_affinity_list
- echo "4-7" > /sys/devices/.../sdma3/cpu_list
- cat /sys/devices/.../sdma3/vl
- 0
- echo "8" > /proc/irq/<M>/smp_affinity_list
- echo "9-12" > /sys/devices/.../sdma4/cpu_list
- cat /sys/devices/.../sdma4/vl
- 1
+ echo "3" > /proc/irq/<N>/smp_affinity_list
+ echo "4-7" > /sys/devices/.../sdma3/cpu_list
+ cat /sys/devices/.../sdma3/vl
+ 0
+ echo "8" > /proc/irq/<M>/smp_affinity_list
+ echo "9-12" > /sys/devices/.../sdma4/cpu_list
+ cat /sys/devices/.../sdma4/vl
+ 1
to make sure that when a process runs on cpus 4,5,6, or 7, and
uses vl=0, then sdma engine 3 is selected by the driver, and
@@ -747,11 +780,13 @@ Date: Jan, 2016
KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== ========================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Show HCA type (I40IW)
board_id: (RO) I40IW board ID
+ =============== ==== ========================
sysfs interface for QLogic qedr NIC Driver
@@ -764,9 +799,11 @@ KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== ========================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Display HCA type
+ =============== ==== ========================
sysfs interface for VMware Paravirtual RDMA driver
@@ -780,11 +817,13 @@ KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== =====================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
board_id: (RO) Display PVRDMA manufacturing board ID
+ =============== ==== =====================================
sysfs interface for Broadcom NetXtreme-E RoCE driver
@@ -796,6 +835,8 @@ Date: Feb, 2017
KernelVersion: v4.11
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== =========================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
+ =============== ==== =========================
diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
index 5b154f922643..037979f7dc4b 100644
--- a/Documentation/ABI/stable/sysfs-class-rfkill
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -2,7 +2,7 @@ rfkill - radio frequency (RF) connector kill switch support
For details to this subsystem look at Documentation/driver-api/rfkill.rst.
-For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in
+For the deprecated ``/sys/class/rfkill/*/claim`` knobs of this interface look in
Documentation/ABI/removed/sysfs-class-rfkill.
What: /sys/class/rfkill
@@ -36,9 +36,10 @@ KernelVersion v2.6.22
Contact: linux-wireless@vger.kernel.org
Description: Whether the soft blocked state is initialised from non-volatile
storage at startup.
-Values: A numeric value.
- 0: false
- 1: true
+Values: A numeric value:
+
+ - 0: false
+ - 1: true
What: /sys/class/rfkill/rfkill[0-9]+/state
@@ -54,6 +55,7 @@ Description: Current state of the transmitter.
through this interface. There will likely be another attempt to
remove it in the future.
Values: A numeric value.
+
0: RFKILL_STATE_SOFT_BLOCKED
transmitter is turned off by software
1: RFKILL_STATE_UNBLOCKED
@@ -69,6 +71,7 @@ KernelVersion v2.6.34
Contact: linux-wireless@vger.kernel.org
Description: Current hardblock state. This file is read only.
Values: A numeric value.
+
0: inactive
The transmitter is (potentially) active.
1: active
@@ -82,7 +85,9 @@ KernelVersion v2.6.34
Contact: linux-wireless@vger.kernel.org
Description: Current softblock state. This file is read and write.
Values: A numeric value.
+
0: inactive
The transmitter is (potentially) active.
+
1: active
The transmitter is turned off by software.
diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm
index c0e23830f56a..bbee8899a90e 100644
--- a/Documentation/ABI/stable/sysfs-class-tpm
+++ b/Documentation/ABI/stable/sysfs-class-tpm
@@ -32,11 +32,11 @@ KernelVersion: 2.6.12
Contact: tpmdd-devel@lists.sf.net
Description: The "caps" property contains TPM manufacturer and version info.
- Example output:
+ Example output::
- Manufacturer: 0x53544d20
- TCG version: 1.2
- Firmware version: 8.16
+ Manufacturer: 0x53544d20
+ TCG version: 1.2
+ Firmware version: 8.16
Manufacturer is a hex dump of the 4 byte manufacturer info
space in a TPM. TCG version shows the TCG TPM spec level that
@@ -54,9 +54,9 @@ Description: The "durations" property shows the 3 vendor-specific values
any longer than necessary before starting to poll for a
result.
- Example output:
+ Example output::
- 3015000 4508000 180995000 [original]
+ 3015000 4508000 180995000 [original]
Here the short, medium and long durations are displayed in
usecs. "[original]" indicates that the values are displayed
@@ -92,14 +92,14 @@ Description: The "pcrs" property will dump the current value of all Platform
values may be constantly changing, the output is only valid
for a snapshot in time.
- Example output:
+ Example output::
- PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- ...
+ PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ ...
The number of PCRs and hex bytes needed to represent a PCR
value will vary depending on TPM chip version. For TPM 1.1 and
@@ -119,44 +119,44 @@ Description: The "pubek" property will return the TPM's public endorsement
ated at TPM manufacture time and exists for the life of the
chip.
- Example output:
+ Example output::
- Algorithm: 00 00 00 01
- Encscheme: 00 03
- Sigscheme: 00 01
- Parameters: 00 00 08 00 00 00 00 02 00 00 00 00
- Modulus length: 256
- Modulus:
- B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C
- 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6
- 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB
- 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3
- D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B
- 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26
- 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E
- 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D
- 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0
- A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6
- 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6
- 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70
- E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A
- F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6
- F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B
- C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B
+ Algorithm: 00 00 00 01
+ Encscheme: 00 03
+ Sigscheme: 00 01
+ Parameters: 00 00 08 00 00 00 00 02 00 00 00 00
+ Modulus length: 256
+ Modulus:
+ B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C
+ 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6
+ 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB
+ 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3
+ D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B
+ 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26
+ 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E
+ 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D
+ 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0
+ A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6
+ 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6
+ 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70
+ E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A
+ F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6
+ F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B
+ C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B
- Possible values:
+ Possible values::
- Algorithm: TPM_ALG_RSA (1)
- Encscheme: TPM_ES_RSAESPKCSv15 (2)
+ Algorithm: TPM_ALG_RSA (1)
+ Encscheme: TPM_ES_RSAESPKCSv15 (2)
TPM_ES_RSAESOAEP_SHA1_MGF1 (3)
- Sigscheme: TPM_SS_NONE (1)
- Parameters, a byte string of 3 u32 values:
+ Sigscheme: TPM_SS_NONE (1)
+ Parameters, a byte string of 3 u32 values:
Key Length (bits): 00 00 08 00 (2048)
Num primes: 00 00 00 02 (2)
Exponent Size: 00 00 00 00 (0 means the
default exp)
- Modulus Length: 256 (bytes)
- Modulus: The 256 byte Endorsement Key modulus
+ Modulus Length: 256 (bytes)
+ Modulus: The 256 byte Endorsement Key modulus
What: /sys/class/tpm/tpmX/device/temp_deactivated
Date: April 2006
@@ -176,9 +176,9 @@ Description: The "timeouts" property shows the 4 vendor-specific values
timeouts is defined by the TPM interface spec that the chip
conforms to.
- Example output:
+ Example output::
- 750000 750000 750000 750000 [original]
+ 750000 750000 750000 750000 [original]
The four timeout values are shown in usecs, with a trailing
"[original]" or "[adjusted]" depending on whether the values
diff --git a/Documentation/ABI/stable/sysfs-devices b/Documentation/ABI/stable/sysfs-devices
index 4404bd9b96c1..42bf1eab5677 100644
--- a/Documentation/ABI/stable/sysfs-devices
+++ b/Documentation/ABI/stable/sysfs-devices
@@ -1,5 +1,6 @@
-# Note: This documents additional properties of any device beyond what
-# is documented in Documentation/admin-guide/sysfs-rules.rst
+Note:
+ This documents additional properties of any device beyond what
+ is documented in Documentation/admin-guide/sysfs-rules.rst
What: /sys/devices/*/of_node
Date: February 2015
diff --git a/Documentation/ABI/stable/sysfs-driver-ib_srp b/Documentation/ABI/stable/sysfs-driver-ib_srp
index 7049a2b50359..2d706b4900ce 100644
--- a/Documentation/ABI/stable/sysfs-driver-ib_srp
+++ b/Documentation/ABI/stable/sysfs-driver-ib_srp
@@ -6,6 +6,7 @@ Description: Interface for making ib_srp connect to a new target.
One can request ib_srp to connect to a new target by writing
a comma-separated list of login parameters to this sysfs
attribute. The supported parameters are:
+
* id_ext, a 16-digit hexadecimal number specifying the eight
byte identifier extension in the 16-byte SRP target port
identifier. The target port identifier is sent by ib_srp
diff --git a/Documentation/ABI/stable/sysfs-firmware-efi-vars b/Documentation/ABI/stable/sysfs-firmware-efi-vars
index 5def20b9019e..46ccd233e359 100644
--- a/Documentation/ABI/stable/sysfs-firmware-efi-vars
+++ b/Documentation/ABI/stable/sysfs-firmware-efi-vars
@@ -17,6 +17,7 @@ Description:
directory has a name of the form "<key>-<vendor guid>"
and contains the following files:
+ =============== ========================================
attributes: A read-only text file enumerating the
EFI variable flags. Potential values
include:
@@ -59,12 +60,14 @@ Description:
size: As ASCII representation of the size of
the variable's value.
+ =============== ========================================
In addition, two other magic binary files are provided
in the top-level directory and are used for adding and
removing variables:
+ =============== ========================================
new_var: Takes a "struct efi_variable" and
instructs the EFI firmware to create a
new variable.
@@ -73,3 +76,4 @@ Description:
instructs the EFI firmware to remove any
variable that has a matching vendor GUID
and variable key name.
+ =============== ========================================
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-dump b/Documentation/ABI/stable/sysfs-firmware-opal-dump
index 32fe7f5c4880..1f74f45327ba 100644
--- a/Documentation/ABI/stable/sysfs-firmware-opal-dump
+++ b/Documentation/ABI/stable/sysfs-firmware-opal-dump
@@ -7,6 +7,7 @@ Description:
This is only for the powerpc/powernv platform.
+ =============== ===============================================
initiate_dump: When '1' is written to it,
we will initiate a dump.
Read this file for supported commands.
@@ -19,8 +20,11 @@ Description:
and ID of the dump, use the id and type files.
Do not rely on any particular size of dump
type or dump id.
+ =============== ===============================================
Each dump has the following files:
+
+ =============== ===============================================
id: An ASCII representation of the dump ID
in hex (e.g. '0x01')
type: An ASCII representation of the type of
@@ -39,3 +43,4 @@ Description:
inaccessible.
Reading this file will get a list of
supported actions.
+ =============== ===============================================
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-elog b/Documentation/ABI/stable/sysfs-firmware-opal-elog
index 2536434d49d0..7c8a61a2d005 100644
--- a/Documentation/ABI/stable/sysfs-firmware-opal-elog
+++ b/Documentation/ABI/stable/sysfs-firmware-opal-elog
@@ -38,6 +38,7 @@ Description:
For each log entry (directory), there are the following
files:
+ ============== ================================================
id: An ASCII representation of the ID of the
error log, in hex - e.g. "0x01".
@@ -58,3 +59,4 @@ Description:
entry will be removed from sysfs.
Reading this file will list the supported
operations (currently just acknowledge).
+ ============== ================================================
diff --git a/Documentation/ABI/stable/sysfs-hypervisor-xen b/Documentation/ABI/stable/sysfs-hypervisor-xen
index 3cf5cdfcd9a8..748593c64568 100644
--- a/Documentation/ABI/stable/sysfs-hypervisor-xen
+++ b/Documentation/ABI/stable/sysfs-hypervisor-xen
@@ -33,6 +33,8 @@ Description: If running under Xen:
Space separated list of supported guest system types. Each type
is in the format: <class>-<major>.<minor>-<arch>
With:
+
+ ======== ============================================
<class>: "xen" -- x86: paravirtualized, arm: standard
"hvm" -- x86 only: fully virtualized
<major>: major guest interface version
@@ -43,6 +45,7 @@ Description: If running under Xen:
"x86_64": 64 bit x86 guest
"armv7l": 32 bit arm guest
"aarch64": 64 bit arm guest
+ ======== ============================================
What: /sys/hypervisor/properties/changeset
Date: March 2009
diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso
index 55406ec8a35a..73ed1240a5c0 100644
--- a/Documentation/ABI/stable/vdso
+++ b/Documentation/ABI/stable/vdso
@@ -23,6 +23,7 @@ Unless otherwise noted, the set of symbols with any given version and the
ABI of those symbols is considered stable. It may vary across architectures,
though.
-(As of this writing, this ABI documentation as been confirmed for x86_64.
+Note:
+ As of this writing, this ABI documentation as been confirmed for x86_64.
The maintainers of the other vDSO-using architectures should confirm
- that it is correct for their architecture.)
+ that it is correct for their architecture.
diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst
index 7495d7a35048..70490736e0d3 100644
--- a/Documentation/admin-guide/abi-stable.rst
+++ b/Documentation/admin-guide/abi-stable.rst
@@ -11,3 +11,4 @@ Most interfaces (like syscalls) are expected to never change and always
be available.
.. kernel-abi:: $srctree/Documentation/ABI/stable
+ :rst:
--
2.21.0
^ permalink raw reply related
* [PATCH v4 14/15] docs: ABI: obsolete, removed: don't escape ReST-incompatible chars
From: Mauro Carvalho Chehab @ 2019-07-17 12:28 UTC (permalink / raw)
To: gregkh
Cc: Mauro Carvalho Chehab, Linus Walleij, Bartosz Golaszewski,
Jonathan Corbet, linux-gpio, linux-doc
In-Reply-To: <cover.1563365880.git.mchehab+samsung@kernel.org>
With just a single fix, the contents there can be parsed properly
without the need to escape any ReST incompatible stuff.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/obsolete/sysfs-gpio | 2 ++
Documentation/admin-guide/abi-obsolete.rst | 1 +
Documentation/admin-guide/abi-removed.rst | 1 +
3 files changed, 4 insertions(+)
diff --git a/Documentation/ABI/obsolete/sysfs-gpio b/Documentation/ABI/obsolete/sysfs-gpio
index e0d4e5e2dd90..b8b0fd341c17 100644
--- a/Documentation/ABI/obsolete/sysfs-gpio
+++ b/Documentation/ABI/obsolete/sysfs-gpio
@@ -13,6 +13,8 @@ Description:
GPIOs are identified as they are inside the kernel, using integers in
the range 0..INT_MAX. See Documentation/admin-guide/gpio for more information.
+ ::
+
/sys/class/gpio
/export ... asks the kernel to export a GPIO to userspace
/unexport ... to return a GPIO to the kernel
diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst
index cda9168445a5..d095867899c5 100644
--- a/Documentation/admin-guide/abi-obsolete.rst
+++ b/Documentation/admin-guide/abi-obsolete.rst
@@ -8,3 +8,4 @@ The description of the interface will document the reason why it is
obsolete and when it can be expected to be removed.
.. kernel-abi:: $srctree/Documentation/ABI/obsolete
+ :rst:
diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst
index 497978fc9632..f7e9e43023c1 100644
--- a/Documentation/admin-guide/abi-removed.rst
+++ b/Documentation/admin-guide/abi-removed.rst
@@ -2,3 +2,4 @@ ABI removed symbols
===================
.. kernel-abi:: $srctree/Documentation/ABI/removed
+ :rst:
--
2.21.0
^ permalink raw reply related
* [PATCH v4 10/15] docs: add ABI documentation to the admin-guide book
From: Mauro Carvalho Chehab @ 2019-07-17 12:28 UTC (permalink / raw)
To: gregkh; +Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc
In-Reply-To: <cover.1563365880.git.mchehab+samsung@kernel.org>
As we don't want a generic Sphinx extension to execute commands,
change the one proposed to Markus to call the abi_book.pl
script.
Use a script to parse the Documentation/ABI directory and output
it at the admin-guide.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/abi-obsolete.rst | 10 ++++++++++
Documentation/admin-guide/abi-removed.rst | 4 ++++
Documentation/admin-guide/abi-stable.rst | 13 +++++++++++++
Documentation/admin-guide/abi-testing.rst | 19 +++++++++++++++++++
Documentation/admin-guide/abi.rst | 11 +++++++++++
Documentation/admin-guide/index.rst | 2 ++
Documentation/conf.py | 2 +-
7 files changed, 60 insertions(+), 1 deletion(-)
create mode 100644 Documentation/admin-guide/abi-obsolete.rst
create mode 100644 Documentation/admin-guide/abi-removed.rst
create mode 100644 Documentation/admin-guide/abi-stable.rst
create mode 100644 Documentation/admin-guide/abi-testing.rst
create mode 100644 Documentation/admin-guide/abi.rst
diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst
new file mode 100644
index 000000000000..cda9168445a5
--- /dev/null
+++ b/Documentation/admin-guide/abi-obsolete.rst
@@ -0,0 +1,10 @@
+ABI obsolete symbols
+====================
+
+Documents interfaces that are still remaining in the kernel, but are
+marked to be removed at some later point in time.
+
+The description of the interface will document the reason why it is
+obsolete and when it can be expected to be removed.
+
+.. kernel-abi:: $srctree/Documentation/ABI/obsolete
diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst
new file mode 100644
index 000000000000..497978fc9632
--- /dev/null
+++ b/Documentation/admin-guide/abi-removed.rst
@@ -0,0 +1,4 @@
+ABI removed symbols
+===================
+
+.. kernel-abi:: $srctree/Documentation/ABI/removed
diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst
new file mode 100644
index 000000000000..7495d7a35048
--- /dev/null
+++ b/Documentation/admin-guide/abi-stable.rst
@@ -0,0 +1,13 @@
+ABI stable symbols
+==================
+
+Documents the interfaces that the developer has defined to be stable.
+
+Userspace programs are free to use these interfaces with no
+restrictions, and backward compatibility for them will be guaranteed
+for at least 2 years.
+
+Most interfaces (like syscalls) are expected to never change and always
+be available.
+
+.. kernel-abi:: $srctree/Documentation/ABI/stable
diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admin-guide/abi-testing.rst
new file mode 100644
index 000000000000..5c886fc50b9e
--- /dev/null
+++ b/Documentation/admin-guide/abi-testing.rst
@@ -0,0 +1,19 @@
+ABI testing symbols
+===================
+
+Documents interfaces that are felt to be stable,
+as the main development of this interface has been completed.
+
+The interface can be changed to add new features, but the
+current interface will not break by doing this, unless grave
+errors or security problems are found in them.
+
+Userspace programs can start to rely on these interfaces, but they must
+be aware of changes that can occur before these interfaces move to
+be marked stable.
+
+Programs that use these interfaces are strongly encouraged to add their
+name to the description of these interfaces, so that the kernel
+developers can easily notify them if any changes occur.
+
+.. kernel-abi:: $srctree/Documentation/ABI/testing
diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/abi.rst
new file mode 100644
index 000000000000..bcab3ef2597c
--- /dev/null
+++ b/Documentation/admin-guide/abi.rst
@@ -0,0 +1,11 @@
+=====================
+Linux ABI description
+=====================
+
+.. toctree::
+ :maxdepth: 2
+
+ abi-stable
+ abi-testing
+ abi-obsolete
+ abi-removed
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 280355d08af5..acdf2cd1d186 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -18,6 +18,8 @@ etc.
devices
sysctl/index
+ abi
+
This section describes CPU vulnerabilities and their mitigations.
.. toctree::
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 3b2397bcb565..35c1960ea15d 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -35,7 +35,7 @@ needs_sphinx = '1.3'
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',
- 'kfigure', 'sphinx.ext.ifconfig', 'automarkup']
+ 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', 'kernel_abi']
# The name of the math extension changed on Sphinx 1.4
if (major == 1 and minor > 3) or (major > 1):
--
2.21.0
^ permalink raw reply related
* [PATCH v4 08/15] docs: kernel_abi.py: allow passing ABI files in a transparent way
From: Mauro Carvalho Chehab @ 2019-07-17 12:28 UTC (permalink / raw)
To: gregkh; +Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc
In-Reply-To: <cover.1563365880.git.mchehab+samsung@kernel.org>
As get-abi.pl supports an ABI file that it is ReST compliant,
add an option to kernel-abi.py to allow using the transparent
mode of the tool.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernel_abi.py | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 615b3773bb62..30cac84e18f5 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -71,12 +71,13 @@ class KernelCmd(Directive):
u"""KernelABI (``kernel-abi``) directive"""
required_arguments = 1
- optional_arguments = 0
+ optional_arguments = 2
has_content = False
final_argument_whitespace = True
option_spec = {
- "debug" : directives.flag
+ "debug" : directives.flag,
+ "rst" : directives.unchanged
}
def warn(self, message, **replace):
@@ -96,6 +97,9 @@ class KernelCmd(Directive):
cmd = "get_abi.pl rest --enable-lineno --dir "
cmd += self.arguments[0]
+ if 'rst' in self.options:
+ cmd += " --rst-source"
+
srctree = path.abspath(os.environ["srctree"])
fname = cmd
--
2.21.0
^ permalink raw reply related
* [PATCH v4 15/15] docs: Kconfig/Makefile: add a check for broken ABI files
From: Mauro Carvalho Chehab @ 2019-07-17 12:28 UTC (permalink / raw)
To: gregkh; +Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc
In-Reply-To: <cover.1563365880.git.mchehab+samsung@kernel.org>
The files under Documentation/ABI should follow the syntax
as defined at Documentation/ABI/README.
Allow checking if they're following the syntax by running
the ABI parser script on COMPILE_TEST.
With that, when there's a problem with a file under
Documentation/ABI, it would produce a warning like:
Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#14:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor' doesn't have a description
Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#21:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal' doesn't have a description
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/Kconfig | 10 ++++++++++
Documentation/Makefile | 5 +++++
lib/Kconfig.debug | 2 ++
scripts/get_abi.pl | 14 +++++++++++---
4 files changed, 28 insertions(+), 3 deletions(-)
diff --git a/Documentation/Kconfig b/Documentation/Kconfig
index 66046fa1c341..e549a61f4d96 100644
--- a/Documentation/Kconfig
+++ b/Documentation/Kconfig
@@ -10,4 +10,14 @@ config WARN_MISSING_DOCUMENTS
If unsure, select 'N'.
+config WARN_ABI_ERRORS
+ bool "Warn if there are errors at ABI files"
+ depends on COMPILE_TEST
+ help
+ The files under Documentation/ABI should follow what's
+ described at Documentation/ABI/README. Yet, as they're manually
+ written, it would be possible that some of those files would
+ have errors that would break them for being parsed by
+ scripts/get_abi.pl. Add a check to verify them.
+ If unsure, select 'N'.
diff --git a/Documentation/Makefile b/Documentation/Makefile
index e145e4db508b..638c4c11d102 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -9,6 +9,11 @@ ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
$(shell $(srctree)/scripts/documentation-file-ref-check --warn)
endif
+# Check for broken ABI files
+ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
+$(shell $(srctree)/scripts/get_abi.pl validate --dir $(srctree)/Documentation/ABI)
+endif
+
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
SPHINXOPTS =
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index a858b55e8ac7..4cf6a8f68409 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -2146,4 +2146,6 @@ config IO_STRICT_DEVMEM
source "arch/$(SRCARCH)/Kconfig.debug"
+source "Documentation/Kconfig"
+
endmenu # Kernel hacking
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 6a4d387ebf3b..e80f9ab2ed26 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -47,7 +47,15 @@ my %data;
sub parse_error($$$$) {
my ($file, $ln, $msg, $data) = @_;
- print STDERR "file $file#$ln: $msg at\n\t$data";
+ $data =~ s/\s+$/\n/;
+
+ print STDERR "Warning: file $file#$ln:\n\t$msg";
+
+ if ($data ne "") {
+ print STDERR ". Line\n\t\t$data";
+ } else {
+ print STDERR "\n";
+ }
}
#
@@ -104,7 +112,7 @@ sub parse_abi {
# Invalid, but it is a common mistake
if ($new_tag eq "where") {
- parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", $_);
+ parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", "");
$new_tag = "what";
}
@@ -205,7 +213,7 @@ sub parse_abi {
}
# Everything else is error
- parse_error($file, $ln, "Unexpected line:", $_);
+ parse_error($file, $ln, "Unexpected content", $_);
}
$data{$nametag}->{description} =~ s/^\n+//;
close IN;
--
2.21.0
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox