* Re: [PATCH v3] Add a document on rebasing and merging
From: Dmitry Vyukov @ 2019-06-14 9:59 UTC (permalink / raw)
To: Jonathan Corbet
Cc: open list:DOCUMENTATION, LKML, Theodore Ts'o,
Geert Uytterhoeven, David Rientjes, Jani Nikula, Michael Ellerman
In-Reply-To: <20190612094503.120f699a@lwn.net>
On Wed, Jun 12, 2019 at 5:45 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Every merge window seems to involve at least one episode where subsystem
> maintainers don't manage their trees as Linus would like. Document the
> expectations so that at least he has something to point people to.
>
> Acked-by: David Rientjes <rientjes@google.com>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> I intend to apply this version unless somebody really screams.
>
> Changes in v3
> - Fill out discussion on back merges and topic branches as suggested by
> Jani.
>
> Changes in v2:
> - Try to clear up "reparenting" v. "history modification"
> - Make the "don't rebase public branches" rule into more of a guideline
> - Fix typos noted by Geert
> - Rename the document to better reflect its contents
>
> Documentation/maintainer/index.rst | 1 +
> .../maintainer/rebasing-and-merging.rst | 226 ++++++++++++++++++
> 2 files changed, 227 insertions(+)
> create mode 100644 Documentation/maintainer/rebasing-and-merging.rst
>
> diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst
> index 2a14916930cb..56e2c09dfa39 100644
> --- a/Documentation/maintainer/index.rst
> +++ b/Documentation/maintainer/index.rst
> @@ -10,5 +10,6 @@ additions to this manual.
> :maxdepth: 2
>
> configure-git
> + rebasing-and-merging
> pull-requests
>
> diff --git a/Documentation/maintainer/rebasing-and-merging.rst b/Documentation/maintainer/rebasing-and-merging.rst
> new file mode 100644
> index 000000000000..5da9da7a2c51
> --- /dev/null
> +++ b/Documentation/maintainer/rebasing-and-merging.rst
> @@ -0,0 +1,226 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +====================
> +Rebasing and merging
> +====================
> +
> +Maintaining a subsystem, as a general rule, requires a familiarity with the
> +Git source-code management system. Git is a powerful tool with a lot of
> +features; as is often the case with such tools, there are right and wrong
> +ways to use those features. This document looks in particular at the use
> +of rebasing and merging. Maintainers often get in trouble when they use
> +those tools incorrectly, but avoiding problems is not actually all that
> +hard.
> +
> +One thing to be aware of in general is that, unlike many other projects,
> +the kernel community is not scared by seeing merge commits in its
> +development history. Indeed, given the scale of the project, avoiding
> +merges would be nearly impossible.
Hi Jonathan,
I will appreciate if you elaborate a bit on this "scale of the
project". I wondered about reasons for having the current hierarchy of
trees and complex merging for a while, but wasn't able to find any
rationale. What exactly scale do you mean? I know a number of projects
that are comparable to Linux kernel, with the largest being 2 orders
of magnitude larger than kernel both in terms of code size and rate of
change, that use single tree and linear history. So these scales do
not seem to inherently require multiple trees and non-linear history.
Maybe this is already documented somewhere?
Thanks
^ permalink raw reply
* Re: [PATCH v10 3/3] watchdog: make the device time out at open_deadline when open_timeout is used
From: Rasmus Villemoes @ 2019-06-14 8:41 UTC (permalink / raw)
To: Guenter Roeck
Cc: linux-watchdog@vger.kernel.org, Wim Van Sebroeck, Jonathan Corbet,
linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org,
Esben Haabendal, Jerry Hoemann, Rasmus Villemoes
In-Reply-To: <20190607183827.GA32475@roeck-us.net>
On 07/06/2019 20.38, Guenter Roeck wrote:
> On Wed, Jun 05, 2019 at 02:06:44PM +0000, Rasmus Villemoes wrote:
>> When the watchdog device is not open by userspace, the kernel takes
>> care of pinging it. When the open_timeout feature is in use, we should
>> ensure that the hardware fires close to open_timeout seconds after the
>> kernel has assumed responsibility for the device.
>>
>> To do this, simply reuse the logic that is already in place for
>> ensuring the same thing when userspace is responsible for regularly
>> pinging the device:
>>
>> - When watchdog_active(wdd), this patch doesn't change anything.
>>
>> - When !watchdoc_active(wdd), the "virtual timeout" should be taken to
>
> s/watchdoc_active/watchdog_active/
>
> otherwise
>
> Reviewed-by: Guenter Roeck <linux@roeck-us.net>
Thanks! Wim, can you fix up if/when applying, or do you prefer I resend?
Rasmus
^ permalink raw reply
* Re: [PATCH 01/14] ABI: fix some syntax issues at the ABI database
From: Rafael J. Wysocki @ 2019-06-14 8:30 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Greg Kroah-Hartman, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, Linux Kernel Mailing List, 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
In-Reply-To: <b908fc6555df8cae3e4c734b2d5f6284c46a5f14.1560477540.git.mchehab+samsung@kernel.org>
On Fri, Jun 14, 2019 at 4:04 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> 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>
Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
> ---
> 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
* Re: [RFC 0/7] Introduce TEE based Trusted Keys support
From: Sumit Garg @ 2019-06-14 8:17 UTC (permalink / raw)
To: Mimi Zohar
Cc: Casey Schaufler, keyrings, linux-integrity, linux-security-module,
Jens Wiklander, corbet, dhowells, jejb, Jarkko Sakkinen, jmorris,
serge, Ard Biesheuvel, Daniel Thompson, linux-doc,
Linux Kernel Mailing List, tee-dev
In-Reply-To: <1560470593.4805.109.camel@linux.ibm.com>
Thanks Mimi for your comments.
On Fri, 14 Jun 2019 at 05:33, Mimi Zohar <zohar@linux.ibm.com> wrote:
>
> 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.
>
Thanks for pointing this out. I will update documentation to include
TEE bus approach and communication apis for kernel clients.
BTW, the interface is similar as with user-space. Only difference is
instead of IOCTL's from user-space, there are wrapper apis to
communicate with TEE.
Also, in case someone is interested to learn about TEE technology,
this webinar [1] could be one of starting points.
> 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.
Understood.
> In the tee case, can the "sealing" key ever leave the tee?
No, the "sealing" key never leaves TEE. Its basically a Hardware
Unique Key (HUK) tied to a particular SoC.
> Can the
> sealed, trusted key, exported to userspace, be unsealed by the tee?
You mean using user-space interface to TEE? If yes, then answer is
"no" as user-space can't communicate with this TEE service as its
accessible to kernel clients only (see patch [2]).
In case you meant loading exported trusted key blob via "keyctl", then
"yes" this driver can unseal the trusted key. Have a look at examples
I have listed in documentation patch [3]. Also, this approach works
well across power cycles too.
> Are the tee security protections similar to those of the TPM? How do
> they compare?
>
Let me try to compare both environments. Regarding TEE, I will refer
to OP-TEE [4] as one of its implementation.
TPM:
1. External hardware.
2. Sealing key resides inside TPM.
3. Communicates via SPI, I2C etc.
OP-TEE:
1. On chip, trusted execution environment enforced via ARM TrustZone.
2. Sealing key is unique to a particular SoC provided by secure fuses,
secure crypto engine etc.
3. Communicates via Secure Monitor Calls (SMCs [5]).
[1] https://globalplatform.org/resource-publication/webinar-an-introduction-to-tee-technology/
[2] [RFC 3/7] tee: add private login method for kernel clients
[3] [RFC 6/7] doc: keys: Document usage of TEE based Trusted Keys
[4] https://optee.readthedocs.io/general/about.html
[5] http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
-Sumit
> 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: [RFC 2/7] tee: enable support to register kernel memory
From: Jens Wiklander @ 2019-06-14 8:16 UTC (permalink / raw)
To: Sumit Garg
Cc: keyrings, linux-integrity, linux-security-module, corbet,
dhowells, jejb, jarkko.sakkinen, zohar, jmorris, serge,
ard.biesheuvel, daniel.thompson, linux-doc, linux-kernel, tee-dev
In-Reply-To: <1560421833-27414-3-git-send-email-sumit.garg@linaro.org>
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: Jens Wiklander <jens.wiklander@linaro.org>
Thanks,
Jens
^ permalink raw reply
* Re: [RFC 1/7] tee: optee: allow kernel pages to register as shm
From: Jens Wiklander @ 2019-06-14 8:15 UTC (permalink / raw)
To: Sumit Garg
Cc: keyrings, linux-integrity, linux-security-module, corbet,
dhowells, jejb, jarkko.sakkinen, zohar, jmorris, serge,
ard.biesheuvel, daniel.thompson, linux-doc, linux-kernel, tee-dev
In-Reply-To: <1560421833-27414-2-git-send-email-sumit.garg@linaro.org>
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>
Reviewed-by: Jens Wiklander <jens.wiklander@linaro.org>
Thanks,
Jens
^ permalink raw reply
* Re: [PATCH 01/14] ABI: fix some syntax issues at the ABI database
From: Andrew Donnellan @ 2019-06-14 7:20 UTC (permalink / raw)
To: Mauro Carvalho Chehab, 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, Sebastian Reichel, Kees Cook, Anton Vorontsov,
Colin Cross, Tony Luck, linux-iio, linuxppc-dev, linux-pm
In-Reply-To: <b908fc6555df8cae3e4c734b2d5f6284c46a5f14.1560477540.git.mchehab+samsung@kernel.org>
On 14/6/19 12:04 pm, Mauro Carvalho Chehab wrote:
> 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
Would prefer "Please note" over "Please notice".
Acked-by: Andrew Donnellan <ajd@linux.ibm.com> # cxl
--
Andrew Donnellan OzLabs, ADL Canberra
ajd@linux.ibm.com IBM Australia Limited
^ permalink raw reply
* 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
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