* Re: [PATCH 1/9] media: docs: v4l2-controls: fix sentence rendered in a nonsense way
From: Hans Verkuil @ 2019-06-14 7:14 UTC (permalink / raw)
To: Luca Ceresoli, linux-media; +Cc: Mauro Carvalho Chehab, linux-kernel, linux-doc
In-Reply-To: <20190613141826.26775-1-luca@lucaceresoli.net>
On 6/13/19 4:18 PM, Luca Ceresoli wrote:
> This sentence renders as:
>
>> Since such compound controls need to expose more information about
>> themselves than is possible with ioctls VIDIOC_QUERYCTRL,
>> VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU the VIDIOC_QUERY_EXT_CTRL
> ^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
>> ioctl was added.
>
> This does not make sense. Fix by providing an explicit link text. This
> results in:
>
>> Since such compound controls need to expose more information about
>> themselves than is possible with VIDIOC_QUERYCTRL and VIDIOC_QUERYMENU
>> the VIDIOC_QUERY_EXT_CTRL ioctl was added.
>
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
> Documentation/media/uapi/v4l/extended-controls.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst
> index 24274b398e63..0968aa9cd167 100644
> --- a/Documentation/media/uapi/v4l/extended-controls.rst
> +++ b/Documentation/media/uapi/v4l/extended-controls.rst
> @@ -86,7 +86,7 @@ with compound types should only be used programmatically.
>
> Since such compound controls need to expose more information about
> themselves than is possible with
> -:ref:`VIDIOC_QUERYCTRL` the
> +:ref:`VIDIOC_QUERYCTRL and VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` the
This should just refer to VIDIOC_QUERYCTRL, not QUERYMENU. So this
becomes: :ref:`VIDIOC_QUERYCTRL <VIDIOC_QUERYCTRL>`
Regards,
Hans
> :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In
> particular, this ioctl gives the dimensions of the N-dimensional array
> if this control consists of more than one element.
>
^ permalink raw reply
* Re: [PATCH 1/2] dt-bindings: hwmon: Add DT bindings for TI ads1000/ads1100 ADCs
From: Serge Semin @ 2019-06-14 6:04 UTC (permalink / raw)
To: Rob Herring
Cc: Jean Delvare, Guenter Roeck, Mark Rutland, Jonathan Corbet,
Serge Semin, linux-hwmon, devicetree, linux-kernel, linux-doc
In-Reply-To: <20190613203313.GA23102@bogus>
Hello Rob
On Thu, Jun 13, 2019 at 02:33:13PM -0600, Rob Herring wrote:
> On Wed, May 15, 2019 at 01:58:08AM +0300, Serge Semin wrote:
> > Add dt-binding documentation for the Texas Instruments ads1000/ads1100 ADCs
> > driver.
> >
> > Signed-off-by: Serge Semin <fancer.lancer@gmail.com>
> > ---
> > .../devicetree/bindings/hwmon/ads1000.txt | 61 ++++++++++++++++
>
> Bindings should be separate patch.
>
> > Documentation/hwmon/ads1000.rst | 72 +++++++++++++++++++
> > 2 files changed, 133 insertions(+)
> > create mode 100644 Documentation/devicetree/bindings/hwmon/ads1000.txt
> > create mode 100644 Documentation/hwmon/ads1000.rst
> >
> > diff --git a/Documentation/devicetree/bindings/hwmon/ads1000.txt b/Documentation/devicetree/bindings/hwmon/ads1000.txt
> > new file mode 100644
> > index 000000000000..3907b7da9b33
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/hwmon/ads1000.txt
> > @@ -0,0 +1,61 @@
> > +ADS1000/ADS1100 (I2C)
> > +
> > +This device is a 12-16 bit A-D converter with 1 input.
>
> ADC's should be in bindings/iio/adc/
>
> > +
> > +The inputs can be used either as a differential pair of Vin+ Vin- or as a single
> > +ended sensor for Vin+ GND. The inputs mode is platform-dependent and isn't
> > +configured by software in any case.
> > +
> > +Device A-D converter sensitivity can be configured using two parameters:
> > + - pga is the programmable gain amplifier
> > + 0: x1 (default)
> > + 1: x2
> > + 2: x4
> > + 3: x8
> > + - data_rate in samples per second also affecting the output code accuracy
> > + 0: 128SPS - +/- Vdd*0.488mV (default, ads1000 accepts this rate only)
> > + 1: 32SPS - +/- Vdd*0.122mV
> > + 2: 16SPS - +/- Vdd*0.061mV
> > + 3: 8SPS - +/- Vdd*0.030mV
> > + Since this parameter also affects the output accuracy, be aware the greater
> > + SPS the worse accuracy.
> > +
> > +As a result the output value is calculated by the next formulae:
> > +dVin = Cod * Vdd / (PGA * max(|Cod|)), where
> > +max(|Cod|) - maximum possible value of the output code, which depends on the SPS
> > +setting from the table above.
> > +
> > +The ADS1000/ADS1100 dts-node:
> > +
> > + Required properties:
> > + - compatible : must be "ti,ads1000" or "ti,ads1100"
> > + - reg : I2C bus address of the device
> > + - #address-cells : must be <1>
> > + - #size-cells : must be <0>
> > + - vdd-supply : regulator for reference supply voltage (usually fixed)
> > +
> > + Optional properties:
> > + - ti,gain : the programmable gain amplifier setting
> > + - ti,datarate : the converter data rate
>
> IIRC, we have standard properties for these.
>
> > + - ti,voltage-divider : <R1 R2> Ohms inbound voltage dividers,
> > + so dVin = (R1 + R2)/R2 * dVin
> > +
> > +Example:
> > +
> > +vdd_5v0: fixedregulator@0 {
> > + compatible = "regulator-fixed";
> > + regulator-name = "vdd-ref";
> > + regulator-min-microvolt = <5000000>;
> > + regulator-max-microvolt = <5000000>;
> > + regulator-always-on;
> > +};
> > +
> > +tiadc: ads1000@48 {
>
> adc@48
>
> > + compatible = "ti,ads1000";
> > + reg = <0x48>;
> > +
> > + vdd-supply = <&vdd_5v0>;
> > + ti,gain = <0>;
> > + ti,voltage-divider = <31600 3600>;
> > +};
> > +
Thanks for this patch review. We had a conversation with Guenter Roeck
and Jonathan Cameron regarding the Linux subsystem to place this patchset
to, and decided to port the driver into the iio subsystem. So if this code
is ported as a separate driver I'll certainly take your comments into
account, while if I manage to integrate it into the existing ads1015 driver,
then this patch will be dropped since ads1015 already have the dedicated
bindings. In the last case sorry for wasting your time in advance.
Regards,
-Sergey
^ permalink raw reply
* Re: [RFC 0/7] Introduce TEE based Trusted Keys support
From: Sumit Garg @ 2019-06-14 5:58 UTC (permalink / raw)
To: Casey Schaufler
Cc: keyrings, linux-integrity, linux-security-module, Jens Wiklander,
corbet, dhowells, jejb, Jarkko Sakkinen, zohar, jmorris, serge,
Ard Biesheuvel, Daniel Thompson, linux-doc,
Linux Kernel Mailing List, tee-dev
In-Reply-To: <d803283e-5e69-5deb-fe94-3f2e45fb95af@schaufler-ca.com>
On Thu, 13 Jun 2019 at 22:10, Casey Schaufler <casey@schaufler-ca.com> wrote:
>
> On 6/13/2019 3:30 AM, Sumit Garg wrote:
> > Add support for TEE based trusted keys where TEE provides the functionality
> > to seal and unseal trusted keys using hardware unique key. Also, this is
> > an alternative in case platform doesn't possess a TPM device.
> >
> > This series also adds some TEE features like:
>
> Please expand the acronym TEE on first use. That will
> help people who don't work with it on a daily basis
> understand what you're going on about.
>
Sure will take care of this. BTW, its Trusted Execution Environment (TEE).
-Sumit
> >
> > Patch #1, #2 enables support for registered kernel shared memory with TEE.
> >
> > Patch #3 enables support for private kernel login method required for
> > cases like trusted keys where we don't wan't user-space to directly access
> > TEE service to retrieve trusted key contents.
> >
> > Rest of the patches from #4 to #7 adds support for TEE based trusted keys.
> >
> > This patch-set has been tested with OP-TEE based pseudo TA which can be
> > found here [1].
> >
> > Looking forward to your valuable feedback/suggestions.
> >
> > [1] https://github.com/OP-TEE/optee_os/pull/3082
> >
> > Sumit Garg (7):
> > tee: optee: allow kernel pages to register as shm
> > tee: enable support to register kernel memory
> > tee: add private login method for kernel clients
> > KEYS: trusted: Introduce TEE based Trusted Keys
> > KEYS: encrypted: Allow TEE based trusted master keys
> > doc: keys: Document usage of TEE based Trusted Keys
> > MAINTAINERS: Add entry for TEE based Trusted Keys
> >
> > Documentation/security/keys/tee-trusted.rst | 93 +++++
> > MAINTAINERS | 9 +
> > drivers/tee/optee/call.c | 7 +
> > drivers/tee/tee_core.c | 6 +
> > drivers/tee/tee_shm.c | 16 +-
> > include/keys/tee_trusted.h | 84 ++++
> > include/keys/trusted-type.h | 1 +
> > include/linux/tee_drv.h | 1 +
> > include/uapi/linux/tee.h | 2 +
> > security/keys/Kconfig | 3 +
> > security/keys/Makefile | 3 +
> > security/keys/encrypted-keys/masterkey_trusted.c | 10 +-
> > security/keys/tee_trusted.c | 506 +++++++++++++++++++++++
> > 13 files changed, 737 insertions(+), 4 deletions(-)
> > create mode 100644 Documentation/security/keys/tee-trusted.rst
> > create mode 100644 include/keys/tee_trusted.h
> > create mode 100644 security/keys/tee_trusted.c
> >
^ permalink raw reply
* Re: [RFC 4/7] KEYS: trusted: Introduce TEE based Trusted Keys
From: Sumit Garg @ 2019-06-14 5:43 UTC (permalink / raw)
To: Jarkko Sakkinen
Cc: keyrings, linux-integrity, linux-security-module, Jens Wiklander,
corbet, dhowells, jejb, zohar, jmorris, serge, Ard Biesheuvel,
Daniel Thompson, linux-doc, Linux Kernel Mailing List, tee-dev
In-Reply-To: <20190613153202.GF18488@linux.intel.com>
On Thu, 13 Jun 2019 at 21:02, Jarkko Sakkinen
<jarkko.sakkinen@linux.intel.com> wrote:
>
> On Thu, Jun 13, 2019 at 04:00:30PM +0530, Sumit Garg wrote:
> > Add support for TEE based trusted keys where TEE provides the functionality
> > to seal and unseal trusted keys using hardware unique key.
> >
> > Refer to Documentation/tee.txt for detailed information about TEE.
> >
> > Approach taken in this patch acts as an alternative to a TPM device in case
> > platform doesn't possess one.
> >
> > Signed-off-by: Sumit Garg <sumit.garg@linaro.org>
>
> How does this interact with the trusted module? Why there is no update
> to security/keys/trusted-encrypted.txt?
>
You already found documentation patch [1].
> Somehow the existing trusted module needs to be re-architected to work
> with either. Otherwise, this will turn out to be a mess.
>
See my reply on this patch [1].
[1] [RFC 6/7] doc: keys: Document usage of TEE based Trusted Keys
-Sumit
> /Jarkko
^ permalink raw reply
* Re: [RFC 6/7] doc: keys: Document usage of TEE based Trusted Keys
From: Sumit Garg @ 2019-06-14 5:37 UTC (permalink / raw)
To: Jarkko Sakkinen
Cc: keyrings, linux-integrity, linux-security-module, Jens Wiklander,
corbet, dhowells, jejb, zohar, jmorris, serge, Ard Biesheuvel,
Daniel Thompson, linux-doc, Linux Kernel Mailing List, tee-dev
In-Reply-To: <20190613153414.GG18488@linux.intel.com>
On Thu, 13 Jun 2019 at 21:04, Jarkko Sakkinen
<jarkko.sakkinen@linux.intel.com> wrote:
>
> On Thu, Jun 13, 2019 at 04:00:32PM +0530, Sumit Garg wrote:
> > Provide documentation for usage of TEE based Trusted Keys via existing
> > user-space "keyctl" utility. Also, document various use-cases.
> >
> > Signed-off-by: Sumit Garg <sumit.garg@linaro.org>
>
> Sorry missed this patch. Anyway, I don't think we want multiple trusted
> keys subsystems. You have to fix the existing one if you care to get
> these changes in. There is no really other way around this.
>
I understand your point.
When I initially looked at trusted key implementation, it seemed to be
tightly coupled to use TPM device. So I implemented a parallel
implementation to get initial feedback (functionality-wise) on this
new approach.
I will work on abstraction of trusted key apis to use either approach.
But is it fine with you if I send if I send a separate RFC patch for
abstraction and later once reviewed I will incorporate that patch in
this patch-set.
It will be really helpful if you could help to test that abstraction
patch with a real TPM device as I doesn't posses one to test.
-Sumit
> /Jarkko
^ permalink raw reply
* Re: [PATCH] docs: stop suggesting strlcpy
From: Kees Cook @ 2019-06-14 5:20 UTC (permalink / raw)
To: Stephen Kitt; +Cc: corbet, federico.vaga, linux-doc, linux-kernel
In-Reply-To: <20190613162548.19792-1-steve@sk2.org>
On Thu, Jun 13, 2019 at 06:25:48PM +0200, Stephen Kitt wrote:
> Since strlcpy is deprecated, the documentation shouldn't suggest using
> it. This patch fixes the examples to use strscpy instead. It also uses
> sizeof instead of underlying constants as far as possible, to simplify
> future changes to the corresponding data structures.
>
> Signed-off-by: Stephen Kitt <steve@sk2.org>
Yes please!
Acked-by: Kees Cook <keescook@chromium.org>
-Kees
> ---
> Documentation/hid/hid-transport.txt | 6 +++---
> Documentation/i2c/instantiating-devices | 2 +-
> Documentation/i2c/upgrading-clients | 4 ++--
> Documentation/kernel-hacking/locking.rst | 6 +++---
> Documentation/translations/it_IT/kernel-hacking/locking.rst | 6 +++---
> 5 files changed, 12 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/hid/hid-transport.txt b/Documentation/hid/hid-transport.txt
> index 3dcba9fd4a3a..4f41d67f1b4b 100644
> --- a/Documentation/hid/hid-transport.txt
> +++ b/Documentation/hid/hid-transport.txt
> @@ -194,9 +194,9 @@ with HID core:
> goto err_<...>;
> }
>
> - strlcpy(hid->name, <device-name-src>, 127);
> - strlcpy(hid->phys, <device-phys-src>, 63);
> - strlcpy(hid->uniq, <device-uniq-src>, 63);
> + strscpy(hid->name, <device-name-src>, sizeof(hid->name));
> + strscpy(hid->phys, <device-phys-src>, sizeof(hid->phys));
> + strscpy(hid->uniq, <device-uniq-src>, sizeof(hid->uniq));
>
> hid->ll_driver = &custom_ll_driver;
> hid->bus = <device-bus>;
> diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices
> index 0d85ac1935b7..8bc7d99133e3 100644
> --- a/Documentation/i2c/instantiating-devices
> +++ b/Documentation/i2c/instantiating-devices
> @@ -137,7 +137,7 @@ static int usb_hcd_nxp_probe(struct platform_device *pdev)
> (...)
> i2c_adap = i2c_get_adapter(2);
> memset(&i2c_info, 0, sizeof(struct i2c_board_info));
> - strlcpy(i2c_info.type, "isp1301_nxp", I2C_NAME_SIZE);
> + strscpy(i2c_info.type, "isp1301_nxp", sizeof(i2c_info.type));
> isp1301_i2c_client = i2c_new_probed_device(i2c_adap, &i2c_info,
> normal_i2c, NULL);
> i2c_put_adapter(i2c_adap);
> diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients
> index ccba3ffd6e80..96392cc5b5c7 100644
> --- a/Documentation/i2c/upgrading-clients
> +++ b/Documentation/i2c/upgrading-clients
> @@ -43,7 +43,7 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind)
> example->client.adapter = adap;
>
> i2c_set_clientdata(&state->i2c_client, state);
> - strlcpy(client->i2c_client.name, "example", I2C_NAME_SIZE);
> + strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
>
> ret = i2c_attach_client(&state->i2c_client);
> if (ret < 0) {
> @@ -138,7 +138,7 @@ can be removed:
> - example->client.flags = 0;
> - example->client.adapter = adap;
> -
> -- strlcpy(client->i2c_client.name, "example", I2C_NAME_SIZE);
> +- strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
>
> The i2c_set_clientdata is now:
>
> diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
> index 519673df0e82..dc698ea456e0 100644
> --- a/Documentation/kernel-hacking/locking.rst
> +++ b/Documentation/kernel-hacking/locking.rst
> @@ -451,7 +451,7 @@ to protect the cache and all the objects within it. Here's the code::
> if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
> return -ENOMEM;
>
> - strlcpy(obj->name, name, sizeof(obj->name));
> + strscpy(obj->name, name, sizeof(obj->name));
> obj->id = id;
> obj->popularity = 0;
>
> @@ -660,7 +660,7 @@ Here is the code::
> }
>
> @@ -63,6 +94,7 @@
> - strlcpy(obj->name, name, sizeof(obj->name));
> + strscpy(obj->name, name, sizeof(obj->name));
> obj->id = id;
> obj->popularity = 0;
> + obj->refcnt = 1; /* The cache holds a reference */
> @@ -774,7 +774,7 @@ the lock is no longer used to protect the reference count itself.
> }
>
> @@ -94,7 +76,7 @@
> - strlcpy(obj->name, name, sizeof(obj->name));
> + strscpy(obj->name, name, sizeof(obj->name));
> obj->id = id;
> obj->popularity = 0;
> - obj->refcnt = 1; /* The cache holds a reference */
> diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst
> index 0ef31666663b..5fd8a1abd2be 100644
> --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
> +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
> @@ -468,7 +468,7 @@ e tutti gli oggetti che contiene. Ecco il codice::
> if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
> return -ENOMEM;
>
> - strlcpy(obj->name, name, sizeof(obj->name));
> + strscpy(obj->name, name, sizeof(obj->name));
> obj->id = id;
> obj->popularity = 0;
>
> @@ -678,7 +678,7 @@ Ecco il codice::
> }
>
> @@ -63,6 +94,7 @@
> - strlcpy(obj->name, name, sizeof(obj->name));
> + strscpy(obj->name, name, sizeof(obj->name));
> obj->id = id;
> obj->popularity = 0;
> + obj->refcnt = 1; /* The cache holds a reference */
> @@ -792,7 +792,7 @@ contatore stesso.
> }
>
> @@ -94,7 +76,7 @@
> - strlcpy(obj->name, name, sizeof(obj->name));
> + strscpy(obj->name, name, sizeof(obj->name));
> obj->id = id;
> obj->popularity = 0;
> - obj->refcnt = 1; /* The cache holds a reference */
> --
> 2.11.0
>
--
Kees Cook
^ permalink raw reply
* Re: [RFC 2/7] tee: enable support to register kernel memory
From: Sumit Garg @ 2019-06-14 5:13 UTC (permalink / raw)
To: Jarkko Sakkinen
Cc: keyrings, linux-integrity, linux-security-module, Jens Wiklander,
corbet, dhowells, jejb, zohar, jmorris, serge, Ard Biesheuvel,
Daniel Thompson, linux-doc, Linux Kernel Mailing List, tee-dev
In-Reply-To: <20190613152003.GE18488@linux.intel.com>
On Thu, 13 Jun 2019 at 20:50, Jarkko Sakkinen
<jarkko.sakkinen@linux.intel.com> wrote:
>
> On Thu, Jun 13, 2019 at 04:00:28PM +0530, Sumit Garg wrote:
> > Enable support to register kernel memory reference with TEE. This change
> > will allow TEE bus drivers to register memory references.
> >
> > Signed-off-by: Sumit Garg <sumit.garg@linaro.org>
>
> Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
>
Thanks.
-Sumit
> /Jarkko
^ permalink raw reply
* Re: [RFC 1/7] tee: optee: allow kernel pages to register as shm
From: Sumit Garg @ 2019-06-14 5:12 UTC (permalink / raw)
To: Jarkko Sakkinen
Cc: keyrings, linux-integrity, linux-security-module, Jens Wiklander,
corbet, dhowells, jejb, zohar, jmorris, serge, Ard Biesheuvel,
Daniel Thompson, linux-doc, Linux Kernel Mailing List, tee-dev
In-Reply-To: <20190613151746.GD18488@linux.intel.com>
On Thu, 13 Jun 2019 at 20:47, Jarkko Sakkinen
<jarkko.sakkinen@linux.intel.com> wrote:
>
> On Thu, Jun 13, 2019 at 06:17:14PM +0300, Jarkko Sakkinen wrote:
> > On Thu, Jun 13, 2019 at 06:12:57PM +0300, Jarkko Sakkinen wrote:
> > > On Thu, Jun 13, 2019 at 04:00:27PM +0530, Sumit Garg wrote:
> > > > Kernel pages are marked as normal type memory only so allow kernel pages
> > > > to be registered as shared memory with OP-TEE.
> > > >
> > > > Signed-off-by: Sumit Garg <sumit.garg@linaro.org>
> > >
> > > Just out of pure interest why this was not allowed before?
> >
> > Please spare me and ignore that one :-) Obviouslly because it
> > was not used.
> >
> > Acked-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
>
> Actually,
>
> Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
>
Thanks.
-Sumit
> /Jarkko
^ permalink raw reply
* [PATCH 10/14] scripts/get_abi.pl: represent what in tables
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mauro Carvalho Chehab
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Several entries at the ABI have multiple What: with the same
description.
Instead of showing those symbols as sections, let's show them
as tables. That makes easier to read on the final output,
and avoid too much recursion at Sphinx parsing.
We need to put file references at the end, as we don't want
non-file tables to be mangled with other entries.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 41 ++++++++++++++++++++++++++++++++++++-----
1 file changed, 36 insertions(+), 5 deletions(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index c202292af1a2..a2861fcec745 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -193,16 +193,19 @@ sub parse_abi {
#
# Outputs the book on ReST format
#
+
sub output_rest {
- foreach my $what (sort keys %data) {
+ foreach my $what (sort {
+ ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
+ $a cmp $b
+ } keys %data) {
my $type = $data{$what}->{type};
my $file = $data{$what}->{file};
+ my $filepath = $data{$what}->{filepath};
my $w = $what;
$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
- my $bar = $w;
- $bar =~ s/./-/g;
foreach my $p (@{$data{$what}->{label}}) {
my ($content, $label) = @{$p};
@@ -222,9 +225,37 @@ sub output_rest {
last;
}
- print "$w\n$bar\n\n";
- print "- defined on file $file (type: $type)\n\n" if ($type ne "File");
+ $filepath =~ s,.*/(.*/.*),\1,;;
+ $filepath =~ s,[/\-],_,g;;
+ my $fileref = "abi_file_".$filepath;
+
+ if ($type eq "File") {
+ my $bar = $w;
+ $bar =~ s/./-/g;
+
+ print ".. _$fileref:\n\n";
+ print "$w\n$bar\n\n";
+ } else {
+ my @names = split /\s*,\s*/,$w;
+
+ my $len = 0;
+
+ foreach my $name (@names) {
+ $len = length($name) if (length($name) > $len);
+ }
+
+ print "What:\n\n";
+
+ print "+-" . "-" x $len . "-+\n";
+ foreach my $name (@names) {
+ printf "| %s", $name . " " x ($len - length($name)) . " |\n";
+ print "+-" . "-" x $len . "-+\n";
+ }
+ print "\n";
+ }
+
+ print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File");
my $desc = $data{$what}->{description};
$desc =~ s/^\s+//;
--
2.21.0
^ permalink raw reply related
* [PATCH 05/14] scripts: add an script to parse the ABI files
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mauro Carvalho Chehab
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Add a script to parse the Documentation/ABI files and produce
an output with all entries inside an ABI (sub)directory.
Right now, it outputs its contents on ReST format. It shouldn't
be hard to make it produce other kind of outputs, since the ABI
file parser is implemented in separate than the output generator.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 212 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 212 insertions(+)
create mode 100755 scripts/get_abi.pl
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
new file mode 100755
index 000000000000..f7c9944a833c
--- /dev/null
+++ b/scripts/get_abi.pl
@@ -0,0 +1,212 @@
+#!/usr/bin/perl
+
+use strict;
+use Pod::Usage;
+use Getopt::Long;
+use File::Find;
+use Fcntl ':mode';
+
+my $help;
+my $man;
+my $debug;
+
+GetOptions(
+ "debug|d+" => \$debug,
+ 'help|?' => \$help,
+ man => \$man
+) or pod2usage(2);
+
+pod2usage(1) if $help;
+pod2usage(-exitstatus => 0, -verbose => 2) if $man;
+
+pod2usage(2) if (scalar @ARGV != 1);
+
+my ($prefix) = @ARGV;
+
+require Data::Dumper if ($debug);
+
+my %data;
+
+#
+# Displays an error message, printing file name and line
+#
+sub parse_error($$$$) {
+ my ($file, $ln, $msg, $data) = @_;
+
+ print STDERR "file $file#$ln: $msg at\n\t$data";
+}
+
+#
+# Parse an ABI file, storing its contents at %data
+#
+sub parse_abi {
+ my $file = $File::Find::name;
+
+ my $mode = (stat($file))[2];
+ return if ($mode & S_IFDIR);
+ return if ($file =~ m,/README,);
+
+ my $name = $file;
+ $name =~ s,.*/,,;
+
+ my $type = $file;
+ $type =~ s,.*/(.*)/.*,$1,;
+
+ my $what;
+ my $new_what;
+ my $tag;
+ my $ln;
+
+ print STDERR "Opening $file\n" if ($debug > 1);
+ open IN, $file;
+ while(<IN>) {
+ $ln++;
+ if (m/^(\S+):\s*(.*)/i) {
+ my $new_tag = lc($1);
+ my $content = $2;
+
+ if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) {
+ if ($tag eq "description") {
+ $data{$what}->{$tag} .= "\n$content";;
+ $data{$what}->{$tag} =~ s/\n+$//;
+ next;
+ } else {
+ parse_error($file, $ln, "tag '$tag' is invalid", $_);
+ }
+ }
+
+ if ($new_tag =~ m/what/) {
+ if ($tag =~ m/what/) {
+ $what .= ", " . $content;
+ } else {
+ $what = $content;
+ $new_what = 1;
+ }
+ $tag = $new_tag;
+ next;
+ }
+
+ $tag = $new_tag;
+
+ if ($new_what) {
+ $new_what = 0;
+
+ $data{$what}->{type} = $type;
+ $data{$what}->{file} = $name;
+ print STDERR "\twhat: $what\n" if ($debug > 1);
+ }
+
+ if (!$what) {
+ parse_error($file, $ln, "'What:' should come first:", $_);
+ next;
+ }
+ $data{$what}->{$tag} = $content;
+ next;
+ }
+
+ # Silently ignore any headers before the database
+ next if (!$tag);
+
+ if (m/^\s*(.*)/) {
+ $data{$what}->{$tag} .= "\n$1";
+ $data{$what}->{$tag} =~ s/\n+$//;
+ next;
+ }
+
+ # Everything else is error
+ parse_error($file, $ln, "Unexpected line:", $_);
+ }
+ close IN;
+}
+
+# Outputs the output on ReST format
+sub output_rest {
+ foreach my $what (sort keys %data) {
+ my $type = $data{$what}->{type};
+ my $file = $data{$what}->{file};
+
+ my $w = $what;
+ $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
+
+ print "$w\n\n";
+ print "- defined on file $file (type: $type)\n\n::\n\n";
+
+ my $desc = $data{$what}->{description};
+ $desc =~ s/^\s+//;
+
+ # Remove title markups from the description, as they won't work
+ $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g;
+
+ # put everything inside a code block
+ $desc =~ s/\n/\n /g;
+
+
+ if (!($desc =~ /^\s*$/)) {
+ print " $desc\n\n";
+ } else {
+ print " DESCRIPTION MISSING\n\n";
+ }
+ }
+}
+
+#
+# Parses all ABI files located at $prefix dir
+#
+find({wanted =>\&parse_abi, no_chdir => 1}, $prefix);
+
+print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);
+
+#
+# Outputs an ReST file with the ABI contents
+#
+output_rest
+
+
+__END__
+
+=head1 NAME
+
+abi_book.pl - parse the Linux ABI files and produce a ReST book.
+
+=head1 SYNOPSIS
+
+B<abi_book.pl> [--debug] <ABI_DIR>]
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<--debug>
+
+Put the script in verbose mode, useful for debugging. Can be called multiple
+times, to increase verbosity.
+
+=item B<--help>
+
+Prints a brief help message and exits.
+
+=item B<--man>
+
+Prints the manual page and exits.
+
+=back
+
+=head1 DESCRIPTION
+
+Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI)
+and produce a ReST book containing the Linux ABI.
+
+=head1 BUGS
+
+Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
+
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+=cut
--
2.21.0
^ permalink raw reply related
* [PATCH 12/14] doc-rst: add ABI documentation to the admin-guide book
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mauro Carvalho Chehab
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
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@s-opensource.com>
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 | 1 +
Documentation/conf.py | 2 +-
Documentation/sphinx/kernel_abi.py | 155 +++++++++++++++++++++
8 files changed, 214 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
create mode 100644 Documentation/sphinx/kernel_abi.py
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..3b9645c77469
--- /dev/null
+++ b/Documentation/admin-guide/abi.rst
@@ -0,0 +1,11 @@
+=====================
+Linux ABI description
+=====================
+
+.. toctree::
+ :maxdepth: 1
+
+ abi-stable
+ abi-testing
+ abi-obsolete
+ abi-removed
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 8001917ee012..20c3020fd73c 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -16,6 +16,7 @@ etc.
README
kernel-parameters
devices
+ abi
This section describes CPU vulnerabilities and their mitigations.
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 7ace3f8852bd..598256fb5c98 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -34,7 +34,7 @@ needs_sphinx = '1.3'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig']
+extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig', 'kernel_abi']
# The name of the math extension changed on Sphinx 1.4
if (major == 1 and minor > 3) or (major > 1):
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
new file mode 100644
index 000000000000..32ce90775d96
--- /dev/null
+++ b/Documentation/sphinx/kernel_abi.py
@@ -0,0 +1,155 @@
+# -*- coding: utf-8; mode: python -*-
+u"""
+ kernel-abi
+ ~~~~~~~~~~
+
+ Implementation of the ``kernel-abi`` reST-directive.
+
+ :copyright: Copyright (C) 2016 Markus Heiser
+ :copyright: Copyright (C) 2016 Mauro Carvalho Chehab
+ :license: GPL Version 2, June 1991 see Linux/COPYING for details.
+
+ The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the
+ scripts/get_abi.pl script to parse the Kernel ABI files.
+
+ Overview of directive's argument and options.
+
+ .. code-block:: rst
+
+ .. kernel-abi:: <ABI directory location>
+ :debug:
+
+ The argument ``<ABI directory location>`` is required. It contains the
+ location of the ABI files to be parsed.
+
+ ``debug``
+ Inserts a code-block with the *raw* reST. Sometimes it is helpful to see
+ what reST is generated.
+
+"""
+
+import sys
+import os
+from os import path
+import subprocess
+
+from sphinx.ext.autodoc import AutodocReporter
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import ViewList
+from docutils.utils.error_reporting import ErrorString
+
+
+__version__ = '1.0'
+
+# We can't assume that six is installed
+PY3 = sys.version_info[0] == 3
+PY2 = sys.version_info[0] == 2
+if PY3:
+ # pylint: disable=C0103, W0622
+ unicode = str
+ basestring = str
+
+def setup(app):
+
+ app.add_directive("kernel-abi", KernelCmd)
+ return dict(
+ version = __version__
+ , parallel_read_safe = True
+ , parallel_write_safe = True
+ )
+
+class KernelCmd(Directive):
+
+ u"""KernelABI (``kernel-abi``) directive"""
+
+ required_arguments = 1
+ optional_arguments = 0
+ has_content = False
+ final_argument_whitespace = True
+
+ option_spec = {
+ "debug" : directives.flag
+ }
+
+ def warn(self, message, **replace):
+ replace["fname"] = self.state.document.current_source
+ replace["line_no"] = replace.get("line_no", self.lineno)
+ message = ("%(fname)s:%(line_no)s: [kernel-abi WARN] : " + message) % replace
+ self.state.document.settings.env.app.warn(message, prefix="")
+
+ def run(self):
+
+ doc = self.state.document
+ if not doc.settings.file_insertion_enabled:
+ raise self.warning("docutils: file insertion disabled")
+
+ env = doc.settings.env
+ cwd = path.dirname(doc.current_source)
+ cmd = "get_abi.pl rest --dir "
+ cmd += self.arguments[0]
+
+ srctree = path.abspath(os.environ["srctree"])
+
+ fname = cmd
+
+ # extend PATH with $(srctree)/scripts
+ path_env = os.pathsep.join([
+ srctree + os.sep + "scripts",
+ os.environ["PATH"]
+ ])
+ shell_env = os.environ.copy()
+ shell_env["PATH"] = path_env
+ shell_env["srctree"] = srctree
+
+ lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
+ nodeList = self.nestedParse(lines, fname)
+ return nodeList
+
+ def runCmd(self, cmd, **kwargs):
+ u"""Run command ``cmd`` and return it's stdout as unicode."""
+
+ try:
+ proc = subprocess.Popen(
+ cmd
+ , stdout = subprocess.PIPE
+ , stderr = subprocess.PIPE
+ , universal_newlines = True
+ , **kwargs
+ )
+ out, err = proc.communicate()
+ if err:
+ self.warn(err)
+ if proc.returncode != 0:
+ raise self.severe(
+ u"command '%s' failed with return code %d"
+ % (cmd, proc.returncode)
+ )
+ except OSError as exc:
+ raise self.severe(u"problems with '%s' directive: %s."
+ % (self.name, ErrorString(exc)))
+ return unicode(out)
+
+ def nestedParse(self, lines, fname):
+ content = ViewList()
+ node = nodes.section()
+
+ if "debug" in self.options:
+ code_block = "\n\n.. code-block:: rst\n :linenos:\n"
+ for l in lines.split("\n"):
+ code_block += "\n " + l
+ lines = code_block + "\n\n"
+
+ for c, l in enumerate(lines.split("\n")):
+ content.append(l, fname, c)
+
+ buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+ self.state.memo.title_styles = []
+ self.state.memo.section_level = 0
+ self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
+ try:
+ self.state.nested_parse(content, 0, node, match_titles=1)
+ finally:
+ self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+ return node.children
--
2.21.0
^ permalink raw reply related
* [PATCH 11/14] scripts/get_abi.pl: fix parse issues with some files
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
A few files are failing to parse:
Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
Documentation/ABI/testing/sysfs-class-pktcdvd
Documentation/ABI/testing/sysfs-bus-nfit
On all three files, the problem is that there is a ":" character
at the initial file description.
Improve the parse in order to handle those special cases.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index a2861fcec745..c3ccfdfc3a5d 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -87,7 +87,7 @@ sub parse_abi {
# New "tag" is actually part of
# description. Don't consider it a tag
$new_tag = "";
- } else {
+ } elsif ($tag ne "") {
parse_error($file, $ln, "tag '$tag' is invalid", $_);
}
}
@@ -110,7 +110,7 @@ sub parse_abi {
next;
}
- if ($new_tag) {
+ if ($tag ne "" && $new_tag) {
$tag = $new_tag;
if ($new_what) {
--
2.21.0
^ permalink raw reply related
* [PATCH 09/14] scripts/get_abi.pl: add support for searching for ABI symbols
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mauro Carvalho Chehab
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Change its syntax to allow switching between ReST output mode
and a new search mode, with allows to seek for ABI symbols
using regex.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 112 +++++++++++++++++++++++++++++++++++++++++----
1 file changed, 103 insertions(+), 9 deletions(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index d437e148b1c0..c202292af1a2 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -9,9 +9,11 @@ use Fcntl ':mode';
my $help;
my $man;
my $debug;
+my $prefix="Documentation/ABI";
GetOptions(
"debug|d+" => \$debug,
+ "dir=s" => \$prefix,
'help|?' => \$help,
man => \$man
) or pod2usage(2);
@@ -19,9 +21,12 @@ GetOptions(
pod2usage(1) if $help;
pod2usage(-exitstatus => 0, -verbose => 2) if $man;
-pod2usage(2) if (scalar @ARGV != 1);
+pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2);
-my ($prefix) = @ARGV;
+my ($cmd, $arg) = @ARGV;
+
+pod2usage(2) if ($cmd ne "search" && $cmd ne "rest");
+pod2usage(2) if ($cmd eq "search" && !$arg);
require Data::Dumper if ($debug);
@@ -53,6 +58,7 @@ sub parse_abi {
$data{$nametag}->{what} = "File $name";
$data{$nametag}->{type} = "File";
$data{$nametag}->{file} = $name;
+ $data{$nametag}->{filepath} = $file;
$data{$nametag}->{is_file} = 1;
my $type = $file;
@@ -115,6 +121,7 @@ sub parse_abi {
$data{$what}->{type} = $type;
$data{$what}->{file} = $name;
+ $data{$what}->{filepath} = $file;
print STDERR "\twhat: $what\n" if ($debug > 1);
}
@@ -183,7 +190,9 @@ sub parse_abi {
close IN;
}
-# Outputs the output on ReST format
+#
+# Outputs the book on ReST format
+#
sub output_rest {
foreach my $what (sort keys %data) {
my $type = $data{$what}->{type};
@@ -262,6 +271,45 @@ sub output_rest {
}
}
+#
+# Searches for ABI symbols
+#
+sub search_symbols {
+ foreach my $what (sort keys %data) {
+ next if (!($what =~ m/($arg)/));
+
+ my $type = $data{$what}->{type};
+ next if ($type eq "File");
+
+ my $file = $data{$what}->{filepath};
+
+ my $bar = $what;
+ $bar =~ s/./-/g;
+
+ print "\n$what\n$bar\n\n";
+
+ my $kernelversion = $data{$what}->{kernelversion};
+ my $contact = $data{$what}->{contact};
+ my $users = $data{$what}->{users};
+ my $date = $data{$what}->{date};
+ my $desc = $data{$what}->{description};
+ $kernelversion =~ s/^\s+//;
+ $contact =~ s/^\s+//;
+ $users =~ s/^\s+//;
+ $users =~ s/\n//g;
+ $date =~ s/^\s+//;
+ $desc =~ s/^\s+//;
+
+ printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion);
+ printf "Date:\t\t\t%s\n", $date if ($date);
+ printf "Contact:\t\t%s\n", $contact if ($contact);
+ printf "Users:\t\t\t%s\n", $users if ($users);
+ print "Defined on file:\t$file\n\n";
+ print "Description:\n\n$desc";
+ }
+}
+
+
#
# Parses all ABI files located at $prefix dir
#
@@ -270,9 +318,13 @@ find({wanted =>\&parse_abi, no_chdir => 1}, $prefix);
print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);
#
-# Outputs an ReST file with the ABI contents
+# Handles the command
#
-output_rest
+if ($cmd eq "rest") {
+ output_rest;
+} else {
+ search_symbols;
+}
__END__
@@ -283,12 +335,27 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book.
=head1 SYNOPSIS
-B<abi_book.pl> [--debug] <ABI_DIR>]
+B<abi_book.pl> [--debug] <COMAND> [<ARGUMENT>]
+
+Where <COMMAND> can be:
+
+=over 8
+
+B<search> [SEARCH_REGEX] - search for [SEARCH_REGEX] inside ABI
+
+B<rest> - output the ABI in ReST markup language
+
+=back
=head1 OPTIONS
=over 8
+=item B<--dir>
+
+Changes the location of the ABI search. By default, it uses
+the Documentation/ABI directory.
+
=item B<--debug>
Put the script in verbose mode, useful for debugging. Can be called multiple
@@ -306,8 +373,35 @@ Prints the manual page and exits.
=head1 DESCRIPTION
-Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI)
-and produce a ReST book containing the Linux ABI.
+Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI),
+allowing to search for ABI symbols or to produce a ReST book containing
+the Linux ABI documentation.
+
+=head1 EXAMPLES
+
+Search for all stable symbols with the word "usb":
+
+=over 8
+
+$ scripts/get_abi.pl search usb --dir Documentation/ABI/stable
+
+=back
+
+Search for all symbols that match the regex expression "usb.*cap":
+
+=over 8
+
+$ scripts/get_abi.pl search usb.*cap
+
+=back
+
+Output all obsoleted symbols in ReST format
+
+=over 8
+
+$ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete
+
+=back
=head1 BUGS
@@ -315,7 +409,7 @@ Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>
=head1 COPYRIGHT
-Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
+Copyright (c) 2016-2017 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
--
2.21.0
^ permalink raw reply related
* [PATCH 07/14] scripts/get_abi.pl: avoid use literal blocks when not needed
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mauro Carvalho Chehab
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
The usage of literal blocks make the document very complex,
causing the browser to take a long time to load.
On most ABI descriptions, they're a plain text, and don't
require a literal block.
So, add a logic there with identifies when a literal block
is needed.
As, on literal blocks, we need to respect the original
document space, the most complex part of this patch is
to preserve the original spacing where needed.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 104 +++++++++++++++++++++++++++++++++------------
1 file changed, 78 insertions(+), 26 deletions(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index ac0f057fa3ca..ba8a7466f896 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -59,29 +59,34 @@ sub parse_abi {
my $ln;
my $has_file;
my $xrefs;
+ my $space;
print STDERR "Opening $file\n" if ($debug > 1);
open IN, $file;
while(<IN>) {
$ln++;
- if (m/^(\S+):\s*(.*)/i) {
+ if (m/^(\S+)(:\s*)(.*)/i) {
my $new_tag = lc($1);
- my $content = $2;
+ my $sep = $2;
+ my $content = $3;
if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) {
if ($tag eq "description") {
- $data{$what}->{$tag} .= "\n$content";
- $data{$what}->{$tag} =~ s/\n+$//;
- next;
+ # New "tag" is actually part of
+ # description. Don't consider it a tag
+ $new_tag = "";
} else {
parse_error($file, $ln, "tag '$tag' is invalid", $_);
}
}
if ($new_tag =~ m/what/) {
+ $space = "";
if ($tag =~ m/what/) {
$what .= ", " . $content;
} else {
+ parse_error($file, $ln, "What '$what' doesn't have a description", "") if ($what && !$data{$what}->{description});
+
$what = $content;
$new_what = 1;
}
@@ -108,25 +113,38 @@ sub parse_abi {
next;
}
- $tag = $new_tag;
+ if ($new_tag) {
+ $tag = $new_tag;
- if ($new_what) {
- $new_what = 0;
+ if ($new_what) {
+ $new_what = 0;
- $data{$what}->{type} = $type;
- $data{$what}->{file} = $name;
- print STDERR "\twhat: $what\n" if ($debug > 1);
- }
+ $data{$what}->{type} = $type;
+ $data{$what}->{file} = $name;
+ print STDERR "\twhat: $what\n" if ($debug > 1);
+ }
- if (!$what) {
- parse_error($file, $ln, "'What:' should come first:", $_);
+ if (!$what) {
+ parse_error($file, $ln, "'What:' should come first:", $_);
+ next;
+ }
+ if ($tag eq "description") {
+ next if ($content =~ m/^\s*$/);
+ if ($content =~ m/^(\s*)(.*)/) {
+ my $new_content = $2;
+ $space = $new_tag . $sep . $1;
+ while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
+ $space =~ s/./ /g;
+ $data{$what}->{$tag} .= "$new_content\n";
+ }
+ } else {
+ $data{$what}->{$tag} = $content;
+ }
next;
}
- $data{$what}->{$tag} = $content;
- next;
}
- # Store any contents before the database
+ # Store any contents before tags at the database
if (!$tag) {
next if (/^\n/);
@@ -139,6 +157,32 @@ sub parse_abi {
next;
}
+ if ($tag eq "description") {
+ if (!$data{$what}->{description}) {
+ next if (m/^\s*\n/);
+ if (m/^(\s*)(.*)/) {
+ $space = $1;
+ while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
+ $data{$what}->{$tag} .= "$2\n";
+ }
+ } else {
+ my $content = $_;
+ if (m/^\s*\n/) {
+ $data{$what}->{$tag} .= $content;
+ next;
+ }
+
+ while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
+ $space = "" if (!($content =~ s/^($space)//));
+
+ # Compress spaces with tabs
+ $content =~ s<^ {8}> <\t>;
+ $content =~ s<^ {1,7}\t> <\t>;
+ $content =~ s< {1,7}\t> <\t>;
+ $data{$what}->{$tag} .= $content;
+ }
+ next;
+ }
if (m/^\s*(.*)/) {
$data{$what}->{$tag} .= "\n$1";
$data{$what}->{$tag} =~ s/\n+$//;
@@ -165,6 +209,9 @@ sub output_rest {
my $w = $what;
$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
+ my $bar = $w;
+ $bar =~ s/./-/g;
+
if ($data{$what}->{label}) {
my @labels = split(/\s/, $data{$what}->{label});
foreach my $label (@labels) {
@@ -172,10 +219,9 @@ sub output_rest {
}
}
- print "$w\n\n";
+ print "$w\n$bar\n\n";
print "- defined on file $file (type: $type)\n\n" if ($type ne "File");
- print "::\n\n";
my $desc = $data{$what}->{description};
$desc =~ s/^\s+//;
@@ -183,18 +229,24 @@ sub output_rest {
# Remove title markups from the description, as they won't work
$desc =~ s/\n[\-\*\=\^\~]+\n/\n/g;
- # put everything inside a code block
- $desc =~ s/\n/\n /g;
-
-
if (!($desc =~ /^\s*$/)) {
- print " $desc\n\n";
+ if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
+ # put everything inside a code block
+ $desc =~ s/\n/\n /g;
+
+ print "::\n\n";
+ print " $desc\n\n";
+ } else {
+ # Escape any special chars from description
+ $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
+
+ print "$desc\n\n";
+ }
} else {
- print " DESCRIPTION MISSING for $what\n\n";
+ print "DESCRIPTION MISSING for $what\n\n";
}
printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs});
-
}
}
--
2.21.0
^ permalink raw reply related
* [PATCH 02/14] ABI: sysfs-driver-hid: the "What" field doesn't parse fine
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mauro Carvalho Chehab
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
The What: field on this ABI description use a different
syntax than expected, causing it to not be properly parsed
by script.
Fix it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/testing/sysfs-driver-hid | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/ABI/testing/sysfs-driver-hid b/Documentation/ABI/testing/sysfs-driver-hid
index 48942cacb0bf..a59533410871 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid
+++ b/Documentation/ABI/testing/sysfs-driver-hid
@@ -1,6 +1,6 @@
-What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
- For BT devices : /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
- Symlink : /sys/class/hidraw/hidraw<num>/device/report_descriptor
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
+What: /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
+What: /sys/class/hidraw/hidraw<num>/device/report_descriptor
Date: Jan 2011
KernelVersion: 2.0.39
Contact: Alan Ott <alan@signal11.us>
@@ -9,9 +9,9 @@ Description: When read, this file returns the device's raw binary HID
This file cannot be written.
Users: HIDAPI library (http://www.signal11.us/oss/hidapi)
-What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
- For BT devices : /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
- Symlink : /sys/class/hidraw/hidraw<num>/device/country
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
+What: /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
+What: /sys/class/hidraw/hidraw<num>/device/country
Date: February 2015
KernelVersion: 3.19
Contact: Olivier Gay <ogay@logitech.com>
--
2.21.0
^ permalink raw reply related
* [PATCH 08/14] scripts/get_abi.pl: split label naming from xref logic
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mauro Carvalho Chehab
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Instead of using a ReST compilant label while parsing,
move the label to ReST output. That makes the parsing logic
more generic, allowing it to provide other types of output.
As a side effect, now all files used to generate the output
will be output. We can later add command line arguments to
filter.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 94 ++++++++++++++++++++++++++--------------------
1 file changed, 53 insertions(+), 41 deletions(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index ba8a7466f896..d437e148b1c0 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -49,17 +49,23 @@ sub parse_abi {
my $name = $file;
$name =~ s,.*/,,;
+ my $nametag = "File $name";
+ $data{$nametag}->{what} = "File $name";
+ $data{$nametag}->{type} = "File";
+ $data{$nametag}->{file} = $name;
+ $data{$nametag}->{is_file} = 1;
+
my $type = $file;
$type =~ s,.*/(.*)/.*,$1,;
my $what;
my $new_what;
my $tag;
- my $label;
my $ln;
- my $has_file;
my $xrefs;
my $space;
+ my @labels;
+ my $label;
print STDERR "Opening $file\n" if ($debug > 1);
open IN, $file;
@@ -88,28 +94,13 @@ sub parse_abi {
parse_error($file, $ln, "What '$what' doesn't have a description", "") if ($what && !$data{$what}->{description});
$what = $content;
+ $label = $content;
$new_what = 1;
}
+ push @labels, [($content, $label)];
$tag = $new_tag;
- if ($has_file) {
- $label = "abi_" . $content . " ";
- $label =~ tr/A-Z/a-z/;
-
- # Convert special chars to "_"
- $label =~s/[\x00-\x2f]+/_/g;
- $label =~s/[\x3a-\x40]+/_/g;
- $label =~s/[\x7b-\xff]+/_/g;
- $label =~ s,_+,_,g;
- $label =~ s,_$,,;
-
- $data{$what}->{label} .= $label;
-
- # Escape special chars from content
- $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
-
- $xrefs .= "- :ref:`$content <$label>`\n\n";
- }
+ push @{$data{$nametag}->{xrefs}}, [($content, $label)] if ($data{$nametag}->{what});
next;
}
@@ -117,6 +108,9 @@ sub parse_abi {
$tag = $new_tag;
if ($new_what) {
+ @{$data{$what}->{label}} = @labels if ($data{$nametag}->{what});
+ @labels = ();
+ $label = "";
$new_what = 0;
$data{$what}->{type} = $type;
@@ -145,15 +139,8 @@ sub parse_abi {
}
# Store any contents before tags at the database
- if (!$tag) {
- next if (/^\n/);
-
- my $my_what = "File $name";
- $data{$my_what}->{what} = "File $name";
- $data{$my_what}->{type} = "File";
- $data{$my_what}->{file} = $name;
- $data{$my_what}->{description} .= $_;
- $has_file = 1;
+ if (!$tag && $data{$nametag}->{what}) {
+ $data{$nametag}->{description} .= $_;
next;
}
@@ -192,12 +179,8 @@ sub parse_abi {
# Everything else is error
parse_error($file, $ln, "Unexpected line:", $_);
}
+ $data{$nametag}->{description} =~ s/^\n+//;
close IN;
-
- if ($has_file) {
- my $my_what = "File $name";
- $data{$my_what}->{xrefs} = $xrefs;
- }
}
# Outputs the output on ReST format
@@ -212,11 +195,22 @@ sub output_rest {
my $bar = $w;
$bar =~ s/./-/g;
- if ($data{$what}->{label}) {
- my @labels = split(/\s/, $data{$what}->{label});
- foreach my $label (@labels) {
- printf ".. _%s:\n\n", $label;
- }
+ foreach my $p (@{$data{$what}->{label}}) {
+ my ($content, $label) = @{$p};
+ $label = "abi_" . $label . " ";
+ $label =~ tr/A-Z/a-z/;
+
+ # Convert special chars to "_"
+ $label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g;
+ $label =~ s,_+,_,g;
+ $label =~ s,_$,,;
+
+ $data{$what}->{label} .= $label;
+
+ printf ".. _%s:\n\n", $label;
+
+ # only one label is enough
+ last;
}
print "$w\n$bar\n\n";
@@ -243,10 +237,28 @@ sub output_rest {
print "$desc\n\n";
}
} else {
- print "DESCRIPTION MISSING for $what\n\n";
+ print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file});
}
- printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs});
+ if ($data{$what}->{xrefs}) {
+ printf "Has the following ABI:\n\n";
+
+ foreach my $p(@{$data{$what}->{xrefs}}) {
+ my ($content, $label) = @{$p};
+ $label = "abi_" . $label . " ";
+ $label =~ tr/A-Z/a-z/;
+
+ # Convert special chars to "_"
+ $label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g;
+ $label =~ s,_+,_,g;
+ $label =~ s,_$,,;
+
+ # Escape special chars from content
+ $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
+
+ print "- :ref:`$content <$label>`\n\n";
+ }
+ }
}
}
--
2.21.0
^ permalink raw reply related
* [PATCH 14/14] docs: sphinx/kernel_abi.py: fix UTF-8 support
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
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 | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 7fa7806532dc..460cee48a245 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
+#
u"""
kernel-abi
~~~~~~~~~~
@@ -28,6 +29,7 @@ u"""
"""
+import codecs
import sys
import os
from os import path
@@ -124,12 +126,12 @@ class KernelCmd(Directive):
cmd
, stdout = subprocess.PIPE
, stderr = subprocess.PIPE
- , universal_newlines = True
, **kwargs
)
out, err = proc.communicate()
- if err:
- self.warn(err)
+
+ out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
+
if proc.returncode != 0:
raise self.severe(
u"command '%s' failed with return code %d"
--
2.21.0
^ permalink raw reply related
* [PATCH 00/14] Add support to generate ABI documentation at admin-guide
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, linuxppc-dev, Andrew Donnellan, Jonathan Cameron,
Lars-Peter Clausen, Anton Vorontsov, linux-pm, Colin Cross,
linux-iio, Hartmut Knaack, Sebastian Reichel, Frederic Barrat,
Andreas Klinger, Tony Luck, Peter Meerwald-Stadler, Stefan Achatz,
Kees Cook
Greg,
As promised, I'm resending the patch series with adds the Kernel ABI to
Documentation/admin-guide.
Those patches are basically the version 3 patchset I sent back in 2017,
rebased on the top of linux-next (next-20190613), and with some fixes
in order for it to work.
- The 4 initial patches to fix some ABI descriptions that are violating
the syntax described at Documentation/ABI/README;
- The next 6 patches are the ones originally written in 2017 with a
script with parses the ABI files;
- The 11th patch is a new one: it relaxes a little bit the parser in
order to parse file headers that contains colons on it;
- The 12th patch adds the new script to the documentation build
system, together with a new python Sphinx extension with calls it;
- The 13th patch fixes the python script when running with newer
Sphinx versions (1.7 and upper);
- The final patch fixes an UTF-8 trouble. I noticed it only with Sphinx
1.4, but it could affect other versions too. So, I ended by changing
the UTF-8 encoding logit to work version-independent, just like
what happens with kerneldoc.py extension.
Mauro Carvalho Chehab (14):
ABI: fix some syntax issues at the ABI database
ABI: sysfs-driver-hid: the "What" field doesn't parse fine
ABI: sysfs-class-uwb_rc: remove a duplicated incomplete entry
ABI: better identificate tables
scripts: add an script to parse the ABI files
scripts/get_abi.pl: parse files with text at beginning
scripts/get_abi.pl: avoid use literal blocks when not needed
scripts/get_abi.pl: split label naming from xref logic
scripts/get_abi.pl: add support for searching for ABI symbols
scripts/get_abi.pl: represent what in tables
scripts/get_abi.pl: fix parse issues with some files
doc-rst: add ABI documentation to the admin-guide book
sphinx/kernel_abi.py: make it compatible with Sphinx 1.7+
docs: sphinx/kernel_abi.py: fix UTF-8 support
.../ABI/obsolete/sysfs-driver-hid-roccat-pyra | 2 +-
Documentation/ABI/testing/pstore | 2 +-
.../sysfs-bus-event_source-devices-format | 2 +-
.../ABI/testing/sysfs-bus-i2c-devices-hm6352 | 6 +-
.../ABI/testing/sysfs-bus-iio-distance-srf08 | 4 +-
.../testing/sysfs-bus-iio-proximity-as3935 | 4 +-
.../ABI/testing/sysfs-bus-pci-devices-cciss | 22 +-
.../testing/sysfs-bus-usb-devices-usbsevseg | 12 +-
.../sysfs-class-backlight-driver-lm3533 | 6 +-
Documentation/ABI/testing/sysfs-class-cxl | 6 +-
Documentation/ABI/testing/sysfs-class-devfreq | 2 +-
.../ABI/testing/sysfs-class-led-driver-lm3533 | 8 +-
.../ABI/testing/sysfs-class-leds-gt683r | 4 +-
.../ABI/testing/sysfs-class-powercap | 2 +-
Documentation/ABI/testing/sysfs-class-uwb_rc | 6 -
Documentation/ABI/testing/sysfs-driver-hid | 12 +-
.../ABI/testing/sysfs-driver-hid-roccat-kone | 2 +-
Documentation/ABI/testing/sysfs-kernel-fscaps | 2 +-
.../ABI/testing/sysfs-kernel-vmcoreinfo | 2 +-
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 | 1 +
Documentation/conf.py | 2 +-
Documentation/sphinx/kernel_abi.py | 172 +++++++
scripts/get_abi.pl | 450 ++++++++++++++++++
28 files changed, 731 insertions(+), 57 deletions(-)
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
create mode 100644 Documentation/sphinx/kernel_abi.py
create mode 100755 scripts/get_abi.pl
--
2.21.0
^ permalink raw reply
* [PATCH 01/14] ABI: fix some syntax issues at the ABI database
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Andreas Klinger, Jonathan Cameron,
Hartmut Knaack, Lars-Peter Clausen, Peter Meerwald-Stadler,
Frederic Barrat, Andrew Donnellan, Sebastian Reichel, Kees Cook,
Anton Vorontsov, Colin Cross, Tony Luck, linux-iio, linuxppc-dev,
linux-pm, Mauro Carvalho Chehab
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
On those three files, the ABI representation described at
README are violated.
- at sysfs-bus-iio-proximity-as3935:
a ':' character is missing after "What"
- at sysfs-class-devfreq:
there's a typo at Description
- at sysfs-class-cxl, it is using the ":" character at a
file preamble, causing it to be misinterpreted as a
tag.
- On the other files, instead of "What", they use "Where".
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/testing/pstore | 2 +-
.../sysfs-bus-event_source-devices-format | 2 +-
.../ABI/testing/sysfs-bus-i2c-devices-hm6352 | 6 ++---
.../ABI/testing/sysfs-bus-iio-distance-srf08 | 4 ++--
.../testing/sysfs-bus-iio-proximity-as3935 | 4 ++--
.../ABI/testing/sysfs-bus-pci-devices-cciss | 22 +++++++++----------
.../testing/sysfs-bus-usb-devices-usbsevseg | 12 +++++-----
Documentation/ABI/testing/sysfs-class-cxl | 6 ++---
Documentation/ABI/testing/sysfs-class-devfreq | 2 +-
.../ABI/testing/sysfs-class-powercap | 2 +-
Documentation/ABI/testing/sysfs-kernel-fscaps | 2 +-
.../ABI/testing/sysfs-kernel-vmcoreinfo | 2 +-
12 files changed, 33 insertions(+), 33 deletions(-)
diff --git a/Documentation/ABI/testing/pstore b/Documentation/ABI/testing/pstore
index 5fca9f5e10a3..8d6e48f4e8ef 100644
--- a/Documentation/ABI/testing/pstore
+++ b/Documentation/ABI/testing/pstore
@@ -1,4 +1,4 @@
-Where: /sys/fs/pstore/... (or /dev/pstore/...)
+What: /sys/fs/pstore/... (or /dev/pstore/...)
Date: March 2011
Kernel Version: 2.6.39
Contact: tony.luck@intel.com
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
index 77f47ff5ee02..b6f8748e0200 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
@@ -1,4 +1,4 @@
-Where: /sys/bus/event_source/devices/<dev>/format
+What: /sys/bus/event_source/devices/<dev>/format
Date: January 2012
Kernel Version: 3.3
Contact: Jiri Olsa <jolsa@redhat.com>
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
index feb2e4a87075..29bd447e50a0 100644
--- a/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
@@ -1,18 +1,18 @@
-Where: /sys/bus/i2c/devices/.../heading0_input
+What: /sys/bus/i2c/devices/.../heading0_input
Date: April 2010
Kernel Version: 2.6.36?
Contact: alan.cox@intel.com
Description: Reports the current heading from the compass as a floating
point value in degrees.
-Where: /sys/bus/i2c/devices/.../power_state
+What: /sys/bus/i2c/devices/.../power_state
Date: April 2010
Kernel Version: 2.6.36?
Contact: alan.cox@intel.com
Description: Sets the power state of the device. 0 sets the device into
sleep mode, 1 wakes it up.
-Where: /sys/bus/i2c/devices/.../calibration
+What: /sys/bus/i2c/devices/.../calibration
Date: April 2010
Kernel Version: 2.6.36?
Contact: alan.cox@intel.com
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
index 0a1ca1487fa9..a133fd8d081a 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
+++ b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
@@ -1,4 +1,4 @@
-What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
+What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
Date: January 2017
KernelVersion: 4.11
Contact: linux-iio@vger.kernel.org
@@ -6,7 +6,7 @@ Description:
Show or set the gain boost of the amp, from 0-31 range.
default 31
-What /sys/bus/iio/devices/iio:deviceX/sensor_max_range
+What: /sys/bus/iio/devices/iio:deviceX/sensor_max_range
Date: January 2017
KernelVersion: 4.11
Contact: linux-iio@vger.kernel.org
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
index 9a17ab5036a4..c59d95346341 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
+++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
@@ -1,4 +1,4 @@
-What /sys/bus/iio/devices/iio:deviceX/in_proximity_input
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity_input
Date: March 2014
KernelVersion: 3.15
Contact: Matt Ranostay <matt.ranostay@konsulko.com>
@@ -6,7 +6,7 @@ Description:
Get the current distance in meters of storm (1km steps)
1000-40000 = distance in meters
-What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
+What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
Date: March 2014
KernelVersion: 3.15
Contact: Matt Ranostay <matt.ranostay@konsulko.com>
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
index 53d99edd1d75..eb449169c30b 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
+++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
@@ -1,66 +1,66 @@
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
Date: March 2009
Kernel Version: 2.6.30
Contact: iss_storagedev@hp.com
Description: Displays the SCSI INQUIRY page 0 model for logical drive
Y of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
Date: March 2009
Kernel Version: 2.6.30
Contact: iss_storagedev@hp.com
Description: Displays the SCSI INQUIRY page 0 revision for logical
drive Y of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
Date: March 2009
Kernel Version: 2.6.30
Contact: iss_storagedev@hp.com
Description: Displays the SCSI INQUIRY page 83 serial number for logical
drive Y of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
Date: March 2009
Kernel Version: 2.6.30
Contact: iss_storagedev@hp.com
Description: Displays the SCSI INQUIRY page 0 vendor for logical drive
Y of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
Date: March 2009
Kernel Version: 2.6.30
Contact: iss_storagedev@hp.com
Description: A symbolic link to /sys/block/cciss!cXdY
-Where: /sys/bus/pci/devices/<dev>/ccissX/rescan
+What: /sys/bus/pci/devices/<dev>/ccissX/rescan
Date: August 2009
Kernel Version: 2.6.31
Contact: iss_storagedev@hp.com
Description: Kicks of a rescan of the controller to discover logical
drive topology changes.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
Date: August 2009
Kernel Version: 2.6.31
Contact: iss_storagedev@hp.com
Description: Displays the 8-byte LUN ID used to address logical
drive Y of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
Date: August 2009
Kernel Version: 2.6.31
Contact: iss_storagedev@hp.com
Description: Displays the RAID level of logical drive Y of
controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
Date: August 2009
Kernel Version: 2.6.31
Contact: iss_storagedev@hp.com
Description: Displays the usage count (number of opens) of logical drive Y
of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/resettable
+What: /sys/bus/pci/devices/<dev>/ccissX/resettable
Date: February 2011
Kernel Version: 2.6.38
Contact: iss_storagedev@hp.com
@@ -71,7 +71,7 @@ Description: Value of 1 indicates the controller can honor the reset_devices
a dump device, as kdump requires resetting the device in order
to work reliably.
-Where: /sys/bus/pci/devices/<dev>/ccissX/transport_mode
+What: /sys/bus/pci/devices/<dev>/ccissX/transport_mode
Date: July 2011
Kernel Version: 3.0
Contact: iss_storagedev@hp.com
diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
index 70d00dfa443d..f6199b314196 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
+++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
@@ -1,12 +1,12 @@
-Where: /sys/bus/usb/.../powered
+What: /sys/bus/usb/.../powered
Date: August 2008
Kernel Version: 2.6.26
Contact: Harrison Metzger <harrisonmetz@gmail.com>
Description: Controls whether the device's display will powered.
A value of 0 is off and a non-zero value is on.
-Where: /sys/bus/usb/.../mode_msb
-Where: /sys/bus/usb/.../mode_lsb
+What: /sys/bus/usb/.../mode_msb
+What: /sys/bus/usb/.../mode_lsb
Date: August 2008
Kernel Version: 2.6.26
Contact: Harrison Metzger <harrisonmetz@gmail.com>
@@ -16,7 +16,7 @@ Description: Controls the devices display mode.
for an 8 character display the values are
MSB 0x08; LSB 0xFF.
-Where: /sys/bus/usb/.../textmode
+What: /sys/bus/usb/.../textmode
Date: August 2008
Kernel Version: 2.6.26
Contact: Harrison Metzger <harrisonmetz@gmail.com>
@@ -25,13 +25,13 @@ Description: Controls the way the device interprets its text buffer.
hex: each character is between 0-15
ascii: each character is between '0'-'9' and 'A'-'F'.
-Where: /sys/bus/usb/.../text
+What: /sys/bus/usb/.../text
Date: August 2008
Kernel Version: 2.6.26
Contact: Harrison Metzger <harrisonmetz@gmail.com>
Description: The text (or data) for the device to display
-Where: /sys/bus/usb/.../decimals
+What: /sys/bus/usb/.../decimals
Date: August 2008
Kernel Version: 2.6.26
Contact: Harrison Metzger <harrisonmetz@gmail.com>
diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl
index bbbabffc682a..fc7c6f7c21b3 100644
--- a/Documentation/ABI/testing/sysfs-class-cxl
+++ b/Documentation/ABI/testing/sysfs-class-cxl
@@ -1,6 +1,6 @@
-Note: Attributes that are shared between devices are stored in the directory
-pointed to by the symlink device/.
-Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
+Please notice that attributes that are shared between devices are stored in
+the directory pointed to by the symlink device/.
+For example, the real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
/sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max.
diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq
index ee39acacf6f8..01196e19afca 100644
--- a/Documentation/ABI/testing/sysfs-class-devfreq
+++ b/Documentation/ABI/testing/sysfs-class-devfreq
@@ -47,7 +47,7 @@ Description:
What: /sys/class/devfreq/.../trans_stat
Date: October 2012
Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
-Descrtiption:
+Description:
This ABI shows the statistics of devfreq behavior on a
specific device. It shows the time spent in each state and
the number of transitions between states.
diff --git a/Documentation/ABI/testing/sysfs-class-powercap b/Documentation/ABI/testing/sysfs-class-powercap
index db3b3ff70d84..f333a0ccc29b 100644
--- a/Documentation/ABI/testing/sysfs-class-powercap
+++ b/Documentation/ABI/testing/sysfs-class-powercap
@@ -147,6 +147,6 @@ What: /sys/class/powercap/.../<power zone>/enabled
Date: September 2013
KernelVersion: 3.13
Contact: linux-pm@vger.kernel.org
-Description
+Description:
This allows to enable/disable power capping at power zone level.
This applies to current power zone and its children.
diff --git a/Documentation/ABI/testing/sysfs-kernel-fscaps b/Documentation/ABI/testing/sysfs-kernel-fscaps
index 50a3033b5e15..bcff34665192 100644
--- a/Documentation/ABI/testing/sysfs-kernel-fscaps
+++ b/Documentation/ABI/testing/sysfs-kernel-fscaps
@@ -2,7 +2,7 @@ What: /sys/kernel/fscaps
Date: February 2011
KernelVersion: 2.6.38
Contact: Ludwig Nussel <ludwig.nussel@suse.de>
-Description
+Description:
Shows whether file system capabilities are honored
when executing a binary
diff --git a/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo b/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
index 7bd81168e063..1f1087a5f075 100644
--- a/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
+++ b/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
@@ -4,7 +4,7 @@ KernelVersion: 2.6.24
Contact: Ken'ichi Ohmichi <oomichi@mxs.nes.nec.co.jp>
Kexec Mailing List <kexec@lists.infradead.org>
Vivek Goyal <vgoyal@redhat.com>
-Description
+Description:
Shows physical address and size of vmcoreinfo ELF note.
First value contains physical address of note in hex and
second value contains the size of note in hex. This ELF
--
2.21.0
^ permalink raw reply related
* [PATCH 04/14] ABI: better identificate tables
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Stefan Achatz, Mauro Carvalho Chehab
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
When parsing via script, it is important to know if the script
should consider a description as a literal block that should
be displayed as-is, or if the description can be considered
as a normal text.
Change descriptions to ensure that the preceding line of a table
ends with a colon. That makes easy to identify the need of a
literal block.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra | 2 +-
.../ABI/testing/sysfs-class-backlight-driver-lm3533 | 6 +++---
Documentation/ABI/testing/sysfs-class-led-driver-lm3533 | 8 ++++----
Documentation/ABI/testing/sysfs-class-leds-gt683r | 4 ++--
Documentation/ABI/testing/sysfs-driver-hid-roccat-kone | 2 +-
5 files changed, 11 insertions(+), 11 deletions(-)
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
index 16020b31ae64..5d41ebadf15e 100644
--- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
@@ -5,7 +5,7 @@ Description: It is possible to switch the cpi setting of the mouse with the
press of a button.
When read, this file returns the raw number of the actual cpi
setting reported by the mouse. This number has to be further
- processed to receive the real dpi value.
+ processed to receive the real dpi value:
VALUE DPI
1 400
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
index 77cf7ac949af..c0e0a9ae7b3d 100644
--- a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
+++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
@@ -4,7 +4,7 @@ KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
Get the ALS output channel used as input in
- ALS-current-control mode (0, 1), where
+ ALS-current-control mode (0, 1), where:
0 - out_current0 (backlight 0)
1 - out_current1 (backlight 1)
@@ -28,7 +28,7 @@ Date: April 2012
KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
- Set the brightness-mapping mode (0, 1), where
+ Set the brightness-mapping mode (0, 1), where:
0 - exponential mode
1 - linear mode
@@ -38,7 +38,7 @@ Date: April 2012
KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
- Set the PWM-input control mask (5 bits), where
+ Set the PWM-input control mask (5 bits), where:
bit 5 - PWM-input enabled in Zone 4
bit 4 - PWM-input enabled in Zone 3
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
index 620ebb3b9baa..e4c89b261546 100644
--- a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
@@ -4,7 +4,7 @@ KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
Set the ALS output channel to use as input in
- ALS-current-control mode (1, 2), where
+ ALS-current-control mode (1, 2), where:
1 - out_current1
2 - out_current2
@@ -22,7 +22,7 @@ Date: April 2012
KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
- Set the pattern generator fall and rise times (0..7), where
+ Set the pattern generator fall and rise times (0..7), where:
0 - 2048 us
1 - 262 ms
@@ -45,7 +45,7 @@ Date: April 2012
KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
- Set the brightness-mapping mode (0, 1), where
+ Set the brightness-mapping mode (0, 1), where:
0 - exponential mode
1 - linear mode
@@ -55,7 +55,7 @@ Date: April 2012
KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
- Set the PWM-input control mask (5 bits), where
+ Set the PWM-input control mask (5 bits), where:
bit 5 - PWM-input enabled in Zone 4
bit 4 - PWM-input enabled in Zone 3
diff --git a/Documentation/ABI/testing/sysfs-class-leds-gt683r b/Documentation/ABI/testing/sysfs-class-leds-gt683r
index e4fae6026e79..6adab27f646e 100644
--- a/Documentation/ABI/testing/sysfs-class-leds-gt683r
+++ b/Documentation/ABI/testing/sysfs-class-leds-gt683r
@@ -5,7 +5,7 @@ Contact: Janne Kanniainen <janne.kanniainen@gmail.com>
Description:
Set the mode of LEDs. You should notice that changing the mode
of one LED will update the mode of its two sibling devices as
- well.
+ well. Possible values are:
0 - normal
1 - audio
@@ -13,4 +13,4 @@ Description:
Normal: LEDs are fully on when enabled
Audio: LEDs brightness depends on sound level
- Breathing: LEDs brightness varies at human breathing rate
\ No newline at end of file
+ Breathing: LEDs brightness varies at human breathing rate
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone
index 3ca3971109bf..8f7982c70d72 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone
+++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone
@@ -5,7 +5,7 @@ Description: It is possible to switch the dpi setting of the mouse with the
press of a button.
When read, this file returns the raw number of the actual dpi
setting reported by the mouse. This number has to be further
- processed to receive the real dpi value.
+ processed to receive the real dpi value:
VALUE DPI
1 800
--
2.21.0
^ permalink raw reply related
* [PATCH 13/14] sphinx/kernel_abi.py: make it compatible with Sphinx 1.7+
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
The same way kerneldoc.py needed changes to work with newer
Sphinx, this script needs the same changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernel_abi.py | 31 ++++++++++++++++++++++--------
1 file changed, 23 insertions(+), 8 deletions(-)
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 32ce90775d96..7fa7806532dc 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -33,7 +33,16 @@ import os
from os import path
import subprocess
-from sphinx.ext.autodoc import AutodocReporter
+#
+# AutodocReporter is only good up to Sphinx 1.7
+#
+import sphinx
+
+Use_SSI = sphinx.__version__[:3] >= '1.7'
+if Use_SSI:
+ from sphinx.util.docutils import switch_source_input
+else:
+ from sphinx.ext.autodoc import AutodocReporter
from docutils import nodes
from docutils.parsers.rst import Directive, directives
@@ -145,11 +154,17 @@ class KernelCmd(Directive):
content.append(l, fname, c)
buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
- self.state.memo.title_styles = []
- self.state.memo.section_level = 0
- self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
- try:
- self.state.nested_parse(content, 0, node, match_titles=1)
- finally:
- self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+
+ if Use_SSI:
+ with switch_source_input(self.state, content):
+ self.state.nested_parse(content, 0, node, match_titles=1)
+ else:
+ self.state.memo.title_styles = []
+ self.state.memo.section_level = 0
+ self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
+ try:
+ self.state.nested_parse(content, 0, node, match_titles=1)
+ finally:
+ self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+
return node.children
--
2.21.0
^ permalink raw reply related
* [PATCH 03/14] ABI: sysfs-class-uwb_rc: remove a duplicated incomplete entry
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mauro Carvalho Chehab
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
There are two entries for /sys/class/uwb_rc/uwbN/<EUI-48>/BPST.
The second one has a missing description.
Get rid of it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/testing/sysfs-class-uwb_rc | 6 ------
1 file changed, 6 deletions(-)
diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc b/Documentation/ABI/testing/sysfs-class-uwb_rc
index 85f4875d16ac..a0578751c1e3 100644
--- a/Documentation/ABI/testing/sysfs-class-uwb_rc
+++ b/Documentation/ABI/testing/sysfs-class-uwb_rc
@@ -125,12 +125,6 @@ Description:
The EUI-48 of this device in colon separated hex
octets.
-What: /sys/class/uwb_rc/uwbN/<EUI-48>/BPST
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
-
What: /sys/class/uwb_rc/uwbN/<EUI-48>/IEs
Date: July 2008
KernelVersion: 2.6.27
--
2.21.0
^ permalink raw reply related
* [PATCH 06/14] scripts/get_abi.pl: parse files with text at beginning
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mauro Carvalho Chehab
In-Reply-To: <cover.1560477540.git.mchehab+samsung@kernel.org>
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
It sounds usefult o parse files with has some text at the
beginning. Add support for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 59 ++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 54 insertions(+), 5 deletions(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index f7c9944a833c..ac0f057fa3ca 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -55,7 +55,10 @@ sub parse_abi {
my $what;
my $new_what;
my $tag;
+ my $label;
my $ln;
+ my $has_file;
+ my $xrefs;
print STDERR "Opening $file\n" if ($debug > 1);
open IN, $file;
@@ -67,7 +70,7 @@ sub parse_abi {
if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) {
if ($tag eq "description") {
- $data{$what}->{$tag} .= "\n$content";;
+ $data{$what}->{$tag} .= "\n$content";
$data{$what}->{$tag} =~ s/\n+$//;
next;
} else {
@@ -83,6 +86,25 @@ sub parse_abi {
$new_what = 1;
}
$tag = $new_tag;
+
+ if ($has_file) {
+ $label = "abi_" . $content . " ";
+ $label =~ tr/A-Z/a-z/;
+
+ # Convert special chars to "_"
+ $label =~s/[\x00-\x2f]+/_/g;
+ $label =~s/[\x3a-\x40]+/_/g;
+ $label =~s/[\x7b-\xff]+/_/g;
+ $label =~ s,_+,_,g;
+ $label =~ s,_$,,;
+
+ $data{$what}->{label} .= $label;
+
+ # Escape special chars from content
+ $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
+
+ $xrefs .= "- :ref:`$content <$label>`\n\n";
+ }
next;
}
@@ -104,8 +126,18 @@ sub parse_abi {
next;
}
- # Silently ignore any headers before the database
- next if (!$tag);
+ # Store any contents before the database
+ if (!$tag) {
+ next if (/^\n/);
+
+ my $my_what = "File $name";
+ $data{$my_what}->{what} = "File $name";
+ $data{$my_what}->{type} = "File";
+ $data{$my_what}->{file} = $name;
+ $data{$my_what}->{description} .= $_;
+ $has_file = 1;
+ next;
+ }
if (m/^\s*(.*)/) {
$data{$what}->{$tag} .= "\n$1";
@@ -117,6 +149,11 @@ sub parse_abi {
parse_error($file, $ln, "Unexpected line:", $_);
}
close IN;
+
+ if ($has_file) {
+ my $my_what = "File $name";
+ $data{$my_what}->{xrefs} = $xrefs;
+ }
}
# Outputs the output on ReST format
@@ -128,8 +165,17 @@ sub output_rest {
my $w = $what;
$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
+ if ($data{$what}->{label}) {
+ my @labels = split(/\s/, $data{$what}->{label});
+ foreach my $label (@labels) {
+ printf ".. _%s:\n\n", $label;
+ }
+ }
+
print "$w\n\n";
- print "- defined on file $file (type: $type)\n\n::\n\n";
+
+ print "- defined on file $file (type: $type)\n\n" if ($type ne "File");
+ print "::\n\n";
my $desc = $data{$what}->{description};
$desc =~ s/^\s+//;
@@ -144,8 +190,11 @@ sub output_rest {
if (!($desc =~ /^\s*$/)) {
print " $desc\n\n";
} else {
- print " DESCRIPTION MISSING\n\n";
+ print " DESCRIPTION MISSING for $what\n\n";
}
+
+ printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs});
+
}
}
--
2.21.0
^ permalink raw reply related
* Re: [RFC 0/7] Introduce TEE based Trusted Keys support
From: Mimi Zohar @ 2019-06-14 0:03 UTC (permalink / raw)
To: Casey Schaufler, Sumit Garg, keyrings, linux-integrity,
linux-security-module
Cc: jens.wiklander, corbet, dhowells, jejb, jarkko.sakkinen, jmorris,
serge, ard.biesheuvel, daniel.thompson, linux-doc, linux-kernel,
tee-dev
In-Reply-To: <d803283e-5e69-5deb-fe94-3f2e45fb95af@schaufler-ca.com>
On Thu, 2019-06-13 at 09:40 -0700, Casey Schaufler wrote:
> On 6/13/2019 3:30 AM, Sumit Garg wrote:
> > Add support for TEE based trusted keys where TEE provides the functionality
> > to seal and unseal trusted keys using hardware unique key. Also, this is
> > an alternative in case platform doesn't possess a TPM device.
> >
> > This series also adds some TEE features like:
>
> Please expand the acronym TEE on first use. That will
> help people who don't work with it on a daily basis
> understand what you're going on about.
Thanks, Casey.
"[6/7] doc: keys: Document usage of TEE based Trusted Keys" refers to
the kernel tee documentation, but that documentation is limited to
userspace interaction with the tee.
A trusted key is a random number generated and sealed(encrypted) by
the TPM, so that only the TPM may unseal it. The sealing key never
leaves the TPM. The sealed, trusted key may be exported to userspace.
In the tee case, can the "sealing" key ever leave the tee? Can the
sealed, trusted key, exported to userspace, be unsealed by the tee?
Are the tee security protections similar to those of the TPM? How do
they compare?
Mimi
>
> >
> > Patch #1, #2 enables support for registered kernel shared memory with TEE.
> >
> > Patch #3 enables support for private kernel login method required for
> > cases like trusted keys where we don't wan't user-space to directly access
> > TEE service to retrieve trusted key contents.
> >
> > Rest of the patches from #4 to #7 adds support for TEE based trusted keys.
> >
> > This patch-set has been tested with OP-TEE based pseudo TA which can be
> > found here [1].
> >
> > Looking forward to your valuable feedback/suggestions.
^ permalink raw reply
* Re: [PATCH v2 2/5] dt-bindings: perf: stm32: ddrperfm support
From: Rob Herring @ 2019-06-13 23:04 UTC (permalink / raw)
To: Gerald BAEZA
Cc: will.deacon@arm.com, mark.rutland@arm.com, robh+dt@kernel.org,
mcoquelin.stm32@gmail.com, Alexandre TORGUE, corbet@lwn.net,
linux@armlinux.org.uk, olof@lixom.net, horms+renesas@verge.net.au,
arnd@arndb.de, linux-arm-kernel@lists.infradead.org,
devicetree@vger.kernel.org,
linux-stm32@st-md-mailman.stormreply.com,
linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org,
Gerald BAEZA
In-Reply-To: <1558366019-24214-3-git-send-email-gerald.baeza@st.com>
On Mon, 20 May 2019 15:27:16 +0000, Gerald BAEZA wrote:
> The DDRPERFM is the DDR Performance Monitor embedded in STM32MP1 SOC.
>
> This documentation indicates how to enable stm32-ddr-pmu driver on
> DDRPERFM peripheral, via the device tree.
>
> Signed-off-by: Gerald Baeza <gerald.baeza@st.com>
> ---
> .../devicetree/bindings/perf/stm32-ddr-pmu.txt | 20 ++++++++++++++++++++
> 1 file changed, 20 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/perf/stm32-ddr-pmu.txt
>
Reviewed-by: Rob Herring <robh@kernel.org>
^ permalink raw reply
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