* Re: [PATCH v12 04/13] mfd: Add Ingenic TCU driver
From: Paul Cercueil @ 2019-06-22 12:21 UTC (permalink / raw)
To: Rob Herring, Mark Rutland, Ralf Baechle, Paul Burton, James Hogan,
Jonathan Corbet, Daniel Lezcano, Thomas Gleixner,
Michael Turquette, Stephen Boyd, Jason Cooper, Marc Zyngier,
Lee Jones
Cc: Mathieu Malaterre, linux-kernel, devicetree, linux-mips,
linux-doc, linux-clk, od
In-Reply-To: <20190521145141.9813-5-paul@crapouillou.net>
Hi,
I'll make a V13 of this patchset on top of -rc6, any feedback
for this MFD driver? It's been already one month.
Thanks,
-Paul
Le mar. 21 mai 2019 à 16:51, Paul Cercueil <paul@crapouillou.net> a
écrit :
> This driver will provide a regmap that can be retrieved very early in
> the boot process through the API function ingenic_tcu_get_regmap().
>
> Additionally, it will call devm_of_platform_populate() so that all the
> children devices will be probed.
>
> Signed-off-by: Paul Cercueil <paul@crapouillou.net>
> ---
>
> Notes:
> v12: New patch
>
> drivers/mfd/Kconfig | 8 +++
> drivers/mfd/Makefile | 1 +
> drivers/mfd/ingenic-tcu.c | 113
> ++++++++++++++++++++++++++++++++
> include/linux/mfd/ingenic-tcu.h | 8 +++
> 4 files changed, 130 insertions(+)
> create mode 100644 drivers/mfd/ingenic-tcu.c
>
> diff --git a/drivers/mfd/Kconfig b/drivers/mfd/Kconfig
> index 294d9567cc71..a13544474e05 100644
> --- a/drivers/mfd/Kconfig
> +++ b/drivers/mfd/Kconfig
> @@ -494,6 +494,14 @@ config HTC_I2CPLD
> This device provides input and output GPIOs through an I2C
> interface to one or more sub-chips.
>
> +config INGENIC_TCU
> + bool "Ingenic Timer/Counter Unit (TCU) support"
> + depends on MIPS || COMPILE_TEST
> + select REGMAP_MMIO
> + help
> + Say yes here to support the Timer/Counter Unit (TCU) IP present
> + in the JZ47xx SoCs from Ingenic.
> +
> config MFD_INTEL_QUARK_I2C_GPIO
> tristate "Intel Quark MFD I2C GPIO"
> depends on PCI
> diff --git a/drivers/mfd/Makefile b/drivers/mfd/Makefile
> index 52b1a90ff515..fb89e131ae98 100644
> --- a/drivers/mfd/Makefile
> +++ b/drivers/mfd/Makefile
> @@ -180,6 +180,7 @@ obj-$(CONFIG_AB8500_CORE) += ab8500-core.o
> ab8500-sysctrl.o
> obj-$(CONFIG_MFD_TIMBERDALE) += timberdale.o
> obj-$(CONFIG_PMIC_ADP5520) += adp5520.o
> obj-$(CONFIG_MFD_KEMPLD) += kempld-core.o
> +obj-$(CONFIG_INGENIC_TCU) += ingenic-tcu.o
> obj-$(CONFIG_MFD_INTEL_QUARK_I2C_GPIO) += intel_quark_i2c_gpio.o
> obj-$(CONFIG_LPC_SCH) += lpc_sch.o
> obj-$(CONFIG_LPC_ICH) += lpc_ich.o
> diff --git a/drivers/mfd/ingenic-tcu.c b/drivers/mfd/ingenic-tcu.c
> new file mode 100644
> index 000000000000..6c1d5e4310c1
> --- /dev/null
> +++ b/drivers/mfd/ingenic-tcu.c
> @@ -0,0 +1,113 @@
> +// SPDX-License-Identifier: GPL-2.0
> +/*
> + * JZ47xx SoCs TCU MFD driver
> + * Copyright (C) 2019 Paul Cercueil <paul@crapouillou.net>
> + */
> +
> +#include <linux/mfd/ingenic-tcu.h>
> +#include <linux/of_address.h>
> +#include <linux/of_platform.h>
> +#include <linux/platform_device.h>
> +#include <linux/regmap.h>
> +
> +struct ingenic_soc_info {
> + unsigned int num_channels;
> +};
> +
> +static struct regmap *tcu_regmap __initdata;
> +
> +static const struct regmap_config ingenic_tcu_regmap_config = {
> + .reg_bits = 32,
> + .val_bits = 32,
> + .reg_stride = 4,
> + .max_register = TCU_REG_OST_CNTHBUF,
> +};
> +
> +static const struct ingenic_soc_info jz4740_soc_info = {
> + .num_channels = 8,
> +};
> +
> +static const struct ingenic_soc_info jz4725b_soc_info = {
> + .num_channels = 6,
> +};
> +
> +static const struct of_device_id ingenic_tcu_of_match[] = {
> + { .compatible = "ingenic,jz4740-tcu", .data = &jz4740_soc_info, },
> + { .compatible = "ingenic,jz4725b-tcu", .data = &jz4725b_soc_info, },
> + { .compatible = "ingenic,jz4770-tcu", .data = &jz4740_soc_info, },
> + { }
> +};
> +
> +static struct regmap * __init ingenic_tcu_create_regmap(struct
> device_node *np)
> +{
> + struct resource res;
> + void __iomem *base;
> + struct regmap *map;
> +
> + if (!of_match_node(ingenic_tcu_of_match, np))
> + return ERR_PTR(-EINVAL);
> +
> + base = of_io_request_and_map(np, 0, "TCU");
> + if (IS_ERR(base))
> + return ERR_PTR(PTR_ERR(base));
> +
> + map = regmap_init_mmio(NULL, base, &ingenic_tcu_regmap_config);
> + if (IS_ERR(map))
> + goto err_iounmap;
> +
> + return map;
> +
> +err_iounmap:
> + iounmap(base);
> + of_address_to_resource(np, 0, &res);
> + release_mem_region(res.start, resource_size(&res));
> +
> + return map;
> +}
> +
> +static int __init ingenic_tcu_probe(struct platform_device *pdev)
> +{
> + struct regmap *map = ingenic_tcu_get_regmap(pdev->dev.of_node);
> +
> + platform_set_drvdata(pdev, map);
> +
> + regmap_attach_dev(&pdev->dev, map, &ingenic_tcu_regmap_config);
> +
> + return devm_of_platform_populate(&pdev->dev);
> +}
> +
> +static struct platform_driver ingenic_tcu_driver = {
> + .driver = {
> + .name = "ingenic-tcu",
> + .of_match_table = ingenic_tcu_of_match,
> + },
> +};
> +
> +static int __init ingenic_tcu_platform_init(void)
> +{
> + return platform_driver_probe(&ingenic_tcu_driver,
> + ingenic_tcu_probe);
> +}
> +subsys_initcall(ingenic_tcu_platform_init);
> +
> +struct regmap * __init ingenic_tcu_get_regmap(struct device_node *np)
> +{
> + if (!tcu_regmap)
> + tcu_regmap = ingenic_tcu_create_regmap(np);
> +
> + return tcu_regmap;
> +}
> +
> +bool ingenic_tcu_pwm_can_use_chn(struct device *dev, unsigned int
> channel)
> +{
> + const struct ingenic_soc_info *soc =
> device_get_match_data(dev->parent);
> +
> + /* Enable all TCU channels for PWM use by default except channels
> 0/1 */
> + u32 pwm_channels_mask = GENMASK(soc->num_channels - 1, 2);
> +
> + device_property_read_u32(dev->parent, "ingenic,pwm-channels-mask",
> + &pwm_channels_mask);
> +
> + return !!(pwm_channels_mask & BIT(channel));
> +}
> +EXPORT_SYMBOL_GPL(ingenic_tcu_pwm_can_use_chn);
> diff --git a/include/linux/mfd/ingenic-tcu.h
> b/include/linux/mfd/ingenic-tcu.h
> index 2083fa20821d..21df23916cd2 100644
> --- a/include/linux/mfd/ingenic-tcu.h
> +++ b/include/linux/mfd/ingenic-tcu.h
> @@ -6,6 +6,11 @@
> #define __LINUX_MFD_INGENIC_TCU_H_
>
> #include <linux/bitops.h>
> +#include <linux/init.h>
> +
> +struct device;
> +struct device_node;
> +struct regmap;
>
> #define TCU_REG_WDT_TDR 0x00
> #define TCU_REG_WDT_TCER 0x04
> @@ -53,4 +58,7 @@
> #define TCU_REG_TCNTc(c) (TCU_REG_TCNT0 + ((c) * TCU_CHANNEL_STRIDE))
> #define TCU_REG_TCSRc(c) (TCU_REG_TCSR0 + ((c) * TCU_CHANNEL_STRIDE))
>
> +struct regmap * __init ingenic_tcu_get_regmap(struct device_node
> *np);
> +bool ingenic_tcu_pwm_can_use_chn(struct device *dev, unsigned int
> channel);
> +
> #endif /* __LINUX_MFD_INGENIC_TCU_H_ */
> --
> 2.21.0.593.g511ec345e18
>
^ permalink raw reply
* Re: [PATCH v2 22/29] docs: iio: convert to ReST
From: Jonathan Cameron @ 2019-06-22 9:43 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Hartmut Knaack, Lars-Peter Clausen,
Peter Meerwald-Stadler, linux-iio, Jonathan Cameron
In-Reply-To: <f54094f023f1ab7130af64ffdbe4bc4cf66452b9.1560890801.git.mchehab+samsung@kernel.org>
On Tue, 18 Jun 2019 17:53:40 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Rename the iio documentation files to ReST, add an
> index for them and adjust in order to produce a nice html
> output via the Sphinx build system.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
I'll take this via IIO.
Applied to the togreg branch of iio.git and pushed out as testing.
I'll probably do a pull request to Greg tomorrow and these will hopefully
turn up in linux-next not long after that.
Thanks Mauro!
Jonathan
> ---
> .../iio/{ep93xx_adc.txt => ep93xx_adc.rst} | 15 +++++-
> .../{iio_configfs.txt => iio_configfs.rst} | 52 +++++++++++--------
> Documentation/iio/index.rst | 12 +++++
> drivers/iio/Kconfig | 2 +-
> 4 files changed, 56 insertions(+), 25 deletions(-)
> rename Documentation/iio/{ep93xx_adc.txt => ep93xx_adc.rst} (71%)
> rename Documentation/iio/{iio_configfs.txt => iio_configfs.rst} (73%)
> create mode 100644 Documentation/iio/index.rst
>
> diff --git a/Documentation/iio/ep93xx_adc.txt b/Documentation/iio/ep93xx_adc.rst
> similarity index 71%
> rename from Documentation/iio/ep93xx_adc.txt
> rename to Documentation/iio/ep93xx_adc.rst
> index 23053e7817bd..4fd8dea3f6b8 100644
> --- a/Documentation/iio/ep93xx_adc.txt
> +++ b/Documentation/iio/ep93xx_adc.rst
> @@ -1,12 +1,16 @@
> -Cirrus Logic EP93xx ADC driver.
> +==============================
> +Cirrus Logic EP93xx ADC driver
> +==============================
>
> 1. Overview
> +===========
>
> The driver is intended to work on both low-end (EP9301, EP9302) devices with
> 5-channel ADC and high-end (EP9307, EP9312, EP9315) devices with 10-channel
> touchscreen/ADC module.
>
> 2. Channel numbering
> +====================
>
> Numbering scheme for channels 0..4 is defined in EP9301 and EP9302 datasheets.
> EP9307, EP9312 and EP9312 have 3 channels more (total 8), but the numbering is
> @@ -17,13 +21,20 @@ Assuming ep93xx_adc is IIO device0, you'd find the following entries under
>
> +-----------------+---------------+
> | sysfs entry | ball/pin name |
> - +-----------------+---------------+
> + +=================+===============+
> | in_voltage0_raw | YM |
> + +-----------------+---------------+
> | in_voltage1_raw | SXP |
> + +-----------------+---------------+
> | in_voltage2_raw | SXM |
> + +-----------------+---------------+
> | in_voltage3_raw | SYP |
> + +-----------------+---------------+
> | in_voltage4_raw | SYM |
> + +-----------------+---------------+
> | in_voltage5_raw | XP |
> + +-----------------+---------------+
> | in_voltage6_raw | XM |
> + +-----------------+---------------+
> | in_voltage7_raw | YP |
> +-----------------+---------------+
> diff --git a/Documentation/iio/iio_configfs.txt b/Documentation/iio/iio_configfs.rst
> similarity index 73%
> rename from Documentation/iio/iio_configfs.txt
> rename to Documentation/iio/iio_configfs.rst
> index 4e5f101837a8..ecbfdb3afef7 100644
> --- a/Documentation/iio/iio_configfs.txt
> +++ b/Documentation/iio/iio_configfs.rst
> @@ -1,6 +1,9 @@
> +===============================
> Industrial IIO configfs support
> +===============================
>
> 1. Overview
> +===========
>
> Configfs is a filesystem-based manager of kernel objects. IIO uses some
> objects that could be easily configured using configfs (e.g.: devices,
> @@ -10,20 +13,22 @@ See Documentation/filesystems/configfs/configfs.txt for more information
> about how configfs works.
>
> 2. Usage
> +========
>
> In order to use configfs support in IIO we need to select it at compile
> time via CONFIG_IIO_CONFIGFS config option.
>
> -Then, mount the configfs filesystem (usually under /config directory):
> +Then, mount the configfs filesystem (usually under /config directory)::
>
> -$ mkdir /config
> -$ mount -t configfs none /config
> + $ mkdir /config
> + $ mount -t configfs none /config
>
> At this point, all default IIO groups will be created and can be accessed
> under /config/iio. Next chapters will describe available IIO configuration
> objects.
>
> 3. Software triggers
> +====================
>
> One of the IIO default configfs groups is the "triggers" group. It is
> automagically accessible when the configfs is mounted and can be found
> @@ -31,40 +36,40 @@ under /config/iio/triggers.
>
> IIO software triggers implementation offers support for creating multiple
> trigger types. A new trigger type is usually implemented as a separate
> -kernel module following the interface in include/linux/iio/sw_trigger.h:
> +kernel module following the interface in include/linux/iio/sw_trigger.h::
>
> -/*
> - * drivers/iio/trigger/iio-trig-sample.c
> - * sample kernel module implementing a new trigger type
> - */
> -#include <linux/iio/sw_trigger.h>
> + /*
> + * drivers/iio/trigger/iio-trig-sample.c
> + * sample kernel module implementing a new trigger type
> + */
> + #include <linux/iio/sw_trigger.h>
>
>
> -static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
> -{
> + static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
> + {
> /*
> * This allocates and registers an IIO trigger plus other
> * trigger type specific initialization.
> */
> -}
> + }
>
> -static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
> -{
> + static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
> + {
> /*
> * This undoes the actions in iio_trig_sample_probe
> */
> -}
> + }
>
> -static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
> + static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
> .probe = iio_trig_sample_probe,
> .remove = iio_trig_sample_remove,
> -};
> + };
>
> -static struct iio_sw_trigger_type iio_trig_sample = {
> + static struct iio_sw_trigger_type iio_trig_sample = {
> .name = "trig-sample",
> .owner = THIS_MODULE,
> .ops = &iio_trig_sample_ops,
> -};
> + };
>
> module_iio_sw_trigger_driver(iio_trig_sample);
>
> @@ -73,21 +78,24 @@ iio-trig-sample module will create 'trig-sample' trigger type directory
> /config/iio/triggers/trig-sample.
>
> We support the following interrupt sources (trigger types):
> +
> * hrtimer, uses high resolution timers as interrupt source
>
> 3.1 Hrtimer triggers creation and destruction
> +---------------------------------------------
>
> Loading iio-trig-hrtimer module will register hrtimer trigger types allowing
> users to create hrtimer triggers under /config/iio/triggers/hrtimer.
>
> -e.g:
> +e.g::
>
> -$ mkdir /config/iio/triggers/hrtimer/instance1
> -$ rmdir /config/iio/triggers/hrtimer/instance1
> + $ mkdir /config/iio/triggers/hrtimer/instance1
> + $ rmdir /config/iio/triggers/hrtimer/instance1
>
> Each trigger can have one or more attributes specific to the trigger type.
>
> 3.2 "hrtimer" trigger types attributes
> +--------------------------------------
>
> "hrtimer" trigger type doesn't have any configurable attribute from /config dir.
> It does introduce the sampling_frequency attribute to trigger directory.
> diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
> new file mode 100644
> index 000000000000..0593dca89a94
> --- /dev/null
> +++ b/Documentation/iio/index.rst
> @@ -0,0 +1,12 @@
> +:orphan:
> +
> +==============
> +Industrial I/O
> +==============
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + iio_configfs
> +
> + ep93xx_adc
> diff --git a/drivers/iio/Kconfig b/drivers/iio/Kconfig
> index 1d736a4952ab..5bd51853b15e 100644
> --- a/drivers/iio/Kconfig
> +++ b/drivers/iio/Kconfig
> @@ -28,7 +28,7 @@ config IIO_CONFIGFS
> help
> This allows configuring various IIO bits through configfs
> (e.g. software triggers). For more info see
> - Documentation/iio/iio_configfs.txt.
> + Documentation/iio/iio_configfs.rst.
>
> config IIO_TRIGGER
> bool "Enable triggered sampling support"
^ permalink raw reply
* Re: [PATCH v5 00/18] kunit: introduce KUnit, the Linux kernel unit testing framework
From: Brendan Higgins @ 2019-06-22 0:54 UTC (permalink / raw)
To: shuah
Cc: Theodore Ts'o, Frank Rowand, Greg KH, Josh Poimboeuf,
Kees Cook, Kieran Bingham, Luis Chamberlain, Peter Zijlstra,
Rob Herring, Stephen Boyd, Masahiro Yamada, devicetree, dri-devel,
kunit-dev, open list:DOCUMENTATION, linux-fsdevel, linux-kbuild,
Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK,
linux-nvdimm, linux-um, Sasha Levin, Bird, Timothy,
Amir Goldstein, Dan Carpenter, Daniel Vetter, Jeff Dike,
Joel Stanley, Julia Lawall, Kevin Hilman, Knut Omang,
Logan Gunthorpe, Michael Ellerman, Petr Mladek, Randy Dunlap,
Richard Weinberger, David Rientjes, Steven Rostedt, wfg
In-Reply-To: <6f3f5184-d14e-1b46-17f1-391ee67e699c@kernel.org>
On Fri, Jun 21, 2019 at 12:21 PM shuah <shuah@kernel.org> wrote:
>
> On 6/21/19 12:13 PM, Theodore Ts'o wrote:
> > On Fri, Jun 21, 2019 at 08:59:48AM -0600, shuah wrote:
> >>>> ### But wait! Doesn't kselftest support in kernel testing?!
> >>>>
> >>>> ....
> >>
> >> I think I commented on this before. I agree with the statement that
> >> there is no overlap between Kselftest and KUnit. I would like see this
> >> removed. Kselftest module support supports use-cases KUnit won't be able
> >> to. I can build an kernel with Kselftest test modules and use it in the
> >> filed to load and run tests if I need to debug a problem and get data
> >> from a system. I can't do that with KUnit.
Sure, I think this point has been brought up a number of times before.
Maybe I didn't write this section well because, like Frank said, it
comes across as being critical of the Kselftest module support; that
wasn't my intention. I was speaking from the perspective that
Kselftest module support is just a feature of Kselftest, and not a
full framework like KUnit is (obviously Kselftest itself *is* a
framework, but a very small part of it is not).
It was obvious to me what Kselftest module support was intended for,
and it is not intended to cover the use case that KUnit is targeting.
> >> In my mind, I am not viewing this as which is better. Kselftest and
> >> KUnit both have their place in the kernel development process. It isn't
> >> productive and/or necessary to comparing Kselftest and KUnit without a
> >> good understanding of the problem spaces for each of these.
Again, I didn't mean to draw a comparison of which is better than the
other. I was just trying to point out that Kselftest module support
doesn't make sense as a stand alone unit testing framework, or really
a framework of any kind, despite how it might actually be used.
> >> I would strongly recommend not making reference to Kselftest and talk
> >> about what KUnit offers.
I can see your point. It seems that both you and Frank seem to think
that I drew a comparison between Kselftest and KUnit, which was
unintended. I probably should have spent more time editing this
section, but I can see the point of drawing the comparison itself
might invite this confusion.
> > Shuah,
> >
> > Just to recall the history, this section of the FAQ was added to rebut
> > the ***very*** strong statements that Frank made that there was
> > overlap between Kselftest and Kunit, and that having too many ways for
> > kernel developers to do the identical thing was harmful (he said it
> > was too much of a burden on a kernel developer) --- and this was an
> > argument for not including Kunit in the upstream kernel.
I don't think he was actually advocating that we don't include KUnit,
maybe playing devil's advocate; nevertheless, at the end, Frank seemed
to agree that there were valuable things that KUnit offered. I thought
he just wanted to make the point that I hadn't made the distinction
sufficiently clear in the cover letter, and other reviewers might get
confused in the future as well.
Additionally, it does look like people were trying to use Kselftest
module support to cover some things which really were trying to be
unit tests. I know this isn't really intended - everything looks like
a nail when you only have a hammer, which I think Frank was pointing
out furthers the above confusion.
In anycase, it sounds like I have, if anything, only made the
discussion even more confusing by adding this section; sorry about
that.
> > If we're past that objection, then perhaps this section can be
> > dropped, but there's a very good reason why it was there. I wouldn't
> > Brendan to be accused of ignoring feedback from those who reviewed his
> > patches. :-)
> >
>
> Agreed. I understand that this FAQ probably was needed at one time and
> Brendan added it to address the concerns.
I don't want to speak for Frank, but I don't think it was an objection
to KUnit itself, but rather an objection to not sufficiently
addressing the point about how they differ.
> I think at some point we do need to have a document that outlines when
> to KUnit and when to use Kselftest modules. I think one concern people
> have is that if KUnit is perceived as a replacement for Ksefltest
> module, Kselftest module will be ignored leaving users without the
> ability to build and run with Kselftest modules and load them on a need
> basis to gather data on a systems that aren't dedicated strictly for
> testing.
I absolutely agree! I posed a suggestion here[1], which after I just
now searched for a link, I realize for some reason it didn't seem like
it reached a number of the mailing lists that I sent it to, so I
should probably resend it.
Anyway, a summary of what I suggested: We should start off by better
organizing Documentation/dev-tools/ and create a landing page that
groups the dev-tools by function according to what person is likely to
use them and for what. Eventually and specifically for Kselftest and
KUnit, I would like to have a testing guide for the kernel that
explains what testing procedure should look like and what to use and
when.
> I am trying to move the conversation forward from KUnit vs. Kselftest
> modules discussion to which problem areas each one addresses keeping
> in mind that it is not about which is better. Kselftest and KUnit both
> have their place in the kernel development process. We just have to be
> clear on usage as we write tests for each.
I think that is the right long term approach. I think a good place to
start, like I suggested above, is cleaning up
Documentation/dev-tools/, but I think that belongs in a (probably
several) follow-up patchset.
Frank, I believe your objection was mostly related to how KUnit is
presented specifically in the cover letter, and doesn't necessarily
deal with the intended use case. So I don't think that doing this,
especially doing this later, really addresses your concern. I don't
want to belabor the issue, but I would also rather not put words in
your mouth, what are your thoughts on the above?
I think my main concern moving forward on this point is that I am not
sure that I can address the debate that this section covers in a way
that is both sufficiently concise for a cover letter, but also doesn't
invite more potential confusion. My inclination at this point is to
drop it since I think the set of reviewers for this patchset has at
this point become fixed, and it seems that it will likely cause more
confusion rather than reduce it; also, I don't really think this will
be an issue for end users, especially once we have proper
documentation in place. Alternatively, I guess I could maybe address
the point elsewhere and refer to it in the cover letter? Or maybe just
put it at the end of the cover letter?
[1] https://www.mail-archive.com/kgdb-bugreport@lists.sourceforge.net/msg05059.html
^ permalink raw reply
* Re: [PATCH 1/3] Docs: An initial automarkup extension for sphinx
From: Mauro Carvalho Chehab @ 2019-06-22 1:00 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, Matthew Wilcox, Jani Nikula, linux-kernel
In-Reply-To: <20190621235159.6992-2-corbet@lwn.net>
Em Fri, 21 Jun 2019 17:51:57 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Rather than fill our text files with :c:func:`function()` syntax, just do
> the markup via a hook into the sphinx build process.
Didn't test it, but it sounds a way nicer than the past version!
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/conf.py | 3 +-
> Documentation/sphinx/automarkup.py | 80 ++++++++++++++++++++++++++++++
> 2 files changed, 82 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/sphinx/automarkup.py
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 7ace3f8852bd..a502baecbb85 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -34,7 +34,8 @@ 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', 'automarkup']
>
> # 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/automarkup.py b/Documentation/sphinx/automarkup.py
> new file mode 100644
> index 000000000000..14b09b5d145e
> --- /dev/null
> +++ b/Documentation/sphinx/automarkup.py
> @@ -0,0 +1,80 @@
> +# SPDX-License-Identifier: GPL-2.0
> +# Copyright 2019 Jonathan Corbet <corbet@lwn.net>
> +#
> +# Apply kernel-specific tweaks after the initial document processing
> +# has been done.
> +#
> +from docutils import nodes
> +from sphinx import addnodes
> +import re
> +
> +#
> +# Regex nastiness. Of course.
> +# Try to identify "function()" that's not already marked up some
> +# other way. Sphinx doesn't like a lot of stuff right after a
> +# :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last
> +# bit tries to restrict matches to things that won't create trouble.
> +#
> +RE_function = re.compile(r'([\w_][\w\d_]+\(\))')
> +
> +#
> +# The DVB docs create references for these basic system calls, leading
> +# to lots of confusing links. So just don't link them.
> +#
> +Skipfuncs = [ 'open', 'close', 'write' ]
and yeah, of course, if there's something weird, it has to be at
the media docs :-)
Btw, if I'm not mistaken, we do the same for ioctl.
I'm wandering if this could also handle the Documentation/* auto-replace.
The patch snipped I did (against your past version is enclosed).
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 39c8f4d5af82..60dad596c790 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -9,6 +9,7 @@
from __future__ import print_function
import re
import sphinx
+#import sys # Just for debug
#
# Regex nastiness. Of course.
@@ -31,10 +32,26 @@ RE_literal = re.compile(r'^(\s*)(.*::\s*|\.\.\s+code-block::.*)$')
#
RE_whitesp = re.compile(r'^(\s*)')
+#
+# Get a documentation reference
+#
+RE_doc_links = re.compile(r'\bDocumentation/([\w\d\-\_\/]+)\.rst\b')
+
+#
+# Doc link false-positives
+#
+RE_false_doc_links = re.compile(r':ref:`\s*Documentation/[\w\d\-\_\/]+\.rst')
+
def MangleFile(app, docname, text):
ret = [ ]
previous = ''
literal = False
+
+ rel_dir = ''
+
+ for depth in range(0, docname.count('/')):
+ rel_dir += "../"
+
for line in text[0].split('\n'):
#
# See if we might be ending a literal block, as denoted by
@@ -63,7 +80,18 @@ def MangleFile(app, docname, text):
# Normal line - perform substitutions.
#
else:
- ret.append(RE_function.sub(r'\1:c:func:`\2`\3', line))
+# new_line = RE_function.sub(r'\1:c:func:`\2`\3', line)
+ new_line = line
+
+ if not RE_false_doc_links.search(new_line):
+ new_line = RE_doc_links.sub(r':doc:`' + rel_dir + r'\1`', new_line)
+
+ # # Just for debug - should be removed on production
+ # if new_line != line:
+ # print ("===>" + new_line, file=sys.stderr)
+
+ ret.append(new_line)
+
#
# Might we be starting a literal block? If so make note of
# the fact.
Thanks,
Mauro
^ permalink raw reply related
* [PATCH 2/3] docs: remove :c:func: annotations from xarray.rst
From: Jonathan Corbet @ 2019-06-21 23:51 UTC (permalink / raw)
To: linux-doc
Cc: Matthew Wilcox, Mauro Carvalho Chehab, Jani Nikula, linux-kernel,
Jonathan Corbet
In-Reply-To: <20190621235159.6992-1-corbet@lwn.net>
Now that the build system automatically marks up function references, we
don't have to clutter the source files, so take it out.
[Some paragraphs could now benefit from refilling, but that was left out to
avoid obscuring the real changes.]
Acked-by: Matthew Wilcox <willy@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/core-api/xarray.rst | 270 +++++++++++++++---------------
1 file changed, 135 insertions(+), 135 deletions(-)
diff --git a/Documentation/core-api/xarray.rst b/Documentation/core-api/xarray.rst
index ef6f9f98f595..fcedc5349ace 100644
--- a/Documentation/core-api/xarray.rst
+++ b/Documentation/core-api/xarray.rst
@@ -30,27 +30,27 @@ it called marks. Each mark may be set or cleared independently of
the others. You can iterate over entries which are marked.
Normal pointers may be stored in the XArray directly. They must be 4-byte
-aligned, which is true for any pointer returned from :c:func:`kmalloc` and
-:c:func:`alloc_page`. It isn't true for arbitrary user-space pointers,
+aligned, which is true for any pointer returned from kmalloc() and
+alloc_page(). It isn't true for arbitrary user-space pointers,
nor for function pointers. You can store pointers to statically allocated
objects, as long as those objects have an alignment of at least 4.
You can also store integers between 0 and ``LONG_MAX`` in the XArray.
-You must first convert it into an entry using :c:func:`xa_mk_value`.
+You must first convert it into an entry using xa_mk_value().
When you retrieve an entry from the XArray, you can check whether it is
-a value entry by calling :c:func:`xa_is_value`, and convert it back to
-an integer by calling :c:func:`xa_to_value`.
+a value entry by calling xa_is_value(), and convert it back to
+an integer by calling xa_to_value().
Some users want to store tagged pointers instead of using the marks
-described above. They can call :c:func:`xa_tag_pointer` to create an
-entry with a tag, :c:func:`xa_untag_pointer` to turn a tagged entry
-back into an untagged pointer and :c:func:`xa_pointer_tag` to retrieve
+described above. They can call xa_tag_pointer() to create an
+entry with a tag, xa_untag_pointer() to turn a tagged entry
+back into an untagged pointer and xa_pointer_tag() to retrieve
the tag of an entry. Tagged pointers use the same bits that are used
to distinguish value entries from normal pointers, so each user must
decide whether they want to store value entries or tagged pointers in
any particular XArray.
-The XArray does not support storing :c:func:`IS_ERR` pointers as some
+The XArray does not support storing IS_ERR() pointers as some
conflict with value entries or internal entries.
An unusual feature of the XArray is the ability to create entries which
@@ -64,89 +64,89 @@ entry will cause the XArray to forget about the range.
Normal API
==========
-Start by initialising an XArray, either with :c:func:`DEFINE_XARRAY`
-for statically allocated XArrays or :c:func:`xa_init` for dynamically
+Start by initialising an XArray, either with DEFINE_XARRAY()
+for statically allocated XArrays or xa_init() for dynamically
allocated ones. A freshly-initialised XArray contains a ``NULL``
pointer at every index.
-You can then set entries using :c:func:`xa_store` and get entries
-using :c:func:`xa_load`. xa_store will overwrite any entry with the
+You can then set entries using xa_store() and get entries
+using xa_load(). xa_store will overwrite any entry with the
new entry and return the previous entry stored at that index. You can
-use :c:func:`xa_erase` instead of calling :c:func:`xa_store` with a
+use xa_erase() instead of calling xa_store() with a
``NULL`` entry. There is no difference between an entry that has never
been stored to, one that has been erased and one that has most recently
had ``NULL`` stored to it.
You can conditionally replace an entry at an index by using
-:c:func:`xa_cmpxchg`. Like :c:func:`cmpxchg`, it will only succeed if
+xa_cmpxchg(). Like cmpxchg(), it will only succeed if
the entry at that index has the 'old' value. It also returns the entry
which was at that index; if it returns the same entry which was passed as
-'old', then :c:func:`xa_cmpxchg` succeeded.
+'old', then xa_cmpxchg() succeeded.
If you want to only store a new entry to an index if the current entry
-at that index is ``NULL``, you can use :c:func:`xa_insert` which
+at that index is ``NULL``, you can use xa_insert() which
returns ``-EBUSY`` if the entry is not empty.
You can enquire whether a mark is set on an entry by using
-:c:func:`xa_get_mark`. If the entry is not ``NULL``, you can set a mark
-on it by using :c:func:`xa_set_mark` and remove the mark from an entry by
-calling :c:func:`xa_clear_mark`. You can ask whether any entry in the
-XArray has a particular mark set by calling :c:func:`xa_marked`.
+xa_get_mark(). If the entry is not ``NULL``, you can set a mark
+on it by using xa_set_mark() and remove the mark from an entry by
+calling xa_clear_mark(). You can ask whether any entry in the
+XArray has a particular mark set by calling xa_marked().
You can copy entries out of the XArray into a plain array by calling
-:c:func:`xa_extract`. Or you can iterate over the present entries in
-the XArray by calling :c:func:`xa_for_each`. You may prefer to use
-:c:func:`xa_find` or :c:func:`xa_find_after` to move to the next present
+xa_extract(). Or you can iterate over the present entries in
+the XArray by calling xa_for_each(). You may prefer to use
+xa_find() or xa_find_after() to move to the next present
entry in the XArray.
-Calling :c:func:`xa_store_range` stores the same entry in a range
+Calling xa_store_range() stores the same entry in a range
of indices. If you do this, some of the other operations will behave
in a slightly odd way. For example, marking the entry at one index
may result in the entry being marked at some, but not all of the other
indices. Storing into one index may result in the entry retrieved by
some, but not all of the other indices changing.
-Sometimes you need to ensure that a subsequent call to :c:func:`xa_store`
-will not need to allocate memory. The :c:func:`xa_reserve` function
+Sometimes you need to ensure that a subsequent call to xa_store()
+will not need to allocate memory. The xa_reserve() function
will store a reserved entry at the indicated index. Users of the
normal API will see this entry as containing ``NULL``. If you do
-not need to use the reserved entry, you can call :c:func:`xa_release`
+not need to use the reserved entry, you can call xa_release()
to remove the unused entry. If another user has stored to the entry
-in the meantime, :c:func:`xa_release` will do nothing; if instead you
-want the entry to become ``NULL``, you should use :c:func:`xa_erase`.
-Using :c:func:`xa_insert` on a reserved entry will fail.
+in the meantime, xa_release() will do nothing; if instead you
+want the entry to become ``NULL``, you should use xa_erase().
+Using xa_insert() on a reserved entry will fail.
-If all entries in the array are ``NULL``, the :c:func:`xa_empty` function
+If all entries in the array are ``NULL``, the xa_empty() function
will return ``true``.
Finally, you can remove all entries from an XArray by calling
-:c:func:`xa_destroy`. If the XArray entries are pointers, you may wish
+xa_destroy(). If the XArray entries are pointers, you may wish
to free the entries first. You can do this by iterating over all present
-entries in the XArray using the :c:func:`xa_for_each` iterator.
+entries in the XArray using the xa_for_each() iterator.
Allocating XArrays
------------------
-If you use :c:func:`DEFINE_XARRAY_ALLOC` to define the XArray, or
-initialise it by passing ``XA_FLAGS_ALLOC`` to :c:func:`xa_init_flags`,
+If you use DEFINE_XARRAY_ALLOC() to define the XArray, or
+initialise it by passing ``XA_FLAGS_ALLOC`` to xa_init_flags(),
the XArray changes to track whether entries are in use or not.
-You can call :c:func:`xa_alloc` to store the entry at an unused index
+You can call xa_alloc() to store the entry at an unused index
in the XArray. If you need to modify the array from interrupt context,
-you can use :c:func:`xa_alloc_bh` or :c:func:`xa_alloc_irq` to disable
+you can use xa_alloc_bh() or xa_alloc_irq() to disable
interrupts while allocating the ID.
-Using :c:func:`xa_store`, :c:func:`xa_cmpxchg` or :c:func:`xa_insert` will
+Using xa_store(), xa_cmpxchg() or xa_insert() will
also mark the entry as being allocated. Unlike a normal XArray, storing
-``NULL`` will mark the entry as being in use, like :c:func:`xa_reserve`.
-To free an entry, use :c:func:`xa_erase` (or :c:func:`xa_release` if
+``NULL`` will mark the entry as being in use, like xa_reserve().
+To free an entry, use xa_erase() (or xa_release() if
you only want to free the entry if it's ``NULL``).
By default, the lowest free entry is allocated starting from 0. If you
want to allocate entries starting at 1, it is more efficient to use
-:c:func:`DEFINE_XARRAY_ALLOC1` or ``XA_FLAGS_ALLOC1``. If you want to
+DEFINE_XARRAY_ALLOC1() or ``XA_FLAGS_ALLOC1``. If you want to
allocate IDs up to a maximum, then wrap back around to the lowest free
-ID, you can use :c:func:`xa_alloc_cyclic`.
+ID, you can use xa_alloc_cyclic().
You cannot use ``XA_MARK_0`` with an allocating XArray as this mark
is used to track whether an entry is free or not. The other marks are
@@ -155,17 +155,17 @@ available for your use.
Memory allocation
-----------------
-The :c:func:`xa_store`, :c:func:`xa_cmpxchg`, :c:func:`xa_alloc`,
-:c:func:`xa_reserve` and :c:func:`xa_insert` functions take a gfp_t
+The xa_store(), xa_cmpxchg(), xa_alloc(),
+xa_reserve() and xa_insert() functions take a gfp_t
parameter in case the XArray needs to allocate memory to store this entry.
If the entry is being deleted, no memory allocation needs to be performed,
and the GFP flags specified will be ignored.
It is possible for no memory to be allocatable, particularly if you pass
a restrictive set of GFP flags. In that case, the functions return a
-special value which can be turned into an errno using :c:func:`xa_err`.
+special value which can be turned into an errno using xa_err().
If you don't need to know exactly which error occurred, using
-:c:func:`xa_is_err` is slightly more efficient.
+xa_is_err() is slightly more efficient.
Locking
-------
@@ -174,54 +174,54 @@ When using the Normal API, you do not have to worry about locking.
The XArray uses RCU and an internal spinlock to synchronise access:
No lock needed:
- * :c:func:`xa_empty`
- * :c:func:`xa_marked`
+ * xa_empty()
+ * xa_marked()
Takes RCU read lock:
- * :c:func:`xa_load`
- * :c:func:`xa_for_each`
- * :c:func:`xa_find`
- * :c:func:`xa_find_after`
- * :c:func:`xa_extract`
- * :c:func:`xa_get_mark`
+ * xa_load()
+ * xa_for_each()
+ * xa_find()
+ * xa_find_after()
+ * xa_extract()
+ * xa_get_mark()
Takes xa_lock internally:
- * :c:func:`xa_store`
- * :c:func:`xa_store_bh`
- * :c:func:`xa_store_irq`
- * :c:func:`xa_insert`
- * :c:func:`xa_insert_bh`
- * :c:func:`xa_insert_irq`
- * :c:func:`xa_erase`
- * :c:func:`xa_erase_bh`
- * :c:func:`xa_erase_irq`
- * :c:func:`xa_cmpxchg`
- * :c:func:`xa_cmpxchg_bh`
- * :c:func:`xa_cmpxchg_irq`
- * :c:func:`xa_store_range`
- * :c:func:`xa_alloc`
- * :c:func:`xa_alloc_bh`
- * :c:func:`xa_alloc_irq`
- * :c:func:`xa_reserve`
- * :c:func:`xa_reserve_bh`
- * :c:func:`xa_reserve_irq`
- * :c:func:`xa_destroy`
- * :c:func:`xa_set_mark`
- * :c:func:`xa_clear_mark`
+ * xa_store()
+ * xa_store_bh()
+ * xa_store_irq()
+ * xa_insert()
+ * xa_insert_bh()
+ * xa_insert_irq()
+ * xa_erase()
+ * xa_erase_bh()
+ * xa_erase_irq()
+ * xa_cmpxchg()
+ * xa_cmpxchg_bh()
+ * xa_cmpxchg_irq()
+ * xa_store_range()
+ * xa_alloc()
+ * xa_alloc_bh()
+ * xa_alloc_irq()
+ * xa_reserve()
+ * xa_reserve_bh()
+ * xa_reserve_irq()
+ * xa_destroy()
+ * xa_set_mark()
+ * xa_clear_mark()
Assumes xa_lock held on entry:
- * :c:func:`__xa_store`
- * :c:func:`__xa_insert`
- * :c:func:`__xa_erase`
- * :c:func:`__xa_cmpxchg`
- * :c:func:`__xa_alloc`
- * :c:func:`__xa_set_mark`
- * :c:func:`__xa_clear_mark`
+ * __xa_store()
+ * __xa_insert()
+ * __xa_erase()
+ * __xa_cmpxchg()
+ * __xa_alloc()
+ * __xa_set_mark()
+ * __xa_clear_mark()
If you want to take advantage of the lock to protect the data structures
-that you are storing in the XArray, you can call :c:func:`xa_lock`
-before calling :c:func:`xa_load`, then take a reference count on the
-object you have found before calling :c:func:`xa_unlock`. This will
+that you are storing in the XArray, you can call xa_lock()
+before calling xa_load(), then take a reference count on the
+object you have found before calling xa_unlock(). This will
prevent stores from removing the object from the array between looking
up the object and incrementing the refcount. You can also use RCU to
avoid dereferencing freed memory, but an explanation of that is beyond
@@ -261,7 +261,7 @@ context and then erase them in softirq context, you can do that this way::
}
If you are going to modify the XArray from interrupt or softirq context,
-you need to initialise the array using :c:func:`xa_init_flags`, passing
+you need to initialise the array using xa_init_flags(), passing
``XA_FLAGS_LOCK_IRQ`` or ``XA_FLAGS_LOCK_BH``.
The above example also shows a common pattern of wanting to extend the
@@ -269,20 +269,20 @@ coverage of the xa_lock on the store side to protect some statistics
associated with the array.
Sharing the XArray with interrupt context is also possible, either
-using :c:func:`xa_lock_irqsave` in both the interrupt handler and process
-context, or :c:func:`xa_lock_irq` in process context and :c:func:`xa_lock`
+using xa_lock_irqsave() in both the interrupt handler and process
+context, or xa_lock_irq() in process context and xa_lock()
in the interrupt handler. Some of the more common patterns have helper
-functions such as :c:func:`xa_store_bh`, :c:func:`xa_store_irq`,
-:c:func:`xa_erase_bh`, :c:func:`xa_erase_irq`, :c:func:`xa_cmpxchg_bh`
-and :c:func:`xa_cmpxchg_irq`.
+functions such as xa_store_bh(), xa_store_irq(),
+xa_erase_bh(), xa_erase_irq(), xa_cmpxchg_bh()
+and xa_cmpxchg_irq().
Sometimes you need to protect access to the XArray with a mutex because
that lock sits above another mutex in the locking hierarchy. That does
-not entitle you to use functions like :c:func:`__xa_erase` without taking
+not entitle you to use functions like __xa_erase() without taking
the xa_lock; the xa_lock is used for lockdep validation and will be used
for other purposes in the future.
-The :c:func:`__xa_set_mark` and :c:func:`__xa_clear_mark` functions are also
+The __xa_set_mark() and __xa_clear_mark() functions are also
available for situations where you look up an entry and want to atomically
set or clear a mark. It may be more efficient to use the advanced API
in this case, as it will save you from walking the tree twice.
@@ -300,27 +300,27 @@ indeed the normal API is implemented in terms of the advanced API. The
advanced API is only available to modules with a GPL-compatible license.
The advanced API is based around the xa_state. This is an opaque data
-structure which you declare on the stack using the :c:func:`XA_STATE`
+structure which you declare on the stack using the XA_STATE()
macro. This macro initialises the xa_state ready to start walking
around the XArray. It is used as a cursor to maintain the position
in the XArray and let you compose various operations together without
having to restart from the top every time.
The xa_state is also used to store errors. You can call
-:c:func:`xas_error` to retrieve the error. All operations check whether
+xas_error() to retrieve the error. All operations check whether
the xa_state is in an error state before proceeding, so there's no need
for you to check for an error after each call; you can make multiple
calls in succession and only check at a convenient point. The only
errors currently generated by the XArray code itself are ``ENOMEM`` and
``EINVAL``, but it supports arbitrary errors in case you want to call
-:c:func:`xas_set_err` yourself.
+xas_set_err() yourself.
-If the xa_state is holding an ``ENOMEM`` error, calling :c:func:`xas_nomem`
+If the xa_state is holding an ``ENOMEM`` error, calling xas_nomem()
will attempt to allocate more memory using the specified gfp flags and
cache it in the xa_state for the next attempt. The idea is that you take
the xa_lock, attempt the operation and drop the lock. The operation
attempts to allocate memory while holding the lock, but it is more
-likely to fail. Once you have dropped the lock, :c:func:`xas_nomem`
+likely to fail. Once you have dropped the lock, xas_nomem()
can try harder to allocate more memory. It will return ``true`` if it
is worth retrying the operation (i.e. that there was a memory error *and*
more memory was allocated). If it has previously allocated memory, and
@@ -333,7 +333,7 @@ Internal Entries
The XArray reserves some entries for its own purposes. These are never
exposed through the normal API, but when using the advanced API, it's
possible to see them. Usually the best way to handle them is to pass them
-to :c:func:`xas_retry`, and retry the operation if it returns ``true``.
+to xas_retry(), and retry the operation if it returns ``true``.
.. flat-table::
:widths: 1 1 6
@@ -343,89 +343,89 @@ to :c:func:`xas_retry`, and retry the operation if it returns ``true``.
- Usage
* - Node
- - :c:func:`xa_is_node`
+ - xa_is_node()
- An XArray node. May be visible when using a multi-index xa_state.
* - Sibling
- - :c:func:`xa_is_sibling`
+ - xa_is_sibling()
- A non-canonical entry for a multi-index entry. The value indicates
which slot in this node has the canonical entry.
* - Retry
- - :c:func:`xa_is_retry`
+ - xa_is_retry()
- This entry is currently being modified by a thread which has the
xa_lock. The node containing this entry may be freed at the end
of this RCU period. You should restart the lookup from the head
of the array.
* - Zero
- - :c:func:`xa_is_zero`
+ - xa_is_zero()
- Zero entries appear as ``NULL`` through the Normal API, but occupy
an entry in the XArray which can be used to reserve the index for
future use. This is used by allocating XArrays for allocated entries
which are ``NULL``.
Other internal entries may be added in the future. As far as possible, they
-will be handled by :c:func:`xas_retry`.
+will be handled by xas_retry().
Additional functionality
------------------------
-The :c:func:`xas_create_range` function allocates all the necessary memory
+The xas_create_range() function allocates all the necessary memory
to store every entry in a range. It will set ENOMEM in the xa_state if
it cannot allocate memory.
-You can use :c:func:`xas_init_marks` to reset the marks on an entry
+You can use xas_init_marks() to reset the marks on an entry
to their default state. This is usually all marks clear, unless the
XArray is marked with ``XA_FLAGS_TRACK_FREE``, in which case mark 0 is set
and all other marks are clear. Replacing one entry with another using
-:c:func:`xas_store` will not reset the marks on that entry; if you want
+xas_store() will not reset the marks on that entry; if you want
the marks reset, you should do that explicitly.
-The :c:func:`xas_load` will walk the xa_state as close to the entry
+The xas_load() will walk the xa_state as close to the entry
as it can. If you know the xa_state has already been walked to the
entry and need to check that the entry hasn't changed, you can use
-:c:func:`xas_reload` to save a function call.
+xas_reload() to save a function call.
If you need to move to a different index in the XArray, call
-:c:func:`xas_set`. This resets the cursor to the top of the tree, which
+xas_set(). This resets the cursor to the top of the tree, which
will generally make the next operation walk the cursor to the desired
spot in the tree. If you want to move to the next or previous index,
-call :c:func:`xas_next` or :c:func:`xas_prev`. Setting the index does
+call xas_next() or xas_prev(). Setting the index does
not walk the cursor around the array so does not require a lock to be
held, while moving to the next or previous index does.
-You can search for the next present entry using :c:func:`xas_find`. This
-is the equivalent of both :c:func:`xa_find` and :c:func:`xa_find_after`;
+You can search for the next present entry using xas_find(). This
+is the equivalent of both xa_find() and xa_find_after();
if the cursor has been walked to an entry, then it will find the next
entry after the one currently referenced. If not, it will return the
-entry at the index of the xa_state. Using :c:func:`xas_next_entry` to
-move to the next present entry instead of :c:func:`xas_find` will save
+entry at the index of the xa_state. Using xas_next_entry() to
+move to the next present entry instead of xas_find() will save
a function call in the majority of cases at the expense of emitting more
inline code.
-The :c:func:`xas_find_marked` function is similar. If the xa_state has
+The xas_find_marked() function is similar. If the xa_state has
not been walked, it will return the entry at the index of the xa_state,
if it is marked. Otherwise, it will return the first marked entry after
-the entry referenced by the xa_state. The :c:func:`xas_next_marked`
-function is the equivalent of :c:func:`xas_next_entry`.
+the entry referenced by the xa_state. The xas_next_marked()
+function is the equivalent of xas_next_entry().
-When iterating over a range of the XArray using :c:func:`xas_for_each`
-or :c:func:`xas_for_each_marked`, it may be necessary to temporarily stop
-the iteration. The :c:func:`xas_pause` function exists for this purpose.
+When iterating over a range of the XArray using xas_for_each()
+or xas_for_each_marked(), it may be necessary to temporarily stop
+the iteration. The xas_pause() function exists for this purpose.
After you have done the necessary work and wish to resume, the xa_state
is in an appropriate state to continue the iteration after the entry
you last processed. If you have interrupts disabled while iterating,
then it is good manners to pause the iteration and reenable interrupts
every ``XA_CHECK_SCHED`` entries.
-The :c:func:`xas_get_mark`, :c:func:`xas_set_mark` and
-:c:func:`xas_clear_mark` functions require the xa_state cursor to have
+The xas_get_mark(), xas_set_mark() and
+xas_clear_mark() functions require the xa_state cursor to have
been moved to the appropriate location in the xarray; they will do
-nothing if you have called :c:func:`xas_pause` or :c:func:`xas_set`
+nothing if you have called xas_pause() or xas_set()
immediately before.
-You can call :c:func:`xas_set_update` to have a callback function
+You can call xas_set_update() to have a callback function
called each time the XArray updates a node. This is used by the page
cache workingset code to maintain its list of nodes which contain only
shadow entries.
@@ -443,25 +443,25 @@ eg indices 64-127 may be tied together, but 2-6 may not be. This may
save substantial quantities of memory; for example tying 512 entries
together will save over 4kB.
-You can create a multi-index entry by using :c:func:`XA_STATE_ORDER`
-or :c:func:`xas_set_order` followed by a call to :c:func:`xas_store`.
-Calling :c:func:`xas_load` with a multi-index xa_state will walk the
+You can create a multi-index entry by using XA_STATE_ORDER()
+or xas_set_order() followed by a call to xas_store().
+Calling xas_load() with a multi-index xa_state will walk the
xa_state to the right location in the tree, but the return value is not
meaningful, potentially being an internal entry or ``NULL`` even when there
-is an entry stored within the range. Calling :c:func:`xas_find_conflict`
+is an entry stored within the range. Calling xas_find_conflict()
will return the first entry within the range or ``NULL`` if there are no
-entries in the range. The :c:func:`xas_for_each_conflict` iterator will
+entries in the range. The xas_for_each_conflict() iterator will
iterate over every entry which overlaps the specified range.
-If :c:func:`xas_load` encounters a multi-index entry, the xa_index
+If xas_load() encounters a multi-index entry, the xa_index
in the xa_state will not be changed. When iterating over an XArray
-or calling :c:func:`xas_find`, if the initial index is in the middle
+or calling xas_find(), if the initial index is in the middle
of a multi-index entry, it will not be altered. Subsequent calls
or iterations will move the index to the first index in the range.
Each entry will only be returned once, no matter how many indices it
occupies.
-Using :c:func:`xas_next` or :c:func:`xas_prev` with a multi-index xa_state
+Using xas_next() or xas_prev() with a multi-index xa_state
is not supported. Using either of these functions on a multi-index entry
will reveal sibling entries; these should be skipped over by the caller.
--
2.21.0
^ permalink raw reply related
* [PATCH 1/3] Docs: An initial automarkup extension for sphinx
From: Jonathan Corbet @ 2019-06-21 23:51 UTC (permalink / raw)
To: linux-doc
Cc: Matthew Wilcox, Mauro Carvalho Chehab, Jani Nikula, linux-kernel,
Jonathan Corbet
In-Reply-To: <20190621235159.6992-1-corbet@lwn.net>
Rather than fill our text files with :c:func:`function()` syntax, just do
the markup via a hook into the sphinx build process.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/conf.py | 3 +-
Documentation/sphinx/automarkup.py | 80 ++++++++++++++++++++++++++++++
2 files changed, 82 insertions(+), 1 deletion(-)
create mode 100644 Documentation/sphinx/automarkup.py
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 7ace3f8852bd..a502baecbb85 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -34,7 +34,8 @@ 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', 'automarkup']
# 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/automarkup.py b/Documentation/sphinx/automarkup.py
new file mode 100644
index 000000000000..14b09b5d145e
--- /dev/null
+++ b/Documentation/sphinx/automarkup.py
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: GPL-2.0
+# Copyright 2019 Jonathan Corbet <corbet@lwn.net>
+#
+# Apply kernel-specific tweaks after the initial document processing
+# has been done.
+#
+from docutils import nodes
+from sphinx import addnodes
+import re
+
+#
+# Regex nastiness. Of course.
+# Try to identify "function()" that's not already marked up some
+# other way. Sphinx doesn't like a lot of stuff right after a
+# :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last
+# bit tries to restrict matches to things that won't create trouble.
+#
+RE_function = re.compile(r'([\w_][\w\d_]+\(\))')
+
+#
+# The DVB docs create references for these basic system calls, leading
+# to lots of confusing links. So just don't link them.
+#
+Skipfuncs = [ 'open', 'close', 'write' ]
+
+#
+# Find all occurrences of function() and try to replace them with
+# appropriate cross references.
+#
+def markup_funcs(docname, app, node):
+ cdom = app.env.domains['c']
+ t = node.astext()
+ done = 0
+ repl = [ ]
+ for m in RE_function.finditer(t):
+ #
+ # Include any text prior to function() as a normal text node.
+ #
+ if m.start() > done:
+ repl.append(nodes.Text(t[done:m.start()]))
+ #
+ # Go through the dance of getting an xref out of the C domain
+ #
+ target = m.group(1)[:-2]
+ target_text = nodes.Text(target + '()')
+ xref = None
+ if target not in Skipfuncs:
+ lit_text = nodes.literal(classes=['xref', 'c', 'c-func'])
+ lit_text += target_text
+ pxref = addnodes.pending_xref('', refdomain = 'c',
+ reftype = 'function',
+ reftarget = target, modname = None,
+ classname = None)
+ xref = cdom.resolve_xref(app.env, docname, app.builder,
+ 'function', target, pxref, lit_text)
+ #
+ # Toss the xref into the list if we got it; otherwise just put
+ # the function text.
+ #
+ if xref:
+ repl.append(xref)
+ else:
+ repl.append(target_text)
+ done = m.end()
+ if done < len(t):
+ repl.append(nodes.Text(t[done:]))
+ return repl
+
+def auto_markup(app, doctree, name):
+ for para in doctree.traverse(nodes.paragraph):
+ for node in para.traverse(nodes.Text):
+ if not isinstance(node.parent, nodes.literal):
+ node.parent.replace(node, markup_funcs(name, app, node))
+
+def setup(app):
+ app.connect('doctree-resolved', auto_markup)
+ return {
+ 'parallel_read_safe': True,
+ 'parallel_write_safe': True,
+ }
--
2.21.0
^ permalink raw reply related
* [PATCH 3/3] kernel-doc: Don't try to mark up function names
From: Jonathan Corbet @ 2019-06-21 23:51 UTC (permalink / raw)
To: linux-doc
Cc: Matthew Wilcox, Mauro Carvalho Chehab, Jani Nikula, linux-kernel,
Jonathan Corbet
In-Reply-To: <20190621235159.6992-1-corbet@lwn.net>
We now have better automarkup in sphinx itself and, besides, this markup
was incorrect and left :c:func: gunk in the processed docs. Sort of
discouraging that nobody ever noticed...:)
As a first step toward the removal of impenetrable regex magic from
kernel-doc it's a tiny one, but you have to start somewhere.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
scripts/kernel-doc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c0cb41e65b9b..6b03012750da 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -249,7 +249,7 @@ my @highlights_rst = (
[$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
[$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
[$type_fp_param, "**\$1\\\\(\\\\)**"],
- [$type_func, "\\:c\\:func\\:`\$1()`"],
+ [$type_func, "\$1()"],
[$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
[$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
[$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
--
2.21.0
^ permalink raw reply related
* [PATCH 0/3 v2] docs: function automarkup, now with 80% fewer regexes!
From: Jonathan Corbet @ 2019-06-21 23:51 UTC (permalink / raw)
To: linux-doc
Cc: Matthew Wilcox, Mauro Carvalho Chehab, Jani Nikula, linux-kernel,
Jonathan Corbet
It took me a loooong time to get back to this, but here's another crack at
automatically marking up "function()" so we can get rid of all that
unsightly :c:func: gunk in our docs. This time, it's implemented as a pass
over the doctree after everything's read and the references resolved, and
the result is certainly far more robust than my first attempt.
Jonathan Corbet (3):
Docs: An initial automarkup extension for sphinx
docs: remove :c:func: annotations from xarray.rst
kernel-doc: Don't try to mark up function names
Documentation/conf.py | 3 +-
Documentation/core-api/xarray.rst | 270 ++++++++++++++---------------
Documentation/sphinx/automarkup.py | 80 +++++++++
scripts/kernel-doc | 2 +-
4 files changed, 218 insertions(+), 137 deletions(-)
create mode 100644 Documentation/sphinx/automarkup.py
--
2.21.0
^ permalink raw reply
* Re: [PATCH v5 00/18] kunit: introduce KUnit, the Linux kernel unit testing framework
From: Brendan Higgins @ 2019-06-21 23:35 UTC (permalink / raw)
To: Frank Rowand
Cc: Greg KH, Josh Poimboeuf, Kees Cook, Kieran Bingham,
Luis Chamberlain, Peter Zijlstra, Rob Herring, Stephen Boyd,
shuah, Theodore Ts'o, Masahiro Yamada, devicetree, dri-devel,
kunit-dev, open list:DOCUMENTATION, linux-fsdevel, linux-kbuild,
Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK,
linux-nvdimm, linux-um, Sasha Levin, Bird, Timothy,
Amir Goldstein, Dan Carpenter, Daniel Vetter, Jeff Dike,
Joel Stanley, Julia Lawall, Kevin Hilman, Knut Omang,
Logan Gunthorpe, Michael Ellerman, Petr Mladek, Randy Dunlap,
Richard Weinberger, David Rientjes, Steven Rostedt, wfg
In-Reply-To: <10feac3e-7621-65e5-fbf0-9c63fcbe09c9@gmail.com>
On Wed, Jun 19, 2019 at 6:17 PM Frank Rowand <frowand.list@gmail.com> wrote:
>
> Hi Brendan,
>
> I am only responding to this because you asked me to in the v4 thread.
Yes, I did! Thank you, I appreciate it!
> Thank you for evaluating my comments in the v4 thread and asking me to
> comment on v5
Of course, I feel as though I ought to address any and all valid comments.
> On 6/17/19 1:25 AM, Brendan Higgins wrote:
> > ## TL;DR
> >
> > A not so quick follow-up to Stephen's suggestions on PATCH v4. Nothing
> > that really changes any functionality or usage with the minor exception
> > of a couple public functions that Stephen asked me to rename.
> > Nevertheless, a good deal of clean up and fixes. See changes below.
> >
> > As for our current status, right now we got Reviewed-bys on all patches
> > except:
> >
> > - [PATCH v5 08/18] objtool: add kunit_try_catch_throw to the noreturn
> > list
> >
> > However, it would probably be good to get reviews/acks from the
> > subsystem maintainers on:
> >
> > - [PATCH v5 06/18] kbuild: enable building KUnit
> > - [PATCH v5 08/18] objtool: add kunit_try_catch_throw to the noreturn
> > list
> > - [PATCH v5 15/18] Documentation: kunit: add documentation for KUnit
> > - [PATCH v5 17/18] kernel/sysctl-test: Add null pointer test for
> > sysctl.c:proc_dointvec()
> > - [PATCH v5 18/18] MAINTAINERS: add proc sysctl KUnit test to PROC
> > SYSCTL section
> >
> > Other than that, I think we should be good to go.
> >
> > One last thing, I updated the background to include my thoughts on KUnit
> > vs. in kernel testing with kselftest in the background sections as
> > suggested by Frank in the discussion on PATCH v2.
> >
> > ## Background
> >
> > This patch set proposes KUnit, a lightweight unit testing and mocking
> > framework for the Linux kernel.
> >
> > Unlike Autotest and kselftest, KUnit is a true unit testing framework;
> > it does not require installing the kernel on a test machine or in a VM
> > (however, KUnit still allows you to run tests on test machines or in VMs
> > if you want[1]) and does not require tests to be written in userspace
> > running on a host kernel. Additionally, KUnit is fast: From invocation
> > to completion KUnit can run several dozen tests in under a second.
> > Currently, the entire KUnit test suite for KUnit runs in under a second
> > from the initial invocation (build time excluded).
> >
> > KUnit is heavily inspired by JUnit, Python's unittest.mock, and
> > Googletest/Googlemock for C++. KUnit provides facilities for defining
> > unit test cases, grouping related test cases into test suites, providing
> > common infrastructure for running tests, mocking, spying, and much more.
> >
>
> I looked only at this section, as was specifically requested:
>
> > ### But wait! Doesn't kselftest support in kernel testing?!
> >
> > In a previous version of this patchset Frank pointed out that kselftest
> > already supports writing a test that resides in the kernel using the
> > test module feature[2]. LWN did a really great summary on this
> > discussion here[3].
> >
> > Kselftest has a feature that allows a test module to be loaded into a
> > kernel using the kselftest framework; this does allow someone to write
> > tests against kernel code not directly exposed to userland; however, it
> > does not provide much of a framework around how to structure the tests.
> > The kselftest test module feature just provides a header which has a
> > standardized way of reporting test failures,
>
>
> > and then provides
> > infrastructure to load and run the tests using the kselftest test
> > harness.
>
> The in-kernel tests can also be invoked at boot time if they are
> configured (Kconfig) as in-kernel instead of as modules. I did not
> check how many of the tests have tri-state configuration to allow
> this, but the few that I looked at did.
>
> >
> > The kselftest test module does not seem to be opinionated at all in
> > regards to how tests are structured, how they check for failures, how
> > tests are organized. Even in the method it provides for reporting
> > failures is pretty simple; it doesn't have any more advanced failure
> > reporting or logging features. Given what's there, I think it is fair to
> > say that it is not actually a framework, but a feature that makes it
> > possible for someone to do some checks in kernel space.
>
> I would call that description a little dismissive. The set of in-kernel
> tests that I looked like followed a common pattern and reported results
> in a uniform manner.
I didn't mean to sound dismissive. I was only referring to what was
present in the actual header itself. There really isn't much there; it
provides a function which takes an expression, evaluates it,
increments a counter of all tests, and if false, prints out a warning;
also, it provides a module init which runs the user defined test
function called selftest(), and then prints the number of tests that
passed and the number of tests that failed; that's it. I was just
trying to make the point that it is pretty bare bones, and isn't
really much of a framework.
> >
> > Furthermore, kselftest test module has very few users. I checked for all
> > the tests that use it using the following grep command:
> >
> > grep -Hrn -e 'kselftest_module\.h'
> >
> > and only got three results: lib/test_strscpy.c, lib/test_printf.c, and
> > lib/test_bitmap.c.
>
> You missed many tests. I listed much more than that in the v4 thread, and
> someone else also listed more in the v4 thread.
Oh, sorry, I forgot that more were listed in the thread.
> >
> > So despite kselftest test module's existence, there really is no feature
> > overlap between kselftest and KUnit, save one: that you can use either
> > to write an in-kernel test, but this is a very small feature in
> > comparison to everything that KUnit allows you to do. KUnit is a full
> > x-unit style unit testing framework, whereas kselftest looks a lot more
> > like an end-to-end/functional testing framework, with a feature that
> > makes it possible to write in-kernel tests.
>
> The description does not give enough credit to what is in kselftest.
You are right about me missing a number of the tests, but there really
is not much infrastructure in kselftest for this at all. It really
doesn't impose any structure of any kind other than that there must be
exactly one static function named selftest() that takes no arguments;
and then you use KSTM_CHECK_ZERO() to do some checks; that's it. It
doesn't have anything else in the actual kselftest module stuff.
>
> It does not matter whether KUnit provides additional things, relative
> to kselftest. The point I was making is that there appears to be
> _some_ overlap between kselftest and KUnit, and if there is overlap
> then it is worth considering whether the overlap can be unified instead
> of duplicated.
I think I understand what you are saying, but the point I was trying
to make here is that it is so simplistic, it doesn't really
conceptually overlap since it is so limited in what structure and
features it provides. It's kind of like what Ted said previously about
how you have C so you can technically do whatever you want, but there
is nothing inherent to the kselftest test module that does any of
those things (other than what I mentioned above).
> I don't have a dog in this fight and the discussion in the v4 thread
> went way off track. Thus I am not going to get sucked back into a
> pointless debate in this thread.
Sure, I don't want to debate the point further either (I had a hard
time understanding what the point was at the end myself).
Nevertheless, I do want to make sure that I addressed this because I
think you did indeed have a point that was worth addressing, and I
don't want to waste anyone's time in the future by not addressing it.
Nevertheless, like I said, I don't want to get too detailed on the
topic otherwise like Shuah suggests later, it might end up just
leading people to draw a comparison that doesn't need to be made, but
I also don't want to misrepresent anything. In anycase, I will follow
up on this point directly with Shuah.
> Thanks for adding this section to address the issue.
No need to thank me; that is what I felt is the correct thing to do. I
didn't address the point before and it caused you and other to spend a
lot of time debating the point.
Also, it looks like Shuah is asking me to drop the section. I will
discuss this point further there.
Thanks!
> -Frank
>
>
> >
> > ### What's so special about unit testing?
> >
> > A unit test is supposed to test a single unit of code in isolation,
> > hence the name. There should be no dependencies outside the control of
> > the test; this means no external dependencies, which makes tests orders
> > of magnitudes faster. Likewise, since there are no external dependencies,
> > there are no hoops to jump through to run the tests. Additionally, this
> > makes unit tests deterministic: a failing unit test always indicates a
> > problem. Finally, because unit tests necessarily have finer granularity,
> > they are able to test all code paths easily solving the classic problem
> > of difficulty in exercising error handling code.
> >
> > ### Is KUnit trying to replace other testing frameworks for the kernel?
> >
> > No. Most existing tests for the Linux kernel are end-to-end tests, which
> > have their place. A well tested system has lots of unit tests, a
> > reasonable number of integration tests, and some end-to-end tests. KUnit
> > is just trying to address the unit test space which is currently not
> > being addressed.
> >
> > ### More information on KUnit
> >
> > There is a bunch of documentation near the end of this patch set that
> > describes how to use KUnit and best practices for writing unit tests.
> > For convenience I am hosting the compiled docs here[4].
> >
> > Additionally for convenience, I have applied these patches to a
> > branch[5]. The repo may be cloned with:
> > git clone https://kunit.googlesource.com/linux
> > This patchset is on the kunit/rfc/v5.2-rc4/v5 branch.
> >
> > ## Changes Since Last Version
> >
> > Aside from a couple public function renames, there isn't really anything
> > in here that changes any functionality.
> >
> > - Went through and fixed a couple of anti-patterns suggested by Stephen
> > Boyd. Things like:
> > - Dropping an else clause at the end of a function.
> > - Dropping the comma on the closing sentinel, `{}`, of a list.
> > - Inlines a bunch of functions in the test case running logic in patch
> > 01/18 to make it more readable as suggested by Stephen Boyd
> > - Found and fixed bug in resource deallocation logic in patch 02/18. Bug
> > was discovered as a result of making a change suggested by Stephen
> > Boyd. This does not substantially change how any of the code works
> > conceptually.
> > - Renamed new_string_stream() to alloc_string_stream() as suggested by
> > Stephen Boyd.
> > - Made string-stream a KUnit managed object - based on a suggestion made
> > by Stephen Boyd.
> > - Renamed kunit_new_stream() to alloc_kunit_stream() as suggested by
> > Stephen Boyd.
> > - Removed the ability to set log level after allocating a kunit_stream,
> > as suggested by Stephen Boyd.
> >
> > [1] https://google.github.io/kunit-docs/third_party/kernel/docs/usage.html#kunit-on-non-uml-architectures
> > [2] https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html#test-module
> > [3] https://lwn.net/Articles/790235/
> > [4] https://google.github.io/kunit-docs/third_party/kernel/docs/
> > [5] https://kunit.googlesource.com/linux/+/kunit/rfc/v5.2-rc4/v5
> >
>
^ permalink raw reply
* Re: [PATCH net-next] doc: phy: document some PHY_INTERFACE_MODE_xxx settings
From: Andrew Lunn @ 2019-06-21 20:11 UTC (permalink / raw)
To: Russell King
Cc: Florian Fainelli, Heiner Kallweit, David S. Miller,
Jonathan Corbet, netdev, linux-doc
In-Reply-To: <E1heL0P-00075z-An@rmk-PC.armlinux.org.uk>
On Fri, Jun 21, 2019 at 03:59:09PM +0100, Russell King wrote:
> There seems to be some confusion surrounding three PHY interface modes,
> specifically 1000BASE-X, 2500BASE-X and SGMII. Add some documentation
> to phylib detailing precisely what these interface modes refer to.
>
> Signed-off-by: Russell King <rmk+kernel@armlinux.org.uk>
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
Andrew
^ permalink raw reply
* Re: [PATCH v5 00/18] kunit: introduce KUnit, the Linux kernel unit testing framework
From: shuah @ 2019-06-21 19:20 UTC (permalink / raw)
To: Theodore Ts'o, Frank Rowand, Brendan Higgins, gregkh,
jpoimboe, keescook, kieran.bingham, mcgrof, peterz, robh, sboyd,
yamada.masahiro, devicetree, dri-devel, kunit-dev, linux-doc,
linux-fsdevel, linux-kbuild, linux-kernel, linux-kselftest,
linux-nvdimm, linux-um, Alexander.Levin, Tim.Bird, amir73il,
dan.carpenter, daniel, jdike, joel, julia.lawall, khilman,
knut.omang, logang, mpe, pmladek, rdunlap, richard, rientjes,
rostedt, wfg, shuah
In-Reply-To: <20190621181342.GA17166@mit.edu>
On 6/21/19 12:13 PM, Theodore Ts'o wrote:
> On Fri, Jun 21, 2019 at 08:59:48AM -0600, shuah wrote:
>>>> ### But wait! Doesn't kselftest support in kernel testing?!
>>>>
>>>> ....
>>
>> I think I commented on this before. I agree with the statement that
>> there is no overlap between Kselftest and KUnit. I would like see this
>> removed. Kselftest module support supports use-cases KUnit won't be able
>> to. I can build an kernel with Kselftest test modules and use it in the
>> filed to load and run tests if I need to debug a problem and get data
>> from a system. I can't do that with KUnit.
>>
>> In my mind, I am not viewing this as which is better. Kselftest and
>> KUnit both have their place in the kernel development process. It isn't
>> productive and/or necessary to comparing Kselftest and KUnit without a
>> good understanding of the problem spaces for each of these.
>>
>> I would strongly recommend not making reference to Kselftest and talk
>> about what KUnit offers.
>
> Shuah,
>
> Just to recall the history, this section of the FAQ was added to rebut
> the ***very*** strong statements that Frank made that there was
> overlap between Kselftest and Kunit, and that having too many ways for
> kernel developers to do the identical thing was harmful (he said it
> was too much of a burden on a kernel developer) --- and this was an
> argument for not including Kunit in the upstream kernel.
>
> If we're past that objection, then perhaps this section can be
> dropped, but there's a very good reason why it was there. I wouldn't
> Brendan to be accused of ignoring feedback from those who reviewed his
> patches. :-)
>
Agreed. I understand that this FAQ probably was needed at one time and
Brendan added it to address the concerns.
I think at some point we do need to have a document that outlines when
to KUnit and when to use Kselftest modules. I think one concern people
have is that if KUnit is perceived as a replacement for Ksefltest
module, Kselftest module will be ignored leaving users without the
ability to build and run with Kselftest modules and load them on a need
basis to gather data on a systems that aren't dedicated strictly for
testing.
I am trying to move the conversation forward from KUnit vs. Kselftest
modules discussion to which problem areas each one addresses keeping
in mind that it is not about which is better. Kselftest and KUnit both
have their place in the kernel development process. We just have to be
clear on usage as we write tests for each.
thanks,
-- Shuah
^ permalink raw reply
* Re: [PATCH v5 00/18] kunit: introduce KUnit, the Linux kernel unit testing framework
From: Theodore Ts'o @ 2019-06-21 18:13 UTC (permalink / raw)
To: shuah
Cc: Frank Rowand, Brendan Higgins, gregkh, jpoimboe, keescook,
kieran.bingham, mcgrof, peterz, robh, sboyd, yamada.masahiro,
devicetree, dri-devel, kunit-dev, linux-doc, linux-fsdevel,
linux-kbuild, linux-kernel, linux-kselftest, linux-nvdimm,
linux-um, Alexander.Levin, Tim.Bird, amir73il, dan.carpenter,
daniel, jdike, joel, julia.lawall, khilman, knut.omang, logang,
mpe, pmladek, rdunlap, richard, rientjes, rostedt, wfg
In-Reply-To: <69809117-dcda-160a-ee0a-d1d3b4c5cd8a@kernel.org>
On Fri, Jun 21, 2019 at 08:59:48AM -0600, shuah wrote:
> > > ### But wait! Doesn't kselftest support in kernel testing?!
> > >
> > > ....
>
> I think I commented on this before. I agree with the statement that
> there is no overlap between Kselftest and KUnit. I would like see this
> removed. Kselftest module support supports use-cases KUnit won't be able
> to. I can build an kernel with Kselftest test modules and use it in the
> filed to load and run tests if I need to debug a problem and get data
> from a system. I can't do that with KUnit.
>
> In my mind, I am not viewing this as which is better. Kselftest and
> KUnit both have their place in the kernel development process. It isn't
> productive and/or necessary to comparing Kselftest and KUnit without a
> good understanding of the problem spaces for each of these.
>
> I would strongly recommend not making reference to Kselftest and talk
> about what KUnit offers.
Shuah,
Just to recall the history, this section of the FAQ was added to rebut
the ***very*** strong statements that Frank made that there was
overlap between Kselftest and Kunit, and that having too many ways for
kernel developers to do the identical thing was harmful (he said it
was too much of a burden on a kernel developer) --- and this was an
argument for not including Kunit in the upstream kernel.
If we're past that objection, then perhaps this section can be
dropped, but there's a very good reason why it was there. I wouldn't
Brendan to be accused of ignoring feedback from those who reviewed his
patches. :-)
- Ted
^ permalink raw reply
* Re: [PATCH v2 00/22] Add ABI and features docs to the Kernel documentation
From: Mauro Carvalho Chehab @ 2019-06-21 18:15 UTC (permalink / raw)
To: Greg KH
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Kees Cook, Anton Vorontsov, Colin Cross,
Tony Luck
In-Reply-To: <20190621150445.GA11015@kroah.com>
Em Fri, 21 Jun 2019 17:04:45 +0200
Greg KH <greg@kroah.com> escreveu:
> On Thu, Jun 20, 2019 at 02:22:52PM -0300, Mauro Carvalho Chehab wrote:
> > This is a rebased version of the scripts with parse
> > Documentation/ABI and Documentation/feature files
> > and produce a ReST output. Those scripts are added to the
> > Kernel building system, in order to output their contents
> > inside the Kernel documentation.
> >
> > Please notice that, as discussed, I added support at get_abi.pl
> > to handle ABI files as if they're compatible with ReST. Right
> > now, this feature can't be enabled for normal builds, as it will
> > cause Sphinx crashes. After getting the offending ABI files fixed,
> > a single line change will be enough to make it default.
> >
> > a version "0" was sent back on 2017.
>
> Ok, I added the first chunk of these patches to my tree, that add the
> get_abi.pl file to the tree. I didn't touch the others that touched the
> documentation build or other scripts just yet, as I wanted to get others
> to agree with them before accepting them.
>
> Or we can just wait until after 5.3-rc1 is out and then the rest can go
> through the documentation tree.
Ok.
Whatever works best for you and Jon.
I'm keeping a tree with the remaining patches on the top of
driver-core-next at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.2
I'll rebase it on the top of yours as new patches get merged there, or if
I develop more patches related to it (I may try to fix the ReST issues with
the files at ABI/testing if I have some spare time).
Note that it contains the RFC patches for parsing ABI files as-is,
with ReST markups on them, if needed.
If you want to pick the hole thing including the RFC ones, there's one patch
there with probably needs to be either split and/or submitted to ABI file authors:
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=abi_patches_v4.2&id=58f73907d21f1c93038196c42dab65be969f4104
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH RFC 0/6] Produce ABI guide without escaping ReST source files
From: Mauro Carvalho Chehab @ 2019-06-21 15:37 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman; +Cc: linux-kernel, Jonathan Corbet
In-Reply-To: <20190621100441.183e7cd2@coco.lan>
Em Fri, 21 Jun 2019 10:04:41 -0300
Mauro Carvalho Chehab <mchehab@infradead.org> escreveu:
> Em Fri, 21 Jun 2019 09:39:15 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
>
> > Em Fri, 21 Jun 2019 09:32:00 -0300
> > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> >
> > > Hi Greg,
> > >
> > > As you proposed to give it a try on removing the escape code from the
> > > script which parses the ReST file, I changed a few things there,
> > > adding the capability of selectively enabling to output an ABI sub-dir
> > > without escaping things that would crash Sphinx.
> > >
> > > PS.: As for now this is just a RFC, I'm not getting the ABI file
> > > maintainers, copying just LKML, linux-doc ML, plus you and Jon.
> > >
> > > I also manually fixed the contents of ABI/stable, in order for it to
> > > pass without causing troubles.
> > >
> > > I added all patches from ABI and features at this branch:
> > >
> > > https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.1
> > >
> > > The html output is at https://www.infradead.org/~mchehab/rst_features/,
> > > and you can see the resulting ABI guide on:
> > >
> > > https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
> > >
> > > No Sphinx crashes/warnings happen when building it.
> > >
> > > That's my personal notes about such work:
> > >
> > > 1) Documentation/ABI/stable/sysfs-class-infiniband
> > >
> > > It had some title captions inside it, like:
> > >
> > > Errors info:
> > > -----------
> > >
> > > For one of the "What:"
> > >
> > > Sphinx is really pick with title markups. As the entire Documentation/stable is
> > > parsed as if it were a single document, there should be a coherency on what
> > > character is used to markup a level-one title. I mean, if one document uses:
> > >
> > > foo
> > > ----
> > >
> > > For the first level, all other documents should use "---...-" as well.
> > >
> > > The alternative would be to have one entry for every single file at
> > > Documentation/admin-guide/abi-*.rst, with, IMHO, it would be a lot
> > > harder to maintain.
> > >
> > > So, the best seems to let clear at ABI/README about how titles/subtitles
> > > should be used inside files, if any.
> > >
> > > 2) Some documents there use a "Values:" tag, with is not defined as a
> > > valid one at ABI/README. The script handles it as part of the description,
> > > so no harm done;
> > >
> > > 3) Among the 47 files under ABI/stable, 14 of them names the file
> > > contents, using a valid ReST markup for the document title. That is shown
> > > at the index at:
> > >
> > > https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
> > >
> > >
> > > - ABI stable symbols
> > >
> > > - sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
> > > - sysfs interface for Intel IB driver qib
> > > - sysfs interface for Intel(R) X722 iWARP i40iw driver
> > > - sysfs interface for QLogic qedr NIC Driver
> > > - sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes)
> > > - sysfs interface for Cisco VIC (usNIC) Verbs Driver
> > > - sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
> > > - sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
> > > - sysfs interface for Intel Omni-Path driver (HFI1)
> > > - sysfs interface for VMware Paravirtual RDMA driver
> > > - sysfs interface for Mellanox Connect-IB HCA driver mlx5
> > > - sysfs interface for Emulex RoCE HCA Driver
> > > - sysfs interface for Broadcom NetXtreme-E RoCE driver
> > > - sysfs interface for Mellanox IB HCA low-level driver (mthca)
> > >
> > > I liked that, but ideally all ABI files should either use it or not.
> > >
> > > 4) I was expecting to have troubles with asterisk characters inside the
> > > ABI files. That was not the case: I had to escape just one occurrence on
> > > a single file of the 47 ones inside ABI/stable.
> > >
> > > -
> > >
> > > My conclusion from this experiment is that it is worth cleaning the ABI
> > > files for them to be parsed without needing to escape non-ReST compliant
> > > parts of the ABI file.
> > >
> > > Perhaps we could keep rst-compliant the stable, obsolete and removed
> > > directories only, and gradually moving stuff from ABI/testing to ABI/stable,
> > > while fixing them to be rst-compliant.
> >
> > Btw, adding :rst: to kernel-abi markup at abi-obsolete.rst and
> > abi-removed.rst produced just two warnings:
> >
> > get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation.
> > get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1692: WARNING: Block quote ends without a blank line; unexpected unindent.
> >
> > I'll fix those too at my repository.
> >
> > I suspect, however, that Documentation/ABI/testing with its 353 files will
> > require a lot more care.
>
> Disabling the escaping logic for ABI/testing won't cause crashes with Sphinx
> 1.4.9 (it will probably cause more harm on newer versions), but will require
> a lot care, as it introduces 248 new errors/warnings:
And they come from 71 different files (list enclosed). I didn't look on them,
and I'll stop handling here for now, as I need to handle some other stuff.
Yet, manually fixing those 71 ABI files doesn't sound a too hard work. It
can probably be done on a single day.
So, I suspect we could enable :rst: and manually fix those.
Regards,
Mauro
-
Files that have issues when assuming that they're ReST friendly:
configfs-spear-pcie-gadget
configfs-usb-gadget
configfs-usb-gadget-hid
configfs-usb-gadget-rndis
configfs-usb-gadget-uac1
configfs-usb-gadget-uvc
debugfs-ec
debugfs-pktcdvd
dev-kmsg
evm
ima_policy
procfs-diskstats
sysfs-block
sysfs-block-device
sysfs-bus-acpi
sysfs-bus-event_source-devices-format
sysfs-bus-i2c-devices-pca954x
sysfs-bus-iio
sysfs-bus-iio-adc-envelope-detector
sysfs-bus-iio-cros-ec
sysfs-bus-iio-dfsdm-adc-stm32
sysfs-bus-iio-lptimer-stm32
sysfs-bus-iio-magnetometer-hmc5843
sysfs-bus-iio-temperature-max31856
sysfs-bus-iio-timer-stm32
sysfs-bus-intel_th-devices-msc
sysfs-bus-rapidio
sysfs-bus-thunderbolt
sysfs-bus-usb
sysfs-bus-usb-devices-usbsevseg
sysfs-bus-vfio-mdev
sysfs-class-cxl
sysfs-class-led
sysfs-class-mic.txt
sysfs-class-ocxl
sysfs-class-power
sysfs-class-power-twl4030
sysfs-class-rc
sysfs-class-scsi_host
sysfs-class-typec
sysfs-devices-platform-ACPI-TAD
sysfs-devices-platform-docg3
sysfs-devices-platform-sh_mobile_lcdc_fb
sysfs-devices-system-cpu
sysfs-devices-system-ibm-rtl
sysfs-driver-bd9571mwv-regulator
sysfs-driver-genwqe
sysfs-driver-hid-logitech-lg4ff
sysfs-driver-hid-wiimote
sysfs-driver-samsung-laptop
sysfs-driver-toshiba_acpi
sysfs-driver-toshiba_haps
sysfs-driver-wacom
sysfs-firmware-acpi
sysfs-firmware-dmi-entries
sysfs-firmware-gsmi
sysfs-firmware-memmap
sysfs-fs-ext4
sysfs-hypervisor-xen
sysfs-kernel-boot_params
sysfs-kernel-mm-hugepages
sysfs-platform-asus-laptop
sysfs-platform-asus-wmi
sysfs-platform-at91
sysfs-platform-eeepc-laptop
sysfs-platform-ideapad-laptop
sysfs-platform-intel-wmi-thunderbolt
sysfs-platform-sst-atom
sysfs-platform-usbip-vudc
sysfs-ptp
sysfs-uevent
Thanks,
Mauro
^ permalink raw reply
* [PATCH 0/2] Report warnings to the file they belong
From: Mauro Carvalho Chehab @ 2019-06-21 15:28 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, gregkh
Reporting an ABI error to the get_abi.pl script is not nice, as it
doesn't maky any easy to fix it.
Instead, just like with kernel-doc, put the fingers to the files
that didn't parse ok:
Documentation/ABI/testing/sysfs-kernel-mm-hugepages:3: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/ABI/testing/evm:4: ERROR: Unexpected indentation.
Documentation/ABI/testing/evm:3: WARNING: Block quote ends without a blank line; unexpected unindent.
---
Greg,
Independently of the RFC patches, I would apply those two ones
together with the script, as they make a lot easier to debug
issues.
Mauro Carvalho Chehab (2):
get_abi.pl: Allow optionally record from where a line came from
docs: kernel_abi.py: use --enable-lineno for get_abi.pl
Documentation/sphinx/kernel_abi.py | 18 ++++++++++++++----
scripts/get_abi.pl | 21 ++++++++++++++++++++-
2 files changed, 34 insertions(+), 5 deletions(-)
--
2.21.0
^ permalink raw reply
* [PATCH 2/2] docs: kernel_abi.py: use --enable-lineno for get_abi.pl
From: Mauro Carvalho Chehab @ 2019-06-21 15:28 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, gregkh
In-Reply-To: <cover.1561130657.git.mchehab+samsung@kernel.org>
Just like kernel-doc extension, we need to be able to identify
what part of an imported document has issues, as reporting them
as:
get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation.
Makes a lot harder for someone to fix.
It should be noticed that it the line which will be reported is
the line where the "What:" definition is, and not the line
with actually has an error.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernel_abi.py | 18 ++++++++++++++----
1 file changed, 14 insertions(+), 4 deletions(-)
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 88dddb8f4152..7f00f9d04a53 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -35,6 +35,7 @@ import codecs
import os
import subprocess
import sys
+import re
from os import path
@@ -93,7 +94,7 @@ class KernelCmd(Directive):
env = doc.settings.env
cwd = path.dirname(doc.current_source)
- cmd = "get_abi.pl rest --dir "
+ cmd = "get_abi.pl rest --enable-lineno --dir "
cmd += self.arguments[0]
@@ -141,7 +142,7 @@ class KernelCmd(Directive):
% (self.name, ErrorString(exc)))
return out
- def nestedParse(self, lines, fname):
+ def nestedParse(self, lines, f):
content = ViewList()
node = nodes.section()
@@ -151,8 +152,17 @@ class KernelCmd(Directive):
code_block += "\n " + l
lines = code_block + "\n\n"
- for c, l in enumerate(lines.split("\n")):
- content.append(l, fname, c)
+ line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$")
+ ln = 0
+
+ for line in lines.split("\n"):
+ match = line_regex.search(line)
+ if match:
+ f = match.group(1)
+ # sphinx counts lines from 0
+ ln = int(match.group(2)) - 1
+ else:
+ content.append(line, f, ln)
buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
--
2.21.0
^ permalink raw reply related
* [PATCH 1/2] get_abi.pl: Allow optionally record from where a line came from
From: Mauro Carvalho Chehab @ 2019-06-21 15:28 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, gregkh
In-Reply-To: <cover.1561130657.git.mchehab+samsung@kernel.org>
The get_abi.pl reads a lot of files and can join them on a
single output file. Store where each "What:" output came from,
in order to be able to optionally display it.
This is useful for the Sphinx extension, with can now be
able to blame what ABI file has issues, and on what line
the What: description with problems begin.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 21 ++++++++++++++++++++-
1 file changed, 20 insertions(+), 1 deletion(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 03f3c57af7ab..45453b7586bc 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -10,6 +10,7 @@ use Fcntl ':mode';
my $help;
my $man;
my $debug;
+my $enable_lineno;
my $prefix="Documentation/ABI";
#
@@ -19,6 +20,7 @@ my $description_is_rst = 0;
GetOptions(
"debug|d+" => \$debug,
+ "enable-lineno" => \$enable_lineno,
"rst-source!" => \$description_is_rst,
"dir=s" => \$prefix,
'help|?' => \$help,
@@ -134,6 +136,8 @@ sub parse_abi {
if ($tag ne "" && $new_tag) {
$tag = $new_tag;
+ $data{$what}->{line_no} = $ln;
+
if ($new_what) {
@{$data{$what}->{label}} = @labels if ($data{$nametag}->{what});
@labels = ();
@@ -229,6 +233,12 @@ sub output_rest {
my $file = $data{$what}->{file};
my $filepath = $data{$what}->{filepath};
+ if ($enable_lineno) {
+ printf "#define LINENO %s%s#%s\n\n",
+ $prefix, $data{$what}->{file},
+ $data{$what}->{line_no};
+ }
+
my $w = $what;
$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
@@ -377,6 +387,10 @@ sub search_symbols {
}
}
+# Ensure that the prefix will always end with a slash
+# While this is not needed for find, it makes the patch nicer
+# with --enable-lineno
+$prefix =~ s,/?$,/,;
#
# Parses all ABI files located at $prefix dir
@@ -403,7 +417,8 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book.
=head1 SYNOPSIS
-B<abi_book.pl> [--debug] [--man] [--help] --[(no-)rst-source] [--dir=<dir>] <COMAND> [<ARGUMENT>]
+B<abi_book.pl> [--debug] [--enable-lineno] [--man] [--help]
+ [--(no-)rst-source] [--dir=<dir>] <COMAND> [<ARGUMENT>]
Where <COMMAND> can be:
@@ -433,6 +448,10 @@ selecting between a rst-compliant source ABI (--rst-source), or a
plain text that may be violating ReST spec, so it requres some escaping
logic (--no-rst-source).
+=item B<--enable-lineno>
+
+Enable output of #define LINENO lines.
+
=item B<--debug>
Put the script in verbose mode, useful for debugging. Can be called multiple
--
2.21.0
^ permalink raw reply related
* Re: [PATCH v5 1/2] arm64: Define Documentation/arm64/tagged-address-abi.txt
From: Catalin Marinas @ 2019-06-21 15:16 UTC (permalink / raw)
To: Kevin Brodsky
Cc: Vincenzo Frascino, linux-arm-kernel, linux-doc, linux-mm,
linux-arch, linux-kselftest, linux-kernel, Will Deacon,
Andrey Konovalov, Alexander Viro
In-Reply-To: <1c55a610-9aa5-4675-f7de-79a1661a660d@arm.com>
On Tue, Jun 18, 2019 at 02:13:01PM +0100, Kevin Brodsky wrote:
> On 13/06/2019 16:51, Vincenzo Frascino wrote:
> > +The ARM64 Tagged Address ABI is an opt-in feature, and an application can
> > +control it using the following:
> > + - /proc/sys/abi/tagged_addr: a new sysctl interface that can be used to
> > + prevent the applications from enabling the relaxed ABI.
> > + The sysctl is meant also for testing purposes in order to provide a
> > + simple way for the userspace to verify the return error checking of
> > + the prctl() commands without having to reconfigure the kernel.
> > + The sysctl supports the following configuration options:
> > + - 0: Disable ARM64 Tagged Address ABI for all the applications.
> > + - 1 (Default): Enable ARM64 Tagged Address ABI for all the
> > + applications.
>
> I find this very confusing, because it suggests that the default value of
> PR_GET_TAGGED_ADDR_CTRL for new processes will be set to the value of this
> sysctl, when in fact this sysctl is about restricting the *availability* of
> the new ABI. Instead of disabling the ABI, I would talk about disabling
> access to the new ABI here.
This bullet point needs to be re-written. The sysctl is meant to disable
opting in to the ABI. I'd also drop the "meant for testing" part. I put
it in my commit log as justification but I don't think it should be part
of the ABI document.
> > + - prctl()s:
> > + - PR_SET_TAGGED_ADDR_CTRL: can be used to enable or disable the Tagged
> > + Address ABI.
> > + The (unsigned int) arg2 argument is a bit mask describing the
> > + control mode used:
> > + - PR_TAGGED_ADDR_ENABLE: Enable ARM64 Tagged Address ABI.
> > + The arguments arg3, arg4, and arg5 are ignored.
>
> Have we definitely decided that arg{3,4,5} are ignored? Catalin?
I don't have a strong preference either way. If it's simpler for the
user to ignore them, fine by me. I can see in the current prctl commands
a mix if ignore vs forced zero.
> > +the ABI guarantees the following behaviours:
> > +
> > + - Every current or newly introduced syscall can accept any valid tagged
> > + pointers.
> "pointer". Also, is it really useful to talk about newly introduced syscall?
> New from which point of view?
I think we should drop this guarantee. It would have made sense if we
allowed tagged pointers everywhere but we already have some exceptions.
> > +3. ARM64 Tagged Address ABI Exceptions
> > +--------------------------------------
> > +
> > +The behaviours described in section 2, with particular reference to the
> > +acceptance by the syscalls of any valid tagged pointer are not applicable
> > +to the following cases:
> > + - mmap() addr parameter.
> > + - mremap() new_address parameter.
> > + - prctl_set_mm() struct prctl_map fields.
> > + - prctl_set_mm_map() struct prctl_map fields.
>
> prctl_set_mm() and prctl_set_mm_map() are internal kernel functions, not
> syscall names. IIUC, we don't want to allow any address field settable via
> the PR_SET_MM prctl() to be tagged. Catalin, is that correct? I think this
> needs rephrasing.
I fully agree. It should talk about PR_SET_MM, PR_SET_MM_MAP,
PR_SET_MM_MAP_SIZE.
--
Catalin
^ permalink raw reply
* Re: [PATCH v2 00/22] Add ABI and features docs to the Kernel documentation
From: Greg KH @ 2019-06-21 15:04 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Kees Cook, Anton Vorontsov, Colin Cross,
Tony Luck
In-Reply-To: <cover.1561050806.git.mchehab+samsung@kernel.org>
On Thu, Jun 20, 2019 at 02:22:52PM -0300, Mauro Carvalho Chehab wrote:
> This is a rebased version of the scripts with parse
> Documentation/ABI and Documentation/feature files
> and produce a ReST output. Those scripts are added to the
> Kernel building system, in order to output their contents
> inside the Kernel documentation.
>
> Please notice that, as discussed, I added support at get_abi.pl
> to handle ABI files as if they're compatible with ReST. Right
> now, this feature can't be enabled for normal builds, as it will
> cause Sphinx crashes. After getting the offending ABI files fixed,
> a single line change will be enough to make it default.
>
> a version "0" was sent back on 2017.
Ok, I added the first chunk of these patches to my tree, that add the
get_abi.pl file to the tree. I didn't touch the others that touched the
documentation build or other scripts just yet, as I wanted to get others
to agree with them before accepting them.
Or we can just wait until after 5.3-rc1 is out and then the rest can go
through the documentation tree.
thanks,
greg k-h
^ permalink raw reply
* Re: [PATCH v5 00/18] kunit: introduce KUnit, the Linux kernel unit testing framework
From: shuah @ 2019-06-21 14:59 UTC (permalink / raw)
To: Frank Rowand, Brendan Higgins, gregkh, jpoimboe, keescook,
kieran.bingham, mcgrof, peterz, robh, sboyd, tytso,
yamada.masahiro
Cc: devicetree, dri-devel, kunit-dev, linux-doc, linux-fsdevel,
linux-kbuild, linux-kernel, linux-kselftest, linux-nvdimm,
linux-um, Alexander.Levin, Tim.Bird, amir73il, dan.carpenter,
daniel, jdike, joel, julia.lawall, khilman, knut.omang, logang,
mpe, pmladek, rdunlap, richard, rientjes, rostedt, wfg, shuah
In-Reply-To: <10feac3e-7621-65e5-fbf0-9c63fcbe09c9@gmail.com>
Hi Brendan,
On 6/19/19 7:17 PM, Frank Rowand wrote:
> Hi Brendan,
>
> I am only responding to this because you asked me to in the v4 thread.
>
> Thank you for evaluating my comments in the v4 thread and asking me to
> comment on v5
>
> On 6/17/19 1:25 AM, Brendan Higgins wrote:
>> ## TL;DR
>>
>> A not so quick follow-up to Stephen's suggestions on PATCH v4. Nothing
>> that really changes any functionality or usage with the minor exception
>> of a couple public functions that Stephen asked me to rename.
>> Nevertheless, a good deal of clean up and fixes. See changes below.
>>
>> As for our current status, right now we got Reviewed-bys on all patches
>> except:
>>
>> - [PATCH v5 08/18] objtool: add kunit_try_catch_throw to the noreturn
>> list
>>
>> However, it would probably be good to get reviews/acks from the
>> subsystem maintainers on:
>>
>> - [PATCH v5 06/18] kbuild: enable building KUnit
>> - [PATCH v5 08/18] objtool: add kunit_try_catch_throw to the noreturn
>> list
>> - [PATCH v5 15/18] Documentation: kunit: add documentation for KUnit
>> - [PATCH v5 17/18] kernel/sysctl-test: Add null pointer test for
>> sysctl.c:proc_dointvec()
>> - [PATCH v5 18/18] MAINTAINERS: add proc sysctl KUnit test to PROC
>> SYSCTL section
>>
>> Other than that, I think we should be good to go.
>>
>> One last thing, I updated the background to include my thoughts on KUnit
>> vs. in kernel testing with kselftest in the background sections as
>> suggested by Frank in the discussion on PATCH v2.
>>
>> ## Background
>>
>> This patch set proposes KUnit, a lightweight unit testing and mocking
>> framework for the Linux kernel.
>>
>> Unlike Autotest and kselftest, KUnit is a true unit testing framework;
>> it does not require installing the kernel on a test machine or in a VM
>> (however, KUnit still allows you to run tests on test machines or in VMs
>> if you want[1]) and does not require tests to be written in userspace
>> running on a host kernel. Additionally, KUnit is fast: From invocation
>> to completion KUnit can run several dozen tests in under a second.
>> Currently, the entire KUnit test suite for KUnit runs in under a second
>> from the initial invocation (build time excluded).
>>
>> KUnit is heavily inspired by JUnit, Python's unittest.mock, and
>> Googletest/Googlemock for C++. KUnit provides facilities for defining
>> unit test cases, grouping related test cases into test suites, providing
>> common infrastructure for running tests, mocking, spying, and much more.
>>
>
> I looked only at this section, as was specifically requested:
>
>> ### But wait! Doesn't kselftest support in kernel testing?!
>>
>> In a previous version of this patchset Frank pointed out that kselftest
>> already supports writing a test that resides in the kernel using the
>> test module feature[2]. LWN did a really great summary on this
>> discussion here[3].
>>
>> Kselftest has a feature that allows a test module to be loaded into a
>> kernel using the kselftest framework; this does allow someone to write
>> tests against kernel code not directly exposed to userland; however, it
>> does not provide much of a framework around how to structure the tests.
>> The kselftest test module feature just provides a header which has a
>> standardized way of reporting test failures,
>
>
>> and then provides
>> infrastructure to load and run the tests using the kselftest test
>> harness.
>
> The in-kernel tests can also be invoked at boot time if they are
> configured (Kconfig) as in-kernel instead of as modules. I did not
> check how many of the tests have tri-state configuration to allow
> this, but the few that I looked at did.
>
>>
>> The kselftest test module does not seem to be opinionated at all in
>> regards to how tests are structured, how they check for failures, how
>> tests are organized. Even in the method it provides for reporting
>> failures is pretty simple; it doesn't have any more advanced failure
>> reporting or logging features. Given what's there, I think it is fair to
>> say that it is not actually a framework, but a feature that makes it
>> possible for someone to do some checks in kernel space.
>
> I would call that description a little dismissive. The set of in-kernel
> tests that I looked like followed a common pattern and reported results
> in a uniform manner.
>
>>
I think I commented on this before. I agree with the statement that
there is no overlap between Kselftest and KUnit. I would like see this
removed. Kselftest module support supports use-cases KUnit won't be able
to. I can build an kernel with Kselftest test modules and use it in the
filed to load and run tests if I need to debug a problem and get data
from a system. I can't do that with KUnit.
In my mind, I am not viewing this as which is better. Kselftest and
KUnit both have their place in the kernel development process. It isn't
productive and/or necessary to comparing Kselftest and KUnit without a
good understanding of the problem spaces for each of these.
I would strongly recommend not making reference to Kselftest and talk
about what KUnit offers.
>> Furthermore, kselftest test module has very few users. I checked for all
>> the tests that use it using the following grep command:
>>
>> grep -Hrn -e 'kselftest_module\.h'
>>
>> and only got three results: lib/test_strscpy.c, lib/test_printf.c, and
>> lib/test_bitmap.c.
>
Again, unnecessary. KUnit can't replace Kselftest module in the way
Kselftest module support can be used for debugging and gathering
information on system that might be in active use and not dedicated
to test and development alone. I wouldn't hesitate loading a Kselftest
test module on my laptop and running tests, but I wouldn't use KUnit
the same way.
Again, this is not a competition between which is better. Kselftest
and KUnit serve different needs and problem spaces.
Please redo this documentation to reflect that.
thanks,
-- Shuah
^ permalink raw reply
* [PATCH net-next] doc: phy: document some PHY_INTERFACE_MODE_xxx settings
From: Russell King @ 2019-06-21 14:59 UTC (permalink / raw)
To: Andrew Lunn, Florian Fainelli, Heiner Kallweit
Cc: David S. Miller, Jonathan Corbet, netdev, linux-doc
There seems to be some confusion surrounding three PHY interface modes,
specifically 1000BASE-X, 2500BASE-X and SGMII. Add some documentation
to phylib detailing precisely what these interface modes refer to.
Signed-off-by: Russell King <rmk+kernel@armlinux.org.uk>
---
This is in response to recent discussion, both public and private of
recent attempts to convert some drivers to use phylink. This is to
aid understanding the differences between these three phy link modes,
specifically with respect to the "up-clocked" 2.5G variants.
The 2.5G variants are the basic 1G variants but with the serdes link
clocked 2.5 times faster; there are no bits in the control word that
identify this over the standard rates. A serdes clocked 2.5x faster
does not support the 1G/100M/10M speeds, but can only support 2.5G
and (theoretically for SGMII) 250M/25M. In practice, the PHY data
sheets I've read state that these slower speeds at the up-clocked link
speed are not supported.
It should be noted that we do not currently support 2.5G SGMII, but
we do support 2.5G BASE-X PHY interface mode.
Documentation/networking/phy.rst | 45 +++++++++++++++++++++++++++++++++++++++-
1 file changed, 44 insertions(+), 1 deletion(-)
diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst
index 0dd90d7df5ec..a689966bc4be 100644
--- a/Documentation/networking/phy.rst
+++ b/Documentation/networking/phy.rst
@@ -202,7 +202,8 @@ the PHY/controller, of which the PHY needs to be aware.
*interface* is a u32 which specifies the connection type used
between the controller and the PHY. Examples are GMII, MII,
-RGMII, and SGMII. For a full list, see include/linux/phy.h
+RGMII, and SGMII. See "PHY interface mode" below. For a full
+list, see include/linux/phy.h
Now just make sure that phydev->supported and phydev->advertising have any
values pruned from them which don't make sense for your controller (a 10/100
@@ -225,6 +226,48 @@ When you want to disconnect from the network (even if just briefly), you call
phy_stop(phydev). This function also stops the phylib state machine and
disables PHY interrupts.
+PHY interface modes
+===================
+
+The PHY interface mode supplied in the phy_connect() family of functions
+defines the initial operating mode of the PHY interface. This is not
+guaranteed to remain constant; there are PHYs which dynamically change
+their interface mode without software interaction depending on the
+negotiation results.
+
+Some of the interface modes are described below:
+
+``PHY_INTERFACE_MODE_1000BASEX``
+ This defines the 1000BASE-X single-lane serdes link as defined by the
+ 802.3 standard section 36. The link operates at a fixed bit rate of
+ 1.25Gbaud using a 10B/8B encoding scheme, resulting in an underlying
+ data rate of 1Gbps. Embedded in the data stream is a 16-bit control
+ word which is used to negotiate the duplex and pause modes with the
+ remote end. This does not include "up-clocked" variants such as 2.5Gbps
+ speeds (see below.)
+
+``PHY_INTERFACE_MODE_2500BASEX``
+ This defines a variant of 1000BASE-X which is clocked 2.5 times faster,
+ than the 802.3 standard giving a fixed bit rate of 3.125Gbaud.
+
+``PHY_INTERFACE_MODE_SGMII``
+ This is used for Cisco SGMII, which is a modification of 1000BASE-X
+ as defined by the 802.3 standard. The SGMII link consists of a single
+ serdes lane running at a fixed bit rate of 1.25Gbaud with 10B/8B
+ encoding. The underlying data rate is 1Gbps, with the slower speeds of
+ 100Mbps and 10Mbps being achieved through replication of each data symbol.
+ The 802.3 control word is re-purposed to send the negotiated speed and
+ duplex information from to the MAC, and for the MAC to acknowledge
+ receipt. This does not include "up-clocked" variants such as 2.5Gbps
+ speeds.
+
+ Note: mismatched SGMII vs 1000BASE-X configuration on a link can
+ successfully pass data in some circumstances, but the 16-bit control
+ word will not be correctly interpreted, which may cause mismatches in
+ duplex, pause or other settings. This is dependent on the MAC and/or
+ PHY behaviour.
+
+
Pause frames / flow control
===========================
--
2.7.4
^ permalink raw reply related
* Re: [PATCH 12/14] doc-rst: add ABI documentation to the admin-guide book
From: Mauro Carvalho Chehab @ 2019-06-21 14:27 UTC (permalink / raw)
To: Jani Nikula
Cc: Greg Kroah-Hartman, Linux Doc Mailing List, linux-kernel,
Jonathan Corbet
In-Reply-To: <20190619133739.44f92409@coco.lan>
Em Wed, 19 Jun 2019 13:37:39 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> Em Tue, 18 Jun 2019 11:47:32 +0300
> Jani Nikula <jani.nikula@linux.intel.com> escreveu:
>
> > On Mon, 17 Jun 2019, Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> > > Yeah, I guess it should be possible to do that. How a python script
> > > can identify if it was called by Sphinx, or if it was called directly?
> >
> > if __name__ == '__main__':
> > # run on the command-line, not imported
>
> Ok, when I have some spare time, I may try to convert one script
> to python and see how it behaves.
Did a quick test here...
Probably I'm doing something wrong (as I'm a rookie with Python), but,
in order to be able to use the same script as command line and as an Sphinx
extension, everything that it is currently there should be "escaped"
by an:
if __name__ != '__main__':
As event the class definition:
class KernelCmd(Directive):
depends on:
from docutils.parsers.rst import directives, Directive
With is only required when one needs to parse ReST - e. g. only
when the script runs as a Sphinx extension.
If this is right, as we want a script that can run by command line
to parse and search inside ABI files, at the end of the day, it will
be a lot easier to maintain if the parser script is different from the
Sphinx extension.
If so, as the Sphinx extension script will need to call a parsing script
anyway, it doesn't matter the language of the script with will be
doing the ABI file parsing.
See the enclosing file. I didn't add anything from the ABI parsing
script yet. It was just changed in order to not generate an error
when trying to run it from command line.
Thanks,
Mauro
#!/usr/bin/env python3
# coding=utf-8
# SPDX-License-Identifier: GPL-2.0
#
u"""
kernel-abi
~~~~~~~~~~
Implementation of the ``kernel-abi`` reST-directive.
:copyright: Copyright (C) 2016 Markus Heiser
:copyright: Copyright (C) 2016-2019 Mauro Carvalho Chehab
:maintained-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
: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 codecs
import os
import subprocess
import sys
from os import path
if __name__ != '__main__':
from docutils import nodes, statemachine
from docutils.statemachine import ViewList
from docutils.parsers.rst import directives, Directive
from docutils.utils.error_reporting import ErrorString
#
# 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
__version__ = '1.0'
if __name__ != '__main__':
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 = 2
has_content = False
final_argument_whitespace = True
option_spec = {
"debug" : directives.flag,
"rst" : directives.unchanged
}
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)
fname = self.arguments[0]
cmd = "get_abi.pl rest --dir "
cmd += fname
if 'rst' in self.options:
cmd += " --rst-source"
srctree = path.abspath(os.environ["srctree"])
# 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, self.arguments[0])
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
, **kwargs
)
out, err = proc.communicate()
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"
% (cmd, proc.returncode)
)
except OSError as exc:
raise self.severe(u"problems with '%s' directive: %s."
% (self.name, ErrorString(exc)))
return 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
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
^ permalink raw reply
* Re: [PATCH v2 06/29] docs: console.txt: convert docs to ReST and rename to *.rst
From: Greg Kroah-Hartman @ 2019-06-21 13:48 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Bartlomiej Zolnierkiewicz, Jiri Slaby, dri-devel,
linux-fbdev
In-Reply-To: <00ddb1bc19e07b7ce4d1e7cda457733a37cf1693.1560890800.git.mchehab+samsung@kernel.org>
On Tue, Jun 18, 2019 at 05:53:24PM -0300, Mauro Carvalho Chehab wrote:
> Convert this small file to ReST in preparation for adding it to
> the driver-api book.
>
> While this is not part of the driver-api book, mark it as
> :orphan:, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
^ permalink raw reply
* Re: [PATCH v2 09/29] docs: driver-model: convert docs to ReST and rename to *.rst
From: Greg Kroah-Hartman @ 2019-06-21 13:47 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Linus Walleij, Bartosz Golaszewski, Jean Delvare,
Guenter Roeck, Rafael J. Wysocki, Jeff Kirsher, David S. Miller,
Julia Lawall, Gilles Muller, Nicolas Palix, Michal Marek,
linux-gpio, linux-hwmon, intel-wired-lan, netdev, cocci
In-Reply-To: <0ac41c7d682452cdbd867c4ae7729b6b34d79c0b.1560890800.git.mchehab+samsung@kernel.org>
On Tue, Jun 18, 2019 at 05:53:27PM -0300, Mauro Carvalho Chehab wrote:
> Convert the various documents at the driver-model, preparing
> them to be part of the driver-api book.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Acked-by: Jeff Kirsher <jeffrey.t.kirsher@intel.com> # ice
Now applied, thanks.
greg k-h
^ permalink raw reply
* Re: [PATCH RFC 0/6] Produce ABI guide without escaping ReST source files
From: Mauro Carvalho Chehab @ 2019-06-21 13:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman; +Cc: linux-kernel, Jonathan Corbet
In-Reply-To: <20190621093915.4a466f79@coco.lan>
Em Fri, 21 Jun 2019 09:39:15 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> Em Fri, 21 Jun 2019 09:32:00 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
>
> > Hi Greg,
> >
> > As you proposed to give it a try on removing the escape code from the
> > script which parses the ReST file, I changed a few things there,
> > adding the capability of selectively enabling to output an ABI sub-dir
> > without escaping things that would crash Sphinx.
> >
> > PS.: As for now this is just a RFC, I'm not getting the ABI file
> > maintainers, copying just LKML, linux-doc ML, plus you and Jon.
> >
> > I also manually fixed the contents of ABI/stable, in order for it to
> > pass without causing troubles.
> >
> > I added all patches from ABI and features at this branch:
> >
> > https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.1
> >
> > The html output is at https://www.infradead.org/~mchehab/rst_features/,
> > and you can see the resulting ABI guide on:
> >
> > https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
> >
> > No Sphinx crashes/warnings happen when building it.
> >
> > That's my personal notes about such work:
> >
> > 1) Documentation/ABI/stable/sysfs-class-infiniband
> >
> > It had some title captions inside it, like:
> >
> > Errors info:
> > -----------
> >
> > For one of the "What:"
> >
> > Sphinx is really pick with title markups. As the entire Documentation/stable is
> > parsed as if it were a single document, there should be a coherency on what
> > character is used to markup a level-one title. I mean, if one document uses:
> >
> > foo
> > ----
> >
> > For the first level, all other documents should use "---...-" as well.
> >
> > The alternative would be to have one entry for every single file at
> > Documentation/admin-guide/abi-*.rst, with, IMHO, it would be a lot
> > harder to maintain.
> >
> > So, the best seems to let clear at ABI/README about how titles/subtitles
> > should be used inside files, if any.
> >
> > 2) Some documents there use a "Values:" tag, with is not defined as a
> > valid one at ABI/README. The script handles it as part of the description,
> > so no harm done;
> >
> > 3) Among the 47 files under ABI/stable, 14 of them names the file
> > contents, using a valid ReST markup for the document title. That is shown
> > at the index at:
> >
> > https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
> >
> >
> > - ABI stable symbols
> >
> > - sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
> > - sysfs interface for Intel IB driver qib
> > - sysfs interface for Intel(R) X722 iWARP i40iw driver
> > - sysfs interface for QLogic qedr NIC Driver
> > - sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes)
> > - sysfs interface for Cisco VIC (usNIC) Verbs Driver
> > - sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
> > - sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
> > - sysfs interface for Intel Omni-Path driver (HFI1)
> > - sysfs interface for VMware Paravirtual RDMA driver
> > - sysfs interface for Mellanox Connect-IB HCA driver mlx5
> > - sysfs interface for Emulex RoCE HCA Driver
> > - sysfs interface for Broadcom NetXtreme-E RoCE driver
> > - sysfs interface for Mellanox IB HCA low-level driver (mthca)
> >
> > I liked that, but ideally all ABI files should either use it or not.
> >
> > 4) I was expecting to have troubles with asterisk characters inside the
> > ABI files. That was not the case: I had to escape just one occurrence on
> > a single file of the 47 ones inside ABI/stable.
> >
> > -
> >
> > My conclusion from this experiment is that it is worth cleaning the ABI
> > files for them to be parsed without needing to escape non-ReST compliant
> > parts of the ABI file.
> >
> > Perhaps we could keep rst-compliant the stable, obsolete and removed
> > directories only, and gradually moving stuff from ABI/testing to ABI/stable,
> > while fixing them to be rst-compliant.
>
> Btw, adding :rst: to kernel-abi markup at abi-obsolete.rst and
> abi-removed.rst produced just two warnings:
>
> get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation.
> get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1692: WARNING: Block quote ends without a blank line; unexpected unindent.
>
> I'll fix those too at my repository.
>
> I suspect, however, that Documentation/ABI/testing with its 353 files will
> require a lot more care.
Disabling the escaping logic for ABI/testing won't cause crashes with Sphinx
1.4.9 (it will probably cause more harm on newer versions), but will require
a lot care, as it introduces 248 new errors/warnings:
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:145: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:147: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:148: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:150: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:157: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:158: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:725: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:726: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:888: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:926: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1001: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1106: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1107: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1109: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1110: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1156: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1157: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1162: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1163: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1197: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1198: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1200: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1219: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1307: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1308: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1344: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1345: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1386: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1389: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1399: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1431: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1434: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1476: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1478: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1480: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1513: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1516: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1534: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1535: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1661: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1662: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1690: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1692: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1906: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:3634: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:3784: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:3785: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:4645: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:4654: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:5358: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:5359: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:5361: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:5362: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8272: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8763: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8951: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8952: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8964: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8975: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8981: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9247: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9372: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9375: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9399: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9404: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9413: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9415: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10137: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10284: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10285: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10691: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10692: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10693: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10702: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10695: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10704: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10824: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10852: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10905: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10918: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10920: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12201: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12203: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12242: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12243: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12292: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12293: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12299: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12300: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12304: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12306: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12307: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13006: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13007: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13018: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13022: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13023: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13037: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13034: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13038: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13041: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13043: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13050: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13051: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13052: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13053: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13054: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13322: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:15110: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:17126: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:17128: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18028: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18029: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18145: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18146: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18612: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18613: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18826: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:21603: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:21605: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:21607: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:22443: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:23675: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:24253: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:24254: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:24288: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:24289: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:24290: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:25697: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:25982: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26095: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26189: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26265: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26303: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26341: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26359: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26535: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26709: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26730: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26855: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26874: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26876: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:27863: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:27864: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:27953: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:27954: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:29105: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:30263: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:31937: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:31941: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:31977: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:31981: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32005: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32007: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32031: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32054: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32058: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32108: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32110: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32136: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32158: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32160: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32204: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32206: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32231: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32254: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32276: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32280: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32306: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32330: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32393: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32394: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32400: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32498: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32518: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32668: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32660: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32660: WARNING: Inline interpreted text or phrase reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32660: WARNING: Inline interpreted text or phrase reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32698: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32699: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32771: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32774: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32902: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32903: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33035: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33038: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33043: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33043: WARNING: Inline interpreted text or phrase reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33044: WARNING: Line block ends without a blank line.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33044: WARNING: Inline interpreted text or phrase reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33045: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33478: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34128: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34132: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34208: WARNING: Inline interpreted text or phrase reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34386: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34811: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34815: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34819: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34822: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34825: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34828: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34831: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34834: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34988: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:35182: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:35538: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:35820: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:35821: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36003: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36005: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36005: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36006: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36006: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36546: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36741: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36745: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36746: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:37206: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38654: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38657: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38658: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38787: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:39407: WARNING: Title underline too short.
Example:
-------
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:39407: WARNING: Title underline too short.
Example:
-------
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:39902: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41503: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41505: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41574: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41579: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41581: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41586: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41588: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:45165: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10695: ERROR: Undefined substitution referenced: "- / | | | |_/ | | | | | | | | irq".
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:3733: ERROR: Unknown target name: "synth_arg".
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:27492: ERROR: Unknown target name: "ptp_pf".
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36117: ERROR: Unknown target name: "entry".
Thanks,
Mauro
^ 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