* 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
* Re: [PATCH RFC 0/6] Produce ABI guide without escaping ReST source files
From: Mauro Carvalho Chehab @ 2019-06-21 12:39 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
In-Reply-To: <cover.1561118631.git.mchehab+samsung@kernel.org>
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.
Thanks,
Mauro
diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst
index cda9168445a5..d095867899c5 100644
--- a/Documentation/admin-guide/abi-obsolete.rst
+++ b/Documentation/admin-guide/abi-obsolete.rst
@@ -8,3 +8,4 @@ The description of the interface will document the reason why it is
obsolete and when it can be expected to be removed.
.. kernel-abi:: $srctree/Documentation/ABI/obsolete
+ :rst:
diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst
index 497978fc9632..f7e9e43023c1 100644
--- a/Documentation/admin-guide/abi-removed.rst
+++ b/Documentation/admin-guide/abi-removed.rst
@@ -2,3 +2,4 @@ ABI removed symbols
===================
.. kernel-abi:: $srctree/Documentation/ABI/removed
+ :rst:
^ permalink raw reply related
* [PATCH RFC 1/6] get_abi.pl: fix parsing on ReST mode
From: Mauro Carvalho Chehab @ 2019-06-21 12:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561118631.git.mchehab+samsung@kernel.org>
When the source ABI file is using ReST notation, the script
should handle whitespaces and lines with care, as otherwise
the file won't be properly recognized.
Address the bugs that are on such part of the script.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 30 ++++++++++++++----------------
1 file changed, 14 insertions(+), 16 deletions(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index e2cd2234af34..03f3c57af7ab 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -159,7 +159,8 @@ sub parse_abi {
$content = $2;
}
while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- $data{$what}->{$tag} .= $content;
+
+ $data{$what}->{$tag} .= "$content\n" if ($content);
} else {
$data{$what}->{$tag} = $content;
}
@@ -174,31 +175,28 @@ sub parse_abi {
}
if ($tag eq "description") {
+ my $content = $_;
+ while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
if (!$data{$what}->{description}) {
- s/^($space)//;
- if (m/^(\s*)(.*)/) {
- my $sp = $1;
- while ($sp =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- my $content = "$sp$2";
-
- $content =~ s/^($space)//;
-
- $data{$what}->{$tag} .= "$content";
+ # Preserve initial spaces for the first line
+ if ($content =~ m/^(\s*)(.*)$/) {
+ $space = $1;
+ $content = $2;
}
+
+ $data{$what}->{$tag} .= "$content\n" if ($content);
} else {
- my $content = $_;
if (m/^\s*\n/) {
$data{$what}->{$tag} .= $content;
next;
}
- while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
$space = "" if (!($content =~ s/^($space)//));
- # Compress spaces with tabs
- $content =~ s<^ {8}> <\t>;
- $content =~ s<^ {1,7}\t> <\t>;
- $content =~ s< {1,7}\t> <\t>;
+# # Compress spaces with tabs
+# $content =~ s<^ {8}> <\t>;
+# $content =~ s<^ {1,7}\t> <\t>;
+# $content =~ s< {1,7}\t> <\t>;
$data{$what}->{$tag} .= $content;
}
next;
--
2.21.0
^ permalink raw reply related
* [PATCH RFC 6/6] docs: abi: create a 2-depth index for ABI
From: Mauro Carvalho Chehab @ 2019-06-21 12:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561118631.git.mchehab+samsung@kernel.org>
That helps to identify what ABI files are adding titles.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/abi.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/abi.rst
index 3b9645c77469..bcab3ef2597c 100644
--- a/Documentation/admin-guide/abi.rst
+++ b/Documentation/admin-guide/abi.rst
@@ -3,7 +3,7 @@ Linux ABI description
=====================
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
abi-stable
abi-testing
--
2.21.0
^ permalink raw reply related
* [PATCH RFC 5/6] docs: ABI: make it parse ABI/stable as ReST-compatible files
From: Mauro Carvalho Chehab @ 2019-06-21 12:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561118631.git.mchehab+samsung@kernel.org>
Now that the stable ABI files are compatible with ReST,
parse them without converting complex descriptions as literal
blocks nor escaping special characters.
Please notice that escaping special characters will probably
be needed at descriptions, at least for the asterisk character.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/abi-stable.rst | 1 +
Documentation/sphinx/kernel_abi.py | 9 +++++++--
2 files changed, 8 insertions(+), 2 deletions(-)
diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst
index 7495d7a35048..70490736e0d3 100644
--- a/Documentation/admin-guide/abi-stable.rst
+++ b/Documentation/admin-guide/abi-stable.rst
@@ -11,3 +11,4 @@ Most interfaces (like syscalls) are expected to never change and always
be available.
.. kernel-abi:: $srctree/Documentation/ABI/stable
+ :rst:
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 5d43cac73d0a..88dddb8f4152 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -70,12 +70,13 @@ class KernelCmd(Directive):
u"""KernelABI (``kernel-abi``) directive"""
required_arguments = 1
- optional_arguments = 0
+ optional_arguments = 2
has_content = False
final_argument_whitespace = True
option_spec = {
- "debug" : directives.flag
+ "debug" : directives.flag,
+ "rst" : directives.unchanged
}
def warn(self, message, **replace):
@@ -93,8 +94,12 @@ class KernelCmd(Directive):
env = doc.settings.env
cwd = path.dirname(doc.current_source)
cmd = "get_abi.pl rest --dir "
+
cmd += self.arguments[0]
+ if 'rst' in self.options:
+ cmd += " --rst-source"
+
srctree = path.abspath(os.environ["srctree"])
fname = cmd
--
2.21.0
^ permalink raw reply related
* [PATCH RFC 4/6] ABI: stable: make files ReST compatible
From: Mauro Carvalho Chehab @ 2019-06-21 12:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561118631.git.mchehab+samsung@kernel.org>
Several entries at the stable ABI files won't parse if we pass
them directly to the ReST output.
Adjust them, in order to allow adding their contents as-is at
the stable ABI book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/stable/firewire-cdev | 4 +
Documentation/ABI/stable/sysfs-acpi-pmprofile | 22 +++--
Documentation/ABI/stable/sysfs-bus-firewire | 3 +
Documentation/ABI/stable/sysfs-bus-nvmem | 19 ++--
Documentation/ABI/stable/sysfs-bus-usb | 6 +-
.../ABI/stable/sysfs-class-backlight | 1 +
.../ABI/stable/sysfs-class-infiniband | 97 +++++++++++++------
Documentation/ABI/stable/sysfs-class-rfkill | 13 ++-
Documentation/ABI/stable/sysfs-class-tpm | 90 ++++++++---------
Documentation/ABI/stable/sysfs-devices | 5 +-
Documentation/ABI/stable/sysfs-driver-ib_srp | 1 +
.../ABI/stable/sysfs-firmware-efi-vars | 4 +
.../ABI/stable/sysfs-firmware-opal-dump | 5 +
.../ABI/stable/sysfs-firmware-opal-elog | 2 +
Documentation/ABI/stable/sysfs-hypervisor-xen | 3 +
Documentation/ABI/stable/vdso | 5 +-
16 files changed, 180 insertions(+), 100 deletions(-)
diff --git a/Documentation/ABI/stable/firewire-cdev b/Documentation/ABI/stable/firewire-cdev
index f72ed653878a..c9e8ff026154 100644
--- a/Documentation/ABI/stable/firewire-cdev
+++ b/Documentation/ABI/stable/firewire-cdev
@@ -14,12 +14,14 @@ Description:
Each /dev/fw* is associated with one IEEE 1394 node, which can
be remote or local nodes. Operations on a /dev/fw* file have
different scope:
+
- The 1394 node which is associated with the file:
- Asynchronous request transmission
- Get the Configuration ROM
- Query node ID
- Query maximum speed of the path between this node
and local node
+
- The 1394 bus (i.e. "card") to which the node is attached to:
- Isochronous stream transmission and reception
- Asynchronous stream transmission and reception
@@ -31,6 +33,7 @@ Description:
manager
- Query cycle time
- Bus reset initiation, bus reset event reception
+
- All 1394 buses:
- Allocation of IEEE 1212 address ranges on the local
link layers, reception of inbound requests to such
@@ -43,6 +46,7 @@ Description:
userland implement different access permission models, some
operations are restricted to /dev/fw* files that are associated
with a local node:
+
- Addition of descriptors or directories to the local
nodes' Configuration ROM
- PHY packet transmission and reception
diff --git a/Documentation/ABI/stable/sysfs-acpi-pmprofile b/Documentation/ABI/stable/sysfs-acpi-pmprofile
index 964c7a8afb26..fd97d22b677f 100644
--- a/Documentation/ABI/stable/sysfs-acpi-pmprofile
+++ b/Documentation/ABI/stable/sysfs-acpi-pmprofile
@@ -6,17 +6,21 @@ Description: The ACPI pm_profile sysfs interface exports the platform
power management (and performance) requirement expectations
as provided by BIOS. The integer value is directly passed as
retrieved from the FADT ACPI table.
-Values: For possible values see ACPI specification:
+
+Values: For possible values see ACPI specification:
5.2.9 Fixed ACPI Description Table (FADT)
Field: Preferred_PM_Profile
Currently these values are defined by spec:
- 0 Unspecified
- 1 Desktop
- 2 Mobile
- 3 Workstation
- 4 Enterprise Server
- 5 SOHO Server
- 6 Appliance PC
- 7 Performance Server
+
+ == =================
+ 0 Unspecified
+ 1 Desktop
+ 2 Mobile
+ 3 Workstation
+ 4 Enterprise Server
+ 5 SOHO Server
+ 6 Appliance PC
+ 7 Performance Server
>7 Reserved
+ == =================
diff --git a/Documentation/ABI/stable/sysfs-bus-firewire b/Documentation/ABI/stable/sysfs-bus-firewire
index 41e5a0cd1e3e..9ac9eddb82ef 100644
--- a/Documentation/ABI/stable/sysfs-bus-firewire
+++ b/Documentation/ABI/stable/sysfs-bus-firewire
@@ -47,6 +47,7 @@ Description:
IEEE 1394 node device attribute.
Read-only and immutable.
Values: 1: The sysfs entry represents a local node (a controller card).
+
0: The sysfs entry represents a remote node.
@@ -125,7 +126,9 @@ Description:
Read-only attribute, immutable during the target's lifetime.
Format, as exposed by firewire-sbp2 since 2.6.22, May 2007:
Colon-separated hexadecimal string representations of
+
u64 EUI-64 : u24 directory_ID : u16 LUN
+
without 0x prefixes, without whitespace. The former sbp2 driver
(removed in 2.6.37 after being superseded by firewire-sbp2) used
a somewhat shorter format which was not as close to SAM.
diff --git a/Documentation/ABI/stable/sysfs-bus-nvmem b/Documentation/ABI/stable/sysfs-bus-nvmem
index 9ffba8576f7b..c399323f37de 100644
--- a/Documentation/ABI/stable/sysfs-bus-nvmem
+++ b/Documentation/ABI/stable/sysfs-bus-nvmem
@@ -9,13 +9,14 @@ Description:
Note: This file is only present if CONFIG_NVMEM_SYSFS
is enabled
- ex:
- hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+ ex::
- 0000000 0000 0000 0000 0000 0000 0000 0000 0000
- *
- 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
- 0000000 0000 0000 0000 0000 0000 0000 0000 0000
- ...
- *
- 0001000
+ hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ *
+ 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ ...
+ *
+ 0001000
diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb
index b832eeff9999..cad4bc232520 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -50,8 +50,10 @@ Description:
Tools can use this file and the connected_duration file to
compute the percentage of time that a device has been active.
- For example,
- echo $((100 * `cat active_duration` / `cat connected_duration`))
+ For example::
+
+ echo $((100 * `cat active_duration` / `cat connected_duration`))
+
will give an integer percentage. Note that this does not
account for counter wrap.
Users:
diff --git a/Documentation/ABI/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight
index 70302f370e7e..023fb52645f8 100644
--- a/Documentation/ABI/stable/sysfs-class-backlight
+++ b/Documentation/ABI/stable/sysfs-class-backlight
@@ -4,6 +4,7 @@ KernelVersion: 2.6.12
Contact: Richard Purdie <rpurdie@rpsys.net>
Description:
Control BACKLIGHT power, values are FB_BLANK_* from fb.h
+
- FB_BLANK_UNBLANK (0) : power on.
- FB_BLANK_POWERDOWN (4) : power off
Users: HAL
diff --git a/Documentation/ABI/stable/sysfs-class-infiniband b/Documentation/ABI/stable/sysfs-class-infiniband
index 17211ceb9bf4..f537db14d3e3 100644
--- a/Documentation/ABI/stable/sysfs-class-infiniband
+++ b/Documentation/ABI/stable/sysfs-class-infiniband
@@ -8,12 +8,14 @@ Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===========================================
node_type: (RO) Node type (CA, RNIC, usNIC, usNIC UDP,
switch or router)
node_guid: (RO) Node GUID
sys_image_guid: (RO) System image GUID
+ =============== ===========================================
What: /sys/class/infiniband/<device>/node_desc
@@ -47,6 +49,7 @@ KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===============================================
lid: (RO) Port LID
rate: (RO) Port data rate (active width * active
@@ -66,8 +69,9 @@ Description:
cap_mask: (RO) Port capability mask. 2 bits here are
settable- IsCommunicationManagementSupported
- (set when CM module is loaded) and IsSM (set via
- open of issmN file).
+ (set when CM module is loaded) and IsSM (set
+ via open of issmN file).
+ =============== ===============================================
What: /sys/class/infiniband/<device>/ports/<port-num>/link_layer
@@ -103,8 +107,7 @@ Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
- Errors info:
- -----------
+ **Errors info**:
symbol_error: (RO) Total number of minor link errors detected on
one or more physical lanes.
@@ -142,8 +145,7 @@ Description:
intervention. It can also indicate hardware issues or extremely
poor link signal integrity
- Data info:
- ---------
+ **Data info**:
port_xmit_data: (RO) Total number of data octets, divided by 4
(lanes), transmitted on all VLs. This is 64 bit counter
@@ -176,8 +178,7 @@ Description:
transmitted on all VLs from the port. This may include multicast
packets with errors.
- Misc info:
- ---------
+ **Misc info**:
port_xmit_discards: (RO) Total number of outbound packets
discarded by the port because the port is down or congested.
@@ -244,9 +245,11 @@ Description:
two umad devices and two issm devices, while a switch will have
one device of each type (for switch port 0).
+ ======= =====================================
ibdev: (RO) Show Infiniband (IB) device name
port: (RO) Display port number
+ ======= =====================================
What: /sys/class/infiniband_mad/abi_version
@@ -281,10 +284,12 @@ Date: Sept, 2005
KernelVersion: v2.6.14
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===========================================
ibdev: (RO) Display Infiniband (IB) device name
abi_version: (RO) Show ABI version of IB device specific
interfaces.
+ =============== ===========================================
What: /sys/class/infiniband_verbs/abi_version
@@ -306,12 +311,14 @@ Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ================================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host Channel Adapter type: MT23108, MT25208
(MT23108 compat mode), MT25208 or MT25204
board_id: (RO) Manufacturing board ID
+ =============== ================================================
sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
@@ -324,6 +331,7 @@ Date: Feb, 2007
KernelVersion: v2.6.21
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==============================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) HCA type. Here it is a driver short name.
@@ -331,6 +339,7 @@ Description:
driver structure (e.g. pci_driver::name).
board_id: (RO) Manufacturing board id
+ =============== ==============================================
sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
@@ -343,11 +352,13 @@ Date: Sep, 2007
KernelVersion: v2.6.24
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===============================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
board_id: (RO) Manufacturing board ID
+ =============== ===============================
What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/gids/<n>
@@ -373,6 +384,7 @@ Description:
example, ports/1/pkeys/10 contains the value at index 10 in port
1's P_Key table.
+ ======================= ==========================================
gids/<n>: (RO) The physical port gids n = 0..127
admin_guids/<n>: (RW) Allows examining or changing the
@@ -401,6 +413,7 @@ Description:
guest, whenever it uses its pkey index
1, will actually be using the real pkey
index 10.
+ ======================= ==========================================
What: /sys/class/infiniband/mlx4_X/iov/<pci-slot-num>/ports/<m>/smi_enabled
@@ -412,12 +425,14 @@ Description:
Enabling QP0 on VFs for selected VF/port. By default, no VFs are
enabled for QP0 operation.
- smi_enabled: (RO) Indicates whether smi is currently enabled
- for the indicated VF/port
+ ================= ==== ===========================================
+ smi_enabled: (RO) Indicates whether smi is currently enabled
+ for the indicated VF/port
- enable_smi_admin:(RW) Used by the admin to request that smi
- capability be enabled or disabled for the
- indicated VF/port. 0 = disable, 1 = enable.
+ enable_smi_admin: (RW) Used by the admin to request that smi
+ capability be enabled or disabled for the
+ indicated VF/port. 0 = disable, 1 = enable.
+ ================= ==== ===========================================
The requested enablement will occur at the next reset of the VF
(e.g. driver restart on the VM which owns the VF).
@@ -433,11 +448,13 @@ Date: Feb, 2008
KernelVersion: v2.6.25
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== ==================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host Channel Adapter type (NEX020)
board_id: (RO) Manufacturing board id
+ =============== ==== ==================================
sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
@@ -451,6 +468,7 @@ KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== =============================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Driver short name. Should normally match
@@ -459,6 +477,7 @@ Description:
board_id: (RO) Manufacturing board id. (Vendor + device
information)
+ =============== =============================================
sysfs interface for Intel IB driver qib
@@ -479,6 +498,7 @@ Date: May, 2010
KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ======================================================
version: (RO) Display version information of installed software
and drivers.
@@ -505,6 +525,7 @@ Description:
chip_reset: (WO) Reset the chip if possible by writing
"reset" to this file. Only allowed if no user
contexts are open that use chip resources.
+ =============== ======================================================
What: /sys/class/infiniband/qibX/ports/N/sl2vl/[0-15]
@@ -524,14 +545,16 @@ Contact: linux-rdma@vger.kernel.org
Description:
Per-port congestion control. Both are binary attributes.
- cc_table_bin: (RO) Congestion control table size followed by
+ =============== ================================================
+ cc_table_bin (RO) Congestion control table size followed by
table entries.
- cc_settings_bin:(RO) Congestion settings: port control, control
+ cc_settings_bin (RO) Congestion settings: port control, control
map and an array of 16 entries for the
congestion entries - increase, timer, event log
trigger threshold and the minimum injection rate
delay.
+ =============== ================================================
What: /sys/class/infiniband/qibX/ports/N/linkstate/loopback
What: /sys/class/infiniband/qibX/ports/N/linkstate/led_override
@@ -544,6 +567,7 @@ Contact: linux-rdma@vger.kernel.org
Description:
[to be documented]
+ =============== ===============================================
loopback: (WO)
led_override: (WO)
hrtbt_enable: (RW)
@@ -554,6 +578,7 @@ Description:
errors. Possible states are- "Initted",
"Present", "IB_link_up", "IB_configured" or
"Fatal_Hardware_Error".
+ =============== ===============================================
What: /sys/class/infiniband/qibX/ports/N/diag_counters/rc_resends
What: /sys/class/infiniband/qibX/ports/N/diag_counters/seq_naks
@@ -602,6 +627,7 @@ Contact: Christian Benvenuti <benve@cisco.com>,
linux-rdma@vger.kernel.org
Description:
+ =============== ===============================================
board_id: (RO) Manufacturing board id
config: (RO) Report the configuration for this PF
@@ -614,6 +640,7 @@ Description:
iface: (RO) Shows which network interface this usNIC
entry is associated to (visible with ifconfig).
+ =============== ===============================================
What: /sys/class/infiniband/usnic_X/qpn/summary
What: /sys/class/infiniband/usnic_X/qpn/context
@@ -658,6 +685,7 @@ Date: May, 2016
KernelVersion: v4.6
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== =============================================
hw_rev: (RO) Hardware revision number
board_id: (RO) Manufacturing board id
@@ -676,6 +704,7 @@ Description:
available.
tempsense: (RO) Thermal sense information
+ =============== =============================================
What: /sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_settings_bin
@@ -687,19 +716,21 @@ Contact: linux-rdma@vger.kernel.org
Description:
Per-port congestion control.
- cc_table_bin: (RO) CCA tables used by PSM2 Congestion control
+ =============== ================================================
+ cc_table_bin (RO) CCA tables used by PSM2 Congestion control
table size followed by table entries. Binary
attribute.
- cc_settings_bin:(RO) Congestion settings: port control, control
+ cc_settings_bin (RO) Congestion settings: port control, control
map and an array of 16 entries for the
congestion entries - increase, timer, event log
trigger threshold and the minimum injection rate
delay. Binary attribute.
- cc_prescan: (RW) enable prescanning for faster BECN
+ cc_prescan (RW) enable prescanning for faster BECN
response. Write "on" to enable and "off" to
disable.
+ =============== ================================================
What: /sys/class/infiniband/hfi1_X/ports/N/sc2vl/[0-31]
What: /sys/class/infiniband/hfi1_X/ports/N/sl2sc/[0-31]
@@ -708,11 +739,13 @@ Date: May, 2016
KernelVersion: v4.6
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===================================================
sc2vl/: (RO) 32 files (0 - 31) used to translate sl->vl
sl2sc/: (RO) 32 files (0 - 31) used to translate sl->sc
vl2mtu/: (RO) 16 files (0 - 15) used to determine MTU for vl
+ =============== ===================================================
What: /sys/class/infiniband/hfi1_X/sdma_N/cpu_list
@@ -723,26 +756,28 @@ Contact: linux-rdma@vger.kernel.org
Description:
sdma<N>/ contains one directory per sdma engine (0 - 15)
+ =============== ==============================================
cpu_list: (RW) List of cpus for user-process to sdma
engine assignment.
vl: (RO) Displays the virtual lane (vl) the sdma
engine maps to.
+ =============== ==============================================
This interface gives the user control on the affinity settings
for the device. As an example, to set an sdma engine irq
affinity and thread affinity of a user processes to use the
sdma engine, which is "near" in terms of NUMA configuration, or
- physical cpu location, the user will do:
+ physical cpu location, the user will do::
- echo "3" > /proc/irq/<N>/smp_affinity_list
- echo "4-7" > /sys/devices/.../sdma3/cpu_list
- cat /sys/devices/.../sdma3/vl
- 0
- echo "8" > /proc/irq/<M>/smp_affinity_list
- echo "9-12" > /sys/devices/.../sdma4/cpu_list
- cat /sys/devices/.../sdma4/vl
- 1
+ echo "3" > /proc/irq/<N>/smp_affinity_list
+ echo "4-7" > /sys/devices/.../sdma3/cpu_list
+ cat /sys/devices/.../sdma3/vl
+ 0
+ echo "8" > /proc/irq/<M>/smp_affinity_list
+ echo "9-12" > /sys/devices/.../sdma4/cpu_list
+ cat /sys/devices/.../sdma4/vl
+ 1
to make sure that when a process runs on cpus 4,5,6, or 7, and
uses vl=0, then sdma engine 3 is selected by the driver, and
@@ -764,11 +799,13 @@ Date: Jan, 2016
KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== ========================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Show HCA type (I40IW)
board_id: (RO) I40IW board ID
+ =============== ==== ========================
sysfs interface for QLogic qedr NIC Driver
@@ -781,9 +818,11 @@ KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== ========================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Display HCA type
+ =============== ==== ========================
sysfs interface for VMware Paravirtual RDMA driver
@@ -797,11 +836,13 @@ KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== =====================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
board_id: (RO) Display PVRDMA manufacturing board ID
+ =============== ==== =====================================
sysfs interface for Broadcom NetXtreme-E RoCE driver
@@ -813,6 +854,8 @@ Date: Feb, 2017
KernelVersion: v4.11
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== =========================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
+ =============== ==== =========================
diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
index 80151a409d67..627f160bbe51 100644
--- a/Documentation/ABI/stable/sysfs-class-rfkill
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -2,7 +2,7 @@ rfkill - radio frequency (RF) connector kill switch support
For details to this subsystem look at Documentation/rfkill.txt.
-For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in
+For the deprecated ``/sys/class/rfkill/*/claim`` knobs of this interface look in
Documentation/ABI/removed/sysfs-class-rfkill.
What: /sys/class/rfkill
@@ -36,9 +36,10 @@ KernelVersion v2.6.22
Contact: linux-wireless@vger.kernel.org
Description: Whether the soft blocked state is initialised from non-volatile
storage at startup.
-Values: A numeric value.
- 0: false
- 1: true
+Values: A numeric value:
+
+ - 0: false
+ - 1: true
What: /sys/class/rfkill/rfkill[0-9]+/state
@@ -54,6 +55,7 @@ Description: Current state of the transmitter.
through this interface. There will likely be another attempt to
remove it in the future.
Values: A numeric value.
+
0: RFKILL_STATE_SOFT_BLOCKED
transmitter is turned off by software
1: RFKILL_STATE_UNBLOCKED
@@ -69,6 +71,7 @@ KernelVersion v2.6.34
Contact: linux-wireless@vger.kernel.org
Description: Current hardblock state. This file is read only.
Values: A numeric value.
+
0: inactive
The transmitter is (potentially) active.
1: active
@@ -82,7 +85,9 @@ KernelVersion v2.6.34
Contact: linux-wireless@vger.kernel.org
Description: Current softblock state. This file is read and write.
Values: A numeric value.
+
0: inactive
The transmitter is (potentially) active.
+
1: active
The transmitter is turned off by software.
diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm
index c0e23830f56a..bbee8899a90e 100644
--- a/Documentation/ABI/stable/sysfs-class-tpm
+++ b/Documentation/ABI/stable/sysfs-class-tpm
@@ -32,11 +32,11 @@ KernelVersion: 2.6.12
Contact: tpmdd-devel@lists.sf.net
Description: The "caps" property contains TPM manufacturer and version info.
- Example output:
+ Example output::
- Manufacturer: 0x53544d20
- TCG version: 1.2
- Firmware version: 8.16
+ Manufacturer: 0x53544d20
+ TCG version: 1.2
+ Firmware version: 8.16
Manufacturer is a hex dump of the 4 byte manufacturer info
space in a TPM. TCG version shows the TCG TPM spec level that
@@ -54,9 +54,9 @@ Description: The "durations" property shows the 3 vendor-specific values
any longer than necessary before starting to poll for a
result.
- Example output:
+ Example output::
- 3015000 4508000 180995000 [original]
+ 3015000 4508000 180995000 [original]
Here the short, medium and long durations are displayed in
usecs. "[original]" indicates that the values are displayed
@@ -92,14 +92,14 @@ Description: The "pcrs" property will dump the current value of all Platform
values may be constantly changing, the output is only valid
for a snapshot in time.
- Example output:
+ Example output::
- PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- ...
+ PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ ...
The number of PCRs and hex bytes needed to represent a PCR
value will vary depending on TPM chip version. For TPM 1.1 and
@@ -119,44 +119,44 @@ Description: The "pubek" property will return the TPM's public endorsement
ated at TPM manufacture time and exists for the life of the
chip.
- Example output:
+ Example output::
- Algorithm: 00 00 00 01
- Encscheme: 00 03
- Sigscheme: 00 01
- Parameters: 00 00 08 00 00 00 00 02 00 00 00 00
- Modulus length: 256
- Modulus:
- B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C
- 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6
- 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB
- 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3
- D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B
- 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26
- 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E
- 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D
- 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0
- A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6
- 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6
- 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70
- E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A
- F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6
- F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B
- C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B
+ Algorithm: 00 00 00 01
+ Encscheme: 00 03
+ Sigscheme: 00 01
+ Parameters: 00 00 08 00 00 00 00 02 00 00 00 00
+ Modulus length: 256
+ Modulus:
+ B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C
+ 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6
+ 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB
+ 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3
+ D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B
+ 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26
+ 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E
+ 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D
+ 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0
+ A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6
+ 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6
+ 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70
+ E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A
+ F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6
+ F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B
+ C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B
- Possible values:
+ Possible values::
- Algorithm: TPM_ALG_RSA (1)
- Encscheme: TPM_ES_RSAESPKCSv15 (2)
+ Algorithm: TPM_ALG_RSA (1)
+ Encscheme: TPM_ES_RSAESPKCSv15 (2)
TPM_ES_RSAESOAEP_SHA1_MGF1 (3)
- Sigscheme: TPM_SS_NONE (1)
- Parameters, a byte string of 3 u32 values:
+ Sigscheme: TPM_SS_NONE (1)
+ Parameters, a byte string of 3 u32 values:
Key Length (bits): 00 00 08 00 (2048)
Num primes: 00 00 00 02 (2)
Exponent Size: 00 00 00 00 (0 means the
default exp)
- Modulus Length: 256 (bytes)
- Modulus: The 256 byte Endorsement Key modulus
+ Modulus Length: 256 (bytes)
+ Modulus: The 256 byte Endorsement Key modulus
What: /sys/class/tpm/tpmX/device/temp_deactivated
Date: April 2006
@@ -176,9 +176,9 @@ Description: The "timeouts" property shows the 4 vendor-specific values
timeouts is defined by the TPM interface spec that the chip
conforms to.
- Example output:
+ Example output::
- 750000 750000 750000 750000 [original]
+ 750000 750000 750000 750000 [original]
The four timeout values are shown in usecs, with a trailing
"[original]" or "[adjusted]" depending on whether the values
diff --git a/Documentation/ABI/stable/sysfs-devices b/Documentation/ABI/stable/sysfs-devices
index 4404bd9b96c1..42bf1eab5677 100644
--- a/Documentation/ABI/stable/sysfs-devices
+++ b/Documentation/ABI/stable/sysfs-devices
@@ -1,5 +1,6 @@
-# Note: This documents additional properties of any device beyond what
-# is documented in Documentation/admin-guide/sysfs-rules.rst
+Note:
+ This documents additional properties of any device beyond what
+ is documented in Documentation/admin-guide/sysfs-rules.rst
What: /sys/devices/*/of_node
Date: February 2015
diff --git a/Documentation/ABI/stable/sysfs-driver-ib_srp b/Documentation/ABI/stable/sysfs-driver-ib_srp
index 7049a2b50359..2d706b4900ce 100644
--- a/Documentation/ABI/stable/sysfs-driver-ib_srp
+++ b/Documentation/ABI/stable/sysfs-driver-ib_srp
@@ -6,6 +6,7 @@ Description: Interface for making ib_srp connect to a new target.
One can request ib_srp to connect to a new target by writing
a comma-separated list of login parameters to this sysfs
attribute. The supported parameters are:
+
* id_ext, a 16-digit hexadecimal number specifying the eight
byte identifier extension in the 16-byte SRP target port
identifier. The target port identifier is sent by ib_srp
diff --git a/Documentation/ABI/stable/sysfs-firmware-efi-vars b/Documentation/ABI/stable/sysfs-firmware-efi-vars
index 5def20b9019e..46ccd233e359 100644
--- a/Documentation/ABI/stable/sysfs-firmware-efi-vars
+++ b/Documentation/ABI/stable/sysfs-firmware-efi-vars
@@ -17,6 +17,7 @@ Description:
directory has a name of the form "<key>-<vendor guid>"
and contains the following files:
+ =============== ========================================
attributes: A read-only text file enumerating the
EFI variable flags. Potential values
include:
@@ -59,12 +60,14 @@ Description:
size: As ASCII representation of the size of
the variable's value.
+ =============== ========================================
In addition, two other magic binary files are provided
in the top-level directory and are used for adding and
removing variables:
+ =============== ========================================
new_var: Takes a "struct efi_variable" and
instructs the EFI firmware to create a
new variable.
@@ -73,3 +76,4 @@ Description:
instructs the EFI firmware to remove any
variable that has a matching vendor GUID
and variable key name.
+ =============== ========================================
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-dump b/Documentation/ABI/stable/sysfs-firmware-opal-dump
index 32fe7f5c4880..1f74f45327ba 100644
--- a/Documentation/ABI/stable/sysfs-firmware-opal-dump
+++ b/Documentation/ABI/stable/sysfs-firmware-opal-dump
@@ -7,6 +7,7 @@ Description:
This is only for the powerpc/powernv platform.
+ =============== ===============================================
initiate_dump: When '1' is written to it,
we will initiate a dump.
Read this file for supported commands.
@@ -19,8 +20,11 @@ Description:
and ID of the dump, use the id and type files.
Do not rely on any particular size of dump
type or dump id.
+ =============== ===============================================
Each dump has the following files:
+
+ =============== ===============================================
id: An ASCII representation of the dump ID
in hex (e.g. '0x01')
type: An ASCII representation of the type of
@@ -39,3 +43,4 @@ Description:
inaccessible.
Reading this file will get a list of
supported actions.
+ =============== ===============================================
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-elog b/Documentation/ABI/stable/sysfs-firmware-opal-elog
index 2536434d49d0..7c8a61a2d005 100644
--- a/Documentation/ABI/stable/sysfs-firmware-opal-elog
+++ b/Documentation/ABI/stable/sysfs-firmware-opal-elog
@@ -38,6 +38,7 @@ Description:
For each log entry (directory), there are the following
files:
+ ============== ================================================
id: An ASCII representation of the ID of the
error log, in hex - e.g. "0x01".
@@ -58,3 +59,4 @@ Description:
entry will be removed from sysfs.
Reading this file will list the supported
operations (currently just acknowledge).
+ ============== ================================================
diff --git a/Documentation/ABI/stable/sysfs-hypervisor-xen b/Documentation/ABI/stable/sysfs-hypervisor-xen
index 3cf5cdfcd9a8..748593c64568 100644
--- a/Documentation/ABI/stable/sysfs-hypervisor-xen
+++ b/Documentation/ABI/stable/sysfs-hypervisor-xen
@@ -33,6 +33,8 @@ Description: If running under Xen:
Space separated list of supported guest system types. Each type
is in the format: <class>-<major>.<minor>-<arch>
With:
+
+ ======== ============================================
<class>: "xen" -- x86: paravirtualized, arm: standard
"hvm" -- x86 only: fully virtualized
<major>: major guest interface version
@@ -43,6 +45,7 @@ Description: If running under Xen:
"x86_64": 64 bit x86 guest
"armv7l": 32 bit arm guest
"aarch64": 64 bit arm guest
+ ======== ============================================
What: /sys/hypervisor/properties/changeset
Date: March 2009
diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso
index 55406ec8a35a..73ed1240a5c0 100644
--- a/Documentation/ABI/stable/vdso
+++ b/Documentation/ABI/stable/vdso
@@ -23,6 +23,7 @@ Unless otherwise noted, the set of symbols with any given version and the
ABI of those symbols is considered stable. It may vary across architectures,
though.
-(As of this writing, this ABI documentation as been confirmed for x86_64.
+Note:
+ As of this writing, this ABI documentation as been confirmed for x86_64.
The maintainers of the other vDSO-using architectures should confirm
- that it is correct for their architecture.)
+ that it is correct for their architecture.
--
2.21.0
^ permalink raw reply related
* [PATCH RFC 0/6] Produce ABI guide without escaping ReST source files
From: Mauro Carvalho Chehab @ 2019-06-21 12:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
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.
Mauro Carvalho Chehab (6):
get_abi.pl: fix parsing on ReST mode
ABI: sysfs-driver-mlxreg-io: fix the what fields
ABI: README: specify that files should be ReST compatible
ABI: stable: make files ReST compatible
docs: ABI: make it parse ABI/stable as ReST-compatible files
docs: abi: create a 2-depth index for ABI
Documentation/ABI/README | 10 +-
Documentation/ABI/stable/firewire-cdev | 4 +
Documentation/ABI/stable/sysfs-acpi-pmprofile | 22 +++--
Documentation/ABI/stable/sysfs-bus-firewire | 3 +
Documentation/ABI/stable/sysfs-bus-nvmem | 19 ++--
Documentation/ABI/stable/sysfs-bus-usb | 6 +-
.../ABI/stable/sysfs-class-backlight | 1 +
.../ABI/stable/sysfs-class-infiniband | 97 +++++++++++++------
Documentation/ABI/stable/sysfs-class-rfkill | 13 ++-
Documentation/ABI/stable/sysfs-class-tpm | 90 ++++++++---------
Documentation/ABI/stable/sysfs-devices | 5 +-
Documentation/ABI/stable/sysfs-driver-ib_srp | 1 +
.../ABI/stable/sysfs-driver-mlxreg-io | 45 ++++-----
.../ABI/stable/sysfs-firmware-efi-vars | 4 +
.../ABI/stable/sysfs-firmware-opal-dump | 5 +
.../ABI/stable/sysfs-firmware-opal-elog | 2 +
Documentation/ABI/stable/sysfs-hypervisor-xen | 3 +
Documentation/ABI/stable/vdso | 5 +-
Documentation/admin-guide/abi-stable.rst | 1 +
Documentation/admin-guide/abi.rst | 2 +-
Documentation/sphinx/kernel_abi.py | 9 +-
scripts/get_abi.pl | 30 +++---
22 files changed, 231 insertions(+), 146 deletions(-)
--
2.21.0
^ permalink raw reply
* [PATCH RFC 2/6] ABI: sysfs-driver-mlxreg-io: fix the what fields
From: Mauro Carvalho Chehab @ 2019-06-21 12:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561118631.git.mchehab+samsung@kernel.org>
The author of this file should be given an award for creativity:
the What: fields on this file technically fulfills the description
at README. Yet, the way it is, it can't be parsed on a script,
and if someone would try to do something like:
grep hwmon*/jtag_enable
It wouldn't find anything.
Fix the What fields in a way that it can be parseable by a
script and other search tools.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../ABI/stable/sysfs-driver-mlxreg-io | 45 ++++++++-----------
1 file changed, 19 insertions(+), 26 deletions(-)
diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
index 156319fc5b80..3544968f43cc 100644
--- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io
+++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
@@ -1,5 +1,4 @@
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- asic_health
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_health
Date: June 2018
KernelVersion: 4.19
@@ -9,9 +8,8 @@ Description: This file shows ASIC health status. The possible values are:
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- cpld1_version
- cpld2_version
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_version
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_version
Date: June 2018
KernelVersion: 4.19
Contact: Vadim Pasternak <vadimpmellanox.com>
@@ -20,8 +18,7 @@ Description: These files show with which CPLD versions have been burned
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- fan_dir
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/fan_dir
Date: December 2018
KernelVersion: 5.0
@@ -32,8 +29,7 @@ Description: This file shows the system fans direction:
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- jtag_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
Date: November 2018
KernelVersion: 5.0
@@ -43,8 +39,7 @@ Description: These files show with which CPLD versions have been burned
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- jtag_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
Date: November 2018
KernelVersion: 5.0
@@ -87,16 +82,15 @@ Description: These files allow asserting system power cycling, switching
The files are write only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- reset_aux_pwr_or_ref
- reset_asic_thermal
- reset_hotswap_or_halt
- reset_hotswap_or_wd
- reset_fw_reset
- reset_long_pb
- reset_main_pwr_fail
- reset_short_pb
- reset_sw_reset
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_aux_pwr_or_ref
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_asic_thermal
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_halt
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_wd
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_fw_reset
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_long_pb
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_main_pwr_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_short_pb
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sw_reset
Date: June 2018
KernelVersion: 4.19
Contact: Vadim Pasternak <vadimpmellanox.com>
@@ -110,11 +104,10 @@ Description: These files show the system reset cause, as following: power
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- reset_comex_pwr_fail
- reset_from_comex
- reset_system
- reset_voltmon_upgrade_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_pwr_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_comex
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_system
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_voltmon_upgrade_fail
Date: November 2018
KernelVersion: 5.0
--
2.21.0
^ permalink raw reply related
* [PATCH RFC 3/6] ABI: README: specify that files should be ReST compatible
From: Mauro Carvalho Chehab @ 2019-06-21 12:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561118631.git.mchehab+samsung@kernel.org>
As we plan to remove the escaping code from the scripts/get_abi.pl,
specify at the ABI README file that the content of the file should
be ReST compatible.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/README | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
diff --git a/Documentation/ABI/README b/Documentation/ABI/README
index 3121029dce21..8bac9cb09a6d 100644
--- a/Documentation/ABI/README
+++ b/Documentation/ABI/README
@@ -32,7 +32,7 @@ The different levels of stability are:
layout of the files below for details on how to do this.)
obsolete/
- This directory documents interfaces that are still remaining in
+ This directory documents interfaces that are still remaining in
the kernel, but are marked to be removed at some later point in
time. The description of the interface will document the reason
why it is obsolete and when it can be expected to be removed.
@@ -58,6 +58,14 @@ Users: All users of this interface who wish to be notified when
be changed further.
+Note:
+ The fields should be use a simple notation, compatible with ReST markup.
+ Also, the file **should not** have a top-level index, like::
+
+ ===
+ foo
+ ===
+
How things move between levels:
Interfaces in stable may move to obsolete, as long as the proper
--
2.21.0
^ permalink raw reply related
* Re: [PATCH v2 20/29] docs: leds: convert to ReST
From: Pavel Machek @ 2019-06-21 10:59 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Vadim Pasternak, Jacek Anaszewski, Dan Murphy,
Pablo Neira Ayuso, Jozsef Kadlecsik, Florian Westphal,
David S. Miller, linux-leds, netfilter-devel, coreteam, netdev
In-Reply-To: <b8185b2d816810281a2b712c70518159516785b6.1560890801.git.mchehab+samsung@kernel.org>
[-- Attachment #1: Type: text/plain, Size: 608 bytes --]
On Tue 2019-06-18 17:53:38, Mauro Carvalho Chehab wrote:
> Rename the leds 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: Pavel Machek <pavel@ucw.cz>
--
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 181 bytes --]
^ permalink raw reply
* Re: [PATCH] ABI: sysfs-driver-mlxreg-io: fix the what fields
From: Andy Shevchenko @ 2019-06-21 10:33 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Greg Kroah-Hartman, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Darren Hart (VMware),
Vadim Pasternak
In-Reply-To: <4cd2ece080041d8545cc2f3e86cb1ff7c8a91f5b.1561110859.git.mchehab+samsung@kernel.org>
On Fri, Jun 21, 2019 at 12:54 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> The author of this file should be given an award for creativity:
> the What: fields on this file technically fulfills the description
> at README. Yet, the way it is, it can't be parsed on a script,
> and if someone would try to do something like:
>
> grep hwmon*/jtag_enable
>
> It wouldn't find anything.
>
> Fix the What fields in a way that it can be parseable by a
> script and other search tools.
>
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Thanks, Mauro, for fixing this.
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> .../ABI/stable/sysfs-driver-mlxreg-io | 45 ++++++++-----------
> 1 file changed, 19 insertions(+), 26 deletions(-)
>
> diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
> index 156319fc5b80..3544968f43cc 100644
> --- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io
> +++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
> @@ -1,5 +1,4 @@
> -What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
> - asic_health
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_health
>
> Date: June 2018
> KernelVersion: 4.19
> @@ -9,9 +8,8 @@ Description: This file shows ASIC health status. The possible values are:
>
> The files are read only.
>
> -What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
> - cpld1_version
> - cpld2_version
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_version
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_version
> Date: June 2018
> KernelVersion: 4.19
> Contact: Vadim Pasternak <vadimpmellanox.com>
> @@ -20,8 +18,7 @@ Description: These files show with which CPLD versions have been burned
>
> The files are read only.
>
> -What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
> - fan_dir
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/fan_dir
>
> Date: December 2018
> KernelVersion: 5.0
> @@ -32,8 +29,7 @@ Description: This file shows the system fans direction:
>
> The files are read only.
>
> -What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
> - jtag_enable
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
>
> Date: November 2018
> KernelVersion: 5.0
> @@ -43,8 +39,7 @@ Description: These files show with which CPLD versions have been burned
>
> The files are read only.
>
> -What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
> - jtag_enable
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
>
> Date: November 2018
> KernelVersion: 5.0
> @@ -87,16 +82,15 @@ Description: These files allow asserting system power cycling, switching
>
> The files are write only.
>
> -What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
> - reset_aux_pwr_or_ref
> - reset_asic_thermal
> - reset_hotswap_or_halt
> - reset_hotswap_or_wd
> - reset_fw_reset
> - reset_long_pb
> - reset_main_pwr_fail
> - reset_short_pb
> - reset_sw_reset
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_aux_pwr_or_ref
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_asic_thermal
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_halt
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_wd
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_fw_reset
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_long_pb
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_main_pwr_fail
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_short_pb
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sw_reset
> Date: June 2018
> KernelVersion: 4.19
> Contact: Vadim Pasternak <vadimpmellanox.com>
> @@ -110,11 +104,10 @@ Description: These files show the system reset cause, as following: power
>
> The files are read only.
>
> -What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
> - reset_comex_pwr_fail
> - reset_from_comex
> - reset_system
> - reset_voltmon_upgrade_fail
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_pwr_fail
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_comex
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_system
> +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_voltmon_upgrade_fail
>
> Date: November 2018
> KernelVersion: 5.0
> --
> 2.21.0
>
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* [PATCH] ABI: sysfs-driver-mlxreg-io: fix the what fields
From: Mauro Carvalho Chehab @ 2019-06-21 9:54 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Darren Hart (VMware), Vadim Pasternak,
Andy Shevchenko
The author of this file should be given an award for creativity:
the What: fields on this file technically fulfills the description
at README. Yet, the way it is, it can't be parsed on a script,
and if someone would try to do something like:
grep hwmon*/jtag_enable
It wouldn't find anything.
Fix the What fields in a way that it can be parseable by a
script and other search tools.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../ABI/stable/sysfs-driver-mlxreg-io | 45 ++++++++-----------
1 file changed, 19 insertions(+), 26 deletions(-)
diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
index 156319fc5b80..3544968f43cc 100644
--- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io
+++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
@@ -1,5 +1,4 @@
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- asic_health
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_health
Date: June 2018
KernelVersion: 4.19
@@ -9,9 +8,8 @@ Description: This file shows ASIC health status. The possible values are:
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- cpld1_version
- cpld2_version
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_version
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_version
Date: June 2018
KernelVersion: 4.19
Contact: Vadim Pasternak <vadimpmellanox.com>
@@ -20,8 +18,7 @@ Description: These files show with which CPLD versions have been burned
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- fan_dir
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/fan_dir
Date: December 2018
KernelVersion: 5.0
@@ -32,8 +29,7 @@ Description: This file shows the system fans direction:
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- jtag_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
Date: November 2018
KernelVersion: 5.0
@@ -43,8 +39,7 @@ Description: These files show with which CPLD versions have been burned
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- jtag_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
Date: November 2018
KernelVersion: 5.0
@@ -87,16 +82,15 @@ Description: These files allow asserting system power cycling, switching
The files are write only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- reset_aux_pwr_or_ref
- reset_asic_thermal
- reset_hotswap_or_halt
- reset_hotswap_or_wd
- reset_fw_reset
- reset_long_pb
- reset_main_pwr_fail
- reset_short_pb
- reset_sw_reset
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_aux_pwr_or_ref
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_asic_thermal
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_halt
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_wd
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_fw_reset
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_long_pb
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_main_pwr_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_short_pb
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sw_reset
Date: June 2018
KernelVersion: 4.19
Contact: Vadim Pasternak <vadimpmellanox.com>
@@ -110,11 +104,10 @@ Description: These files show the system reset cause, as following: power
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- reset_comex_pwr_fail
- reset_from_comex
- reset_system
- reset_voltmon_upgrade_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_pwr_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_comex
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_system
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_voltmon_upgrade_fail
Date: November 2018
KernelVersion: 5.0
--
2.21.0
^ permalink raw reply related
* Re: [PATCH 04/14] ABI: better identificate tables
From: Mauro Carvalho Chehab @ 2019-06-21 9:49 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Johan Hovold, Linux Doc Mailing List, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Stefan Achatz
In-Reply-To: <20190621072152.GA21300@kroah.com>
Em Fri, 21 Jun 2019 09:21:52 +0200
Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
> On Thu, Jun 20, 2019 at 11:27:49AM -0300, Mauro Carvalho Chehab wrote:
> > Em Wed, 19 Jun 2019 13:14:08 -0300
> > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> >
> > > Em Wed, 19 Jun 2019 17:02:07 +0200
> > > Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
> > >
> > > > On Wed, Jun 19, 2019 at 10:56:33AM -0300, Mauro Carvalho Chehab wrote:
> > > > > Hi Johan,
> > > > >
> > > > > Em Wed, 19 Jun 2019 14:51:35 +0200
> > > > > Johan Hovold <johan@kernel.org> escreveu:
> > > > >
> > > > > > On Thu, Jun 13, 2019 at 11:04:10PM -0300, Mauro Carvalho Chehab wrote:
> > > > > > > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > > > > >
> > > > > > > When parsing via script, it is important to know if the script
> > > > > > > should consider a description as a literal block that should
> > > > > > > be displayed as-is, or if the description can be considered
> > > > > > > as a normal text.
> > > > > > >
> > > > > > > Change descriptions to ensure that the preceding line of a table
> > > > > > > ends with a colon. That makes easy to identify the need of a
> > > > > > > literal block.
> > > > > >
> > > > > > In the cover letter you say that the first four patches of this series,
> > > > > > including this one, "fix some ABI descriptions that are violating the
> > > > > > syntax described at Documentation/ABI/README". This seems a bit harsh,
> > > > > > given that it's you that is now *introducing* a new syntax requirement
> > > > > > to assist your script.
> > > > >
> > > > > Yeah, what's there at the cover letter doesn't apply to this specific
> > > > > patch. The thing is that I wrote this series a lot of time ago (2016/17).
> > > > >
> > > > > I revived those per a request at KS ML, as we still need to expose the
> > > > > ABI content on some book that will be used by userspace people.
> > > > >
> > > > > So, I just rebased it on the top of curent Kernel, add a cover letter
> > > > > with the things I remembered and re-sent.
> > > > >
> > > > > In the specific case of this patch, the ":" there actually makes sense
> > > > > for someone that it is reading it as a text file, and it is an easy
> > > > > hack to make it parse better.
> > > > >
> > > > > > Specifically, this new requirement isn't documented anywhere AFAICT, so
> > > > > > how will anyone adding new ABI descriptions learn about it?
> > > > >
> > > > > Yeah, either that or provide an alternative to "Description" tag, to be
> > > > > used with more complex ABI descriptions.
> > > > >
> > > > > One of the things that occurred to me, back on 2017, is that we should
> > > > > have a way to to specify that an specific ABI description would have
> > > > > a rich format. Something like:
> > > > >
> > > > > What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_cpi
> > > > > Date: August 2010
> > > > > Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
> > > > > RST-Description:
> > > > > It is possible to switch the cpi setting of the mouse with the
> > > > > press of a button.
> > > > > When read, this file returns the raw number of the actual cpi
> > > > > setting reported by the mouse. This number has to be further
> > > > > processed to receive the real dpi value:
> > > > >
> > > > > ===== =====
> > > > > VALUE DPI
> > > > > ===== =====
> > > > > 1 400
> > > > > 2 800
> > > > > 4 1600
> > > > > ===== =====
> > > > >
> > > > > With that, the script will know that the description contents will be using
> > > > > the ReST markup, and parse it accordingly. Right now, what it does, instead,
> > > > > is to place the description on a code-block, e. g. it will produce this
> > > > > output for the description:
> > > > >
> > > > > ::
> > > > >
> > > > > It is possible to switch the cpi setting of the mouse with the
> > > > > press of a button.
> > > > > When read, this file returns the raw number of the actual cpi
> > > > > setting reported by the mouse. This number has to be further
> > > > > processed to receive the real dpi value:
> > > > >
> > > > > VALUE DPI
> > > > > 1 400
> > > > > 2 800
> > > > > 4 1600
> > > > >
> > > > >
> > > > > Greg,
> > > > >
> > > > > what do you think?
> > > >
> > > > I don't know when "Description" and "RST-Description" would be used.
> > > > Why not just parse "Description" like rst text and if things are "messy"
> > > > we fix them up as found, like you did with the ":" here? It doesn't
> > > > have to be complex, we can always fix them up after-the-fact if new
> > > > stuff gets added that doesn't quite parse properly.
> > > >
> > > > Just like we do for most kernel-doc formatting :)
> > >
> > > Works for me. Yet, I guess I tried that, back on 2017.
> > >
> > > If I'm not mistaken, the initial patchset to solve the broken things
> > > won't be small, and will be require a lot of attention in order to
> > > identify what's broken and where.
> > >
> > > Btw, one thing is to pass at ReST validation. Another thing is to
> > > produce something that people can read.
> > >
> > > Right now, the pertinent logic at the script I wrote (scripts/get_abi.pl)
> > > is here:
> > >
> > > if (!($desc =~ /^\s*$/)) {
> > > if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
> > > # put everything inside a code block
> > > $desc =~ s/\n/\n /g;
> > >
> > > print "::\n\n";
> > > print " $desc\n\n";
> > > } else {
> > > # Escape any special chars from description
> > > $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
> > >
> > > print "$desc\n\n";
> > > }
> > > }
> > >
> > > If it discovers something weird enough, it just places everything
> > > into a comment block. Otherwise, it assumes that it is a plain
> > > text and that any special characters should be escaped.
> > >
> > > If the above block is replaced by a simple:
> > >
> > > print "$desc\n\n";
> > >
> > > The description content will be handled as a ReST file.
> > >
> > > I don't have any time right now to do this change and to handle the
> > > warnings that will start to popup.
> > >
> > > Btw, a single replace there is enough to show the amount of problems that
> > > it will rise, as it will basically break Sphinx build with:
> > >
> > > reading sources... [ 1%] admin-guide/abi-testing
> > > reST markup error:
> > > get_abi.pl rest --dir $srctree/Documentation/ABI/testing:45261: (SEVERE/4) Missing matching underline for section title overline.
> > >
> > > ==========================
> > > PCIe Device AER statistics
> > > These attributes show up under all the devices that are AER capable. These
> >
> > To be clear here: the problem with the above is that ReST has zero
> > tolerance and actually behaves like a crash, if it receives something like:
> >
> > ==========================
> > PCIe Device AER statistics
> > ==========================
> >
> > For it to work, it has to have zero spaces before ===..=== line, e. g.:
> >
> > ==========================
> > PCIe Device AER statistics
> > ==========================
> >
> > Ok, maybe we could try to teach the parser a way to identify the initial
> > spacing of the first description line and remove that amount of
> > spaces/tabs for the following lines, but it may require some heuristics.
>
> Or we can clean this type of thing up by hand :)
>
> Let's see how bad this gets, the documentation in these files should not
> be very complex as they _should_ only be one-value-per-file, but as you
> have shown in this very example, that rule is violated :(
Hi Greg,
Doing a manual review - still incomplete (just stable/ dir) - and I didn't
try to run the script over ABI file yet - this is what I found so
far[1]: 17 files over 37 needed adjustments (45%).
That trick of detecting a complex file when it finds a ':' and parse the
hole description as a literal block solves most of them.
From the changes below, this file:
Documentation/ABI/stable/sysfs-driver-mlxreg-io
Found a "creative way" to place the "What:" field avoiding long lines...
At least this one should be fixed, as the parser won't handle its
content right (it won't complain, but the result output will be wrong).
[1] I also added a note at README that files should be ReST-compatible
diff --git a/Documentation/ABI/README b/Documentation/ABI/README
index 3121029dce21..8bac9cb09a6d 100644
--- a/Documentation/ABI/README
+++ b/Documentation/ABI/README
@@ -32,7 +32,7 @@ The different levels of stability are:
layout of the files below for details on how to do this.)
obsolete/
- This directory documents interfaces that are still remaining in
+ This directory documents interfaces that are still remaining in
the kernel, but are marked to be removed at some later point in
time. The description of the interface will document the reason
why it is obsolete and when it can be expected to be removed.
@@ -58,6 +58,14 @@ Users: All users of this interface who wish to be notified when
be changed further.
+Note:
+ The fields should be use a simple notation, compatible with ReST markup.
+ Also, the file **should not** have a top-level index, like::
+
+ ===
+ foo
+ ===
+
How things move between levels:
Interfaces in stable may move to obsolete, as long as the proper
diff --git a/Documentation/ABI/stable/firewire-cdev b/Documentation/ABI/stable/firewire-cdev
index f72ed653878a..d8df3004c318 100644
--- a/Documentation/ABI/stable/firewire-cdev
+++ b/Documentation/ABI/stable/firewire-cdev
@@ -20,6 +20,7 @@ Description:
- Query node ID
- Query maximum speed of the path between this node
and local node
+
- The 1394 bus (i.e. "card") to which the node is attached to:
- Isochronous stream transmission and reception
- Asynchronous stream transmission and reception
@@ -31,6 +32,7 @@ Description:
manager
- Query cycle time
- Bus reset initiation, bus reset event reception
+
- All 1394 buses:
- Allocation of IEEE 1212 address ranges on the local
link layers, reception of inbound requests to such
diff --git a/Documentation/ABI/stable/sysfs-acpi-pmprofile b/Documentation/ABI/stable/sysfs-acpi-pmprofile
index 964c7a8afb26..3b0e34eef83c 100644
--- a/Documentation/ABI/stable/sysfs-acpi-pmprofile
+++ b/Documentation/ABI/stable/sysfs-acpi-pmprofile
@@ -11,12 +11,15 @@ Values: For possible values see ACPI specification:
Field: Preferred_PM_Profile
Currently these values are defined by spec:
- 0 Unspecified
- 1 Desktop
- 2 Mobile
- 3 Workstation
- 4 Enterprise Server
- 5 SOHO Server
- 6 Appliance PC
- 7 Performance Server
+
+ == =================
+ 0 Unspecified
+ 1 Desktop
+ 2 Mobile
+ 3 Workstation
+ 4 Enterprise Server
+ 5 SOHO Server
+ 6 Appliance PC
+ 7 Performance Server
>7 Reserved
+ == =================
diff --git a/Documentation/ABI/stable/sysfs-bus-firewire b/Documentation/ABI/stable/sysfs-bus-firewire
index 41e5a0cd1e3e..0c8c023855b6 100644
--- a/Documentation/ABI/stable/sysfs-bus-firewire
+++ b/Documentation/ABI/stable/sysfs-bus-firewire
@@ -125,7 +125,9 @@ Description:
Read-only attribute, immutable during the target's lifetime.
Format, as exposed by firewire-sbp2 since 2.6.22, May 2007:
Colon-separated hexadecimal string representations of
+
u64 EUI-64 : u24 directory_ID : u16 LUN
+
without 0x prefixes, without whitespace. The former sbp2 driver
(removed in 2.6.37 after being superseded by firewire-sbp2) used
a somewhat shorter format which was not as close to SAM.
diff --git a/Documentation/ABI/stable/sysfs-bus-nvmem b/Documentation/ABI/stable/sysfs-bus-nvmem
index 9ffba8576f7b..c399323f37de 100644
--- a/Documentation/ABI/stable/sysfs-bus-nvmem
+++ b/Documentation/ABI/stable/sysfs-bus-nvmem
@@ -9,13 +9,14 @@ Description:
Note: This file is only present if CONFIG_NVMEM_SYSFS
is enabled
- ex:
- hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+ ex::
- 0000000 0000 0000 0000 0000 0000 0000 0000 0000
- *
- 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
- 0000000 0000 0000 0000 0000 0000 0000 0000 0000
- ...
- *
- 0001000
+ hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ *
+ 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ ...
+ *
+ 0001000
diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb
index b832eeff9999..cad4bc232520 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -50,8 +50,10 @@ Description:
Tools can use this file and the connected_duration file to
compute the percentage of time that a device has been active.
- For example,
- echo $((100 * `cat active_duration` / `cat connected_duration`))
+ For example::
+
+ echo $((100 * `cat active_duration` / `cat connected_duration`))
+
will give an integer percentage. Note that this does not
account for counter wrap.
Users:
diff --git a/Documentation/ABI/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight
index 70302f370e7e..023fb52645f8 100644
--- a/Documentation/ABI/stable/sysfs-class-backlight
+++ b/Documentation/ABI/stable/sysfs-class-backlight
@@ -4,6 +4,7 @@ KernelVersion: 2.6.12
Contact: Richard Purdie <rpurdie@rpsys.net>
Description:
Control BACKLIGHT power, values are FB_BLANK_* from fb.h
+
- FB_BLANK_UNBLANK (0) : power on.
- FB_BLANK_POWERDOWN (4) : power off
Users: HAL
diff --git a/Documentation/ABI/stable/sysfs-class-infiniband b/Documentation/ABI/stable/sysfs-class-infiniband
index 17211ceb9bf4..3f58952a8ccb 100644
--- a/Documentation/ABI/stable/sysfs-class-infiniband
+++ b/Documentation/ABI/stable/sysfs-class-infiniband
@@ -8,12 +8,14 @@ Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===========================================
node_type: (RO) Node type (CA, RNIC, usNIC, usNIC UDP,
switch or router)
node_guid: (RO) Node GUID
sys_image_guid: (RO) System image GUID
+ =============== ===========================================
What: /sys/class/infiniband/<device>/node_desc
@@ -47,6 +49,7 @@ KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===============================================
lid: (RO) Port LID
rate: (RO) Port data rate (active width * active
@@ -66,8 +69,9 @@ Description:
cap_mask: (RO) Port capability mask. 2 bits here are
settable- IsCommunicationManagementSupported
- (set when CM module is loaded) and IsSM (set via
- open of issmN file).
+ (set when CM module is loaded) and IsSM (set
+ via open of issmN file).
+ =============== ===============================================
What: /sys/class/infiniband/<device>/ports/<port-num>/link_layer
@@ -143,7 +147,7 @@ Description:
poor link signal integrity
Data info:
- ---------
+ ----------
port_xmit_data: (RO) Total number of data octets, divided by 4
(lanes), transmitted on all VLs. This is 64 bit counter
@@ -177,7 +181,7 @@ Description:
packets with errors.
Misc info:
- ---------
+ ----------
port_xmit_discards: (RO) Total number of outbound packets
discarded by the port because the port is down or congested.
@@ -244,9 +248,11 @@ Description:
two umad devices and two issm devices, while a switch will have
one device of each type (for switch port 0).
+ ======= =====================================
ibdev: (RO) Show Infiniband (IB) device name
port: (RO) Display port number
+ ======= =====================================
What: /sys/class/infiniband_mad/abi_version
@@ -281,10 +287,12 @@ Date: Sept, 2005
KernelVersion: v2.6.14
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===========================================
ibdev: (RO) Display Infiniband (IB) device name
abi_version: (RO) Show ABI version of IB device specific
interfaces.
+ =============== ===========================================
What: /sys/class/infiniband_verbs/abi_version
@@ -306,12 +314,14 @@ Date: Apr, 2005
KernelVersion: v2.6.12
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ================================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host Channel Adapter type: MT23108, MT25208
(MT23108 compat mode), MT25208 or MT25204
board_id: (RO) Manufacturing board ID
+ =============== ================================================
sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
@@ -324,6 +334,7 @@ Date: Feb, 2007
KernelVersion: v2.6.21
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==============================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) HCA type. Here it is a driver short name.
@@ -331,6 +342,7 @@ Description:
driver structure (e.g. pci_driver::name).
board_id: (RO) Manufacturing board id
+ =============== ==============================================
sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
@@ -343,11 +355,13 @@ Date: Sep, 2007
KernelVersion: v2.6.24
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===============================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
board_id: (RO) Manufacturing board ID
+ =============== ===============================
What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/gids/<n>
@@ -373,6 +387,7 @@ Description:
example, ports/1/pkeys/10 contains the value at index 10 in port
1's P_Key table.
+ ======================= ==========================================
gids/<n>: (RO) The physical port gids n = 0..127
admin_guids/<n>: (RW) Allows examining or changing the
@@ -401,6 +416,7 @@ Description:
guest, whenever it uses its pkey index
1, will actually be using the real pkey
index 10.
+ ======================= ==========================================
What: /sys/class/infiniband/mlx4_X/iov/<pci-slot-num>/ports/<m>/smi_enabled
@@ -412,12 +428,14 @@ Description:
Enabling QP0 on VFs for selected VF/port. By default, no VFs are
enabled for QP0 operation.
- smi_enabled: (RO) Indicates whether smi is currently enabled
- for the indicated VF/port
+ ================= ==== ===========================================
+ smi_enabled: (RO) Indicates whether smi is currently enabled
+ for the indicated VF/port
- enable_smi_admin:(RW) Used by the admin to request that smi
- capability be enabled or disabled for the
- indicated VF/port. 0 = disable, 1 = enable.
+ enable_smi_admin: (RW) Used by the admin to request that smi
+ capability be enabled or disabled for the
+ indicated VF/port. 0 = disable, 1 = enable.
+ ================= ==== ===========================================
The requested enablement will occur at the next reset of the VF
(e.g. driver restart on the VM which owns the VF).
@@ -433,11 +451,13 @@ Date: Feb, 2008
KernelVersion: v2.6.25
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== ==================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host Channel Adapter type (NEX020)
board_id: (RO) Manufacturing board id
+ =============== ==== ==================================
sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
@@ -451,6 +471,7 @@ KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== =============================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Driver short name. Should normally match
@@ -459,6 +480,7 @@ Description:
board_id: (RO) Manufacturing board id. (Vendor + device
information)
+ =============== =============================================
sysfs interface for Intel IB driver qib
@@ -479,6 +501,7 @@ Date: May, 2010
KernelVersion: v2.6.35
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ======================================================
version: (RO) Display version information of installed software
and drivers.
@@ -505,6 +528,7 @@ Description:
chip_reset: (WO) Reset the chip if possible by writing
"reset" to this file. Only allowed if no user
contexts are open that use chip resources.
+ =============== ======================================================
What: /sys/class/infiniband/qibX/ports/N/sl2vl/[0-15]
@@ -524,6 +548,7 @@ Contact: linux-rdma@vger.kernel.org
Description:
Per-port congestion control. Both are binary attributes.
+ =============== ================================================
cc_table_bin: (RO) Congestion control table size followed by
table entries.
@@ -532,6 +557,7 @@ Description:
congestion entries - increase, timer, event log
trigger threshold and the minimum injection rate
delay.
+ =============== ================================================
What: /sys/class/infiniband/qibX/ports/N/linkstate/loopback
What: /sys/class/infiniband/qibX/ports/N/linkstate/led_override
@@ -544,6 +570,7 @@ Contact: linux-rdma@vger.kernel.org
Description:
[to be documented]
+ =============== ===============================================
loopback: (WO)
led_override: (WO)
hrtbt_enable: (RW)
@@ -554,6 +581,7 @@ Description:
errors. Possible states are- "Initted",
"Present", "IB_link_up", "IB_configured" or
"Fatal_Hardware_Error".
+ =============== ===============================================
What: /sys/class/infiniband/qibX/ports/N/diag_counters/rc_resends
What: /sys/class/infiniband/qibX/ports/N/diag_counters/seq_naks
@@ -602,6 +630,7 @@ Contact: Christian Benvenuti <benve@cisco.com>,
linux-rdma@vger.kernel.org
Description:
+ =============== ===============================================
board_id: (RO) Manufacturing board id
config: (RO) Report the configuration for this PF
@@ -614,6 +643,7 @@ Description:
iface: (RO) Shows which network interface this usNIC
entry is associated to (visible with ifconfig).
+ =============== ===============================================
What: /sys/class/infiniband/usnic_X/qpn/summary
What: /sys/class/infiniband/usnic_X/qpn/context
@@ -658,6 +688,7 @@ Date: May, 2016
KernelVersion: v4.6
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== ========================================
hw_rev: (RO) Hardware revision number
board_id: (RO) Manufacturing board id
@@ -676,6 +707,7 @@ Description:
available.
tempsense: (RO) Thermal sense information
+ =============== ==== ========================================
What: /sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_settings_bin
@@ -687,19 +719,21 @@ Contact: linux-rdma@vger.kernel.org
Description:
Per-port congestion control.
- cc_table_bin: (RO) CCA tables used by PSM2 Congestion control
+ =============== ================================================
+ cc_table_bin (RO) CCA tables used by PSM2 Congestion control
table size followed by table entries. Binary
attribute.
- cc_settings_bin:(RO) Congestion settings: port control, control
+ cc_settings_bin (RO) Congestion settings: port control, control
map and an array of 16 entries for the
congestion entries - increase, timer, event log
trigger threshold and the minimum injection rate
delay. Binary attribute.
- cc_prescan: (RW) enable prescanning for faster BECN
+ cc_prescan (RW) enable prescanning for faster BECN
response. Write "on" to enable and "off" to
disable.
+ =============== ================================================
What: /sys/class/infiniband/hfi1_X/ports/N/sc2vl/[0-31]
What: /sys/class/infiniband/hfi1_X/ports/N/sl2sc/[0-31]
@@ -708,11 +742,13 @@ Date: May, 2016
KernelVersion: v4.6
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ===================================================
sc2vl/: (RO) 32 files (0 - 31) used to translate sl->vl
sl2sc/: (RO) 32 files (0 - 31) used to translate sl->sc
vl2mtu/: (RO) 16 files (0 - 15) used to determine MTU for vl
+ =============== ===================================================
What: /sys/class/infiniband/hfi1_X/sdma_N/cpu_list
@@ -723,26 +759,28 @@ Contact: linux-rdma@vger.kernel.org
Description:
sdma<N>/ contains one directory per sdma engine (0 - 15)
+ =============== ==============================================
cpu_list: (RW) List of cpus for user-process to sdma
engine assignment.
vl: (RO) Displays the virtual lane (vl) the sdma
engine maps to.
+ =============== ==============================================
This interface gives the user control on the affinity settings
for the device. As an example, to set an sdma engine irq
affinity and thread affinity of a user processes to use the
sdma engine, which is "near" in terms of NUMA configuration, or
- physical cpu location, the user will do:
+ physical cpu location, the user will do::
- echo "3" > /proc/irq/<N>/smp_affinity_list
- echo "4-7" > /sys/devices/.../sdma3/cpu_list
- cat /sys/devices/.../sdma3/vl
- 0
- echo "8" > /proc/irq/<M>/smp_affinity_list
- echo "9-12" > /sys/devices/.../sdma4/cpu_list
- cat /sys/devices/.../sdma4/vl
- 1
+ echo "3" > /proc/irq/<N>/smp_affinity_list
+ echo "4-7" > /sys/devices/.../sdma3/cpu_list
+ cat /sys/devices/.../sdma3/vl
+ 0
+ echo "8" > /proc/irq/<M>/smp_affinity_list
+ echo "9-12" > /sys/devices/.../sdma4/cpu_list
+ cat /sys/devices/.../sdma4/vl
+ 1
to make sure that when a process runs on cpus 4,5,6, or 7, and
uses vl=0, then sdma engine 3 is selected by the driver, and
@@ -764,11 +802,13 @@ Date: Jan, 2016
KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== ========================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Show HCA type (I40IW)
board_id: (RO) I40IW board ID
+ =============== ==== ========================
sysfs interface for QLogic qedr NIC Driver
@@ -781,9 +821,11 @@ KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== ========================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Display HCA type
+ =============== ==== ========================
sysfs interface for VMware Paravirtual RDMA driver
@@ -797,11 +839,13 @@ KernelVersion: v4.10
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== =====================================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
board_id: (RO) Display PVRDMA manufacturing board ID
+ =============== ==== =====================================
sysfs interface for Broadcom NetXtreme-E RoCE driver
@@ -813,6 +857,8 @@ Date: Feb, 2017
KernelVersion: v4.11
Contact: linux-rdma@vger.kernel.org
Description:
+ =============== ==== =========================
hw_rev: (RO) Hardware revision number
hca_type: (RO) Host channel adapter type
+ =============== ==== =========================
diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
index 80151a409d67..370254b6296a 100644
--- a/Documentation/ABI/stable/sysfs-class-rfkill
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -54,6 +54,7 @@ Description: Current state of the transmitter.
through this interface. There will likely be another attempt to
remove it in the future.
Values: A numeric value.
+
0: RFKILL_STATE_SOFT_BLOCKED
transmitter is turned off by software
1: RFKILL_STATE_UNBLOCKED
@@ -69,6 +70,7 @@ KernelVersion v2.6.34
Contact: linux-wireless@vger.kernel.org
Description: Current hardblock state. This file is read only.
Values: A numeric value.
+
0: inactive
The transmitter is (potentially) active.
1: active
@@ -82,6 +84,7 @@ KernelVersion v2.6.34
Contact: linux-wireless@vger.kernel.org
Description: Current softblock state. This file is read and write.
Values: A numeric value.
+
0: inactive
The transmitter is (potentially) active.
1: active
diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm
index c0e23830f56a..bbee8899a90e 100644
--- a/Documentation/ABI/stable/sysfs-class-tpm
+++ b/Documentation/ABI/stable/sysfs-class-tpm
@@ -32,11 +32,11 @@ KernelVersion: 2.6.12
Contact: tpmdd-devel@lists.sf.net
Description: The "caps" property contains TPM manufacturer and version info.
- Example output:
+ Example output::
- Manufacturer: 0x53544d20
- TCG version: 1.2
- Firmware version: 8.16
+ Manufacturer: 0x53544d20
+ TCG version: 1.2
+ Firmware version: 8.16
Manufacturer is a hex dump of the 4 byte manufacturer info
space in a TPM. TCG version shows the TCG TPM spec level that
@@ -54,9 +54,9 @@ Description: The "durations" property shows the 3 vendor-specific values
any longer than necessary before starting to poll for a
result.
- Example output:
+ Example output::
- 3015000 4508000 180995000 [original]
+ 3015000 4508000 180995000 [original]
Here the short, medium and long durations are displayed in
usecs. "[original]" indicates that the values are displayed
@@ -92,14 +92,14 @@ Description: The "pcrs" property will dump the current value of all Platform
values may be constantly changing, the output is only valid
for a snapshot in time.
- Example output:
+ Example output::
- PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- ...
+ PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ ...
The number of PCRs and hex bytes needed to represent a PCR
value will vary depending on TPM chip version. For TPM 1.1 and
@@ -119,44 +119,44 @@ Description: The "pubek" property will return the TPM's public endorsement
ated at TPM manufacture time and exists for the life of the
chip.
- Example output:
-
- Algorithm: 00 00 00 01
- Encscheme: 00 03
- Sigscheme: 00 01
- Parameters: 00 00 08 00 00 00 00 02 00 00 00 00
- Modulus length: 256
- Modulus:
- B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C
- 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6
- 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB
- 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3
- D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B
- 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26
- 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E
- 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D
- 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0
- A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6
- 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6
- 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70
- E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A
- F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6
- F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B
- C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B
-
- Possible values:
-
- Algorithm: TPM_ALG_RSA (1)
- Encscheme: TPM_ES_RSAESPKCSv15 (2)
+ Example output::
+
+ Algorithm: 00 00 00 01
+ Encscheme: 00 03
+ Sigscheme: 00 01
+ Parameters: 00 00 08 00 00 00 00 02 00 00 00 00
+ Modulus length: 256
+ Modulus:
+ B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C
+ 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6
+ 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB
+ 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3
+ D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B
+ 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26
+ 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E
+ 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D
+ 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0
+ A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6
+ 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6
+ 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70
+ E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A
+ F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6
+ F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B
+ C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B
+
+ Possible values::
+
+ Algorithm: TPM_ALG_RSA (1)
+ Encscheme: TPM_ES_RSAESPKCSv15 (2)
TPM_ES_RSAESOAEP_SHA1_MGF1 (3)
- Sigscheme: TPM_SS_NONE (1)
- Parameters, a byte string of 3 u32 values:
+ Sigscheme: TPM_SS_NONE (1)
+ Parameters, a byte string of 3 u32 values:
Key Length (bits): 00 00 08 00 (2048)
Num primes: 00 00 00 02 (2)
Exponent Size: 00 00 00 00 (0 means the
default exp)
- Modulus Length: 256 (bytes)
- Modulus: The 256 byte Endorsement Key modulus
+ Modulus Length: 256 (bytes)
+ Modulus: The 256 byte Endorsement Key modulus
What: /sys/class/tpm/tpmX/device/temp_deactivated
Date: April 2006
@@ -176,9 +176,9 @@ Description: The "timeouts" property shows the 4 vendor-specific values
timeouts is defined by the TPM interface spec that the chip
conforms to.
- Example output:
+ Example output::
- 750000 750000 750000 750000 [original]
+ 750000 750000 750000 750000 [original]
The four timeout values are shown in usecs, with a trailing
"[original]" or "[adjusted]" depending on whether the values
diff --git a/Documentation/ABI/stable/sysfs-devices b/Documentation/ABI/stable/sysfs-devices
index 4404bd9b96c1..42bf1eab5677 100644
--- a/Documentation/ABI/stable/sysfs-devices
+++ b/Documentation/ABI/stable/sysfs-devices
@@ -1,5 +1,6 @@
-# Note: This documents additional properties of any device beyond what
-# is documented in Documentation/admin-guide/sysfs-rules.rst
+Note:
+ This documents additional properties of any device beyond what
+ is documented in Documentation/admin-guide/sysfs-rules.rst
What: /sys/devices/*/of_node
Date: February 2015
diff --git a/Documentation/ABI/stable/sysfs-driver-ib_srp b/Documentation/ABI/stable/sysfs-driver-ib_srp
index 7049a2b50359..2d706b4900ce 100644
--- a/Documentation/ABI/stable/sysfs-driver-ib_srp
+++ b/Documentation/ABI/stable/sysfs-driver-ib_srp
@@ -6,6 +6,7 @@ Description: Interface for making ib_srp connect to a new target.
One can request ib_srp to connect to a new target by writing
a comma-separated list of login parameters to this sysfs
attribute. The supported parameters are:
+
* id_ext, a 16-digit hexadecimal number specifying the eight
byte identifier extension in the 16-byte SRP target port
identifier. The target port identifier is sent by ib_srp
diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
index 156319fc5b80..3544968f43cc 100644
--- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io
+++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
@@ -1,5 +1,4 @@
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- asic_health
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_health
Date: June 2018
KernelVersion: 4.19
@@ -9,9 +8,8 @@ Description: This file shows ASIC health status. The possible values are:
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- cpld1_version
- cpld2_version
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_version
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_version
Date: June 2018
KernelVersion: 4.19
Contact: Vadim Pasternak <vadimpmellanox.com>
@@ -20,8 +18,7 @@ Description: These files show with which CPLD versions have been burned
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- fan_dir
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/fan_dir
Date: December 2018
KernelVersion: 5.0
@@ -32,8 +29,7 @@ Description: This file shows the system fans direction:
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- jtag_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
Date: November 2018
KernelVersion: 5.0
@@ -43,8 +39,7 @@ Description: These files show with which CPLD versions have been burned
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- jtag_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
Date: November 2018
KernelVersion: 5.0
@@ -87,16 +82,15 @@ Description: These files allow asserting system power cycling, switching
The files are write only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- reset_aux_pwr_or_ref
- reset_asic_thermal
- reset_hotswap_or_halt
- reset_hotswap_or_wd
- reset_fw_reset
- reset_long_pb
- reset_main_pwr_fail
- reset_short_pb
- reset_sw_reset
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_aux_pwr_or_ref
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_asic_thermal
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_halt
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_wd
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_fw_reset
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_long_pb
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_main_pwr_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_short_pb
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sw_reset
Date: June 2018
KernelVersion: 4.19
Contact: Vadim Pasternak <vadimpmellanox.com>
@@ -110,11 +104,10 @@ Description: These files show the system reset cause, as following: power
The files are read only.
-What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/
- reset_comex_pwr_fail
- reset_from_comex
- reset_system
- reset_voltmon_upgrade_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_pwr_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_comex
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_system
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_voltmon_upgrade_fail
Date: November 2018
KernelVersion: 5.0
diff --git a/Documentation/ABI/stable/sysfs-firmware-efi-vars b/Documentation/ABI/stable/sysfs-firmware-efi-vars
index 5def20b9019e..46ccd233e359 100644
--- a/Documentation/ABI/stable/sysfs-firmware-efi-vars
+++ b/Documentation/ABI/stable/sysfs-firmware-efi-vars
@@ -17,6 +17,7 @@ Description:
directory has a name of the form "<key>-<vendor guid>"
and contains the following files:
+ =============== ========================================
attributes: A read-only text file enumerating the
EFI variable flags. Potential values
include:
@@ -59,12 +60,14 @@ Description:
size: As ASCII representation of the size of
the variable's value.
+ =============== ========================================
In addition, two other magic binary files are provided
in the top-level directory and are used for adding and
removing variables:
+ =============== ========================================
new_var: Takes a "struct efi_variable" and
instructs the EFI firmware to create a
new variable.
@@ -73,3 +76,4 @@ Description:
instructs the EFI firmware to remove any
variable that has a matching vendor GUID
and variable key name.
+ =============== ========================================
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-dump b/Documentation/ABI/stable/sysfs-firmware-opal-dump
index 32fe7f5c4880..1f74f45327ba 100644
--- a/Documentation/ABI/stable/sysfs-firmware-opal-dump
+++ b/Documentation/ABI/stable/sysfs-firmware-opal-dump
@@ -7,6 +7,7 @@ Description:
This is only for the powerpc/powernv platform.
+ =============== ===============================================
initiate_dump: When '1' is written to it,
we will initiate a dump.
Read this file for supported commands.
@@ -19,8 +20,11 @@ Description:
and ID of the dump, use the id and type files.
Do not rely on any particular size of dump
type or dump id.
+ =============== ===============================================
Each dump has the following files:
+
+ =============== ===============================================
id: An ASCII representation of the dump ID
in hex (e.g. '0x01')
type: An ASCII representation of the type of
@@ -39,3 +43,4 @@ Description:
inaccessible.
Reading this file will get a list of
supported actions.
+ =============== ===============================================
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-elog b/Documentation/ABI/stable/sysfs-firmware-opal-elog
index 2536434d49d0..7c8a61a2d005 100644
--- a/Documentation/ABI/stable/sysfs-firmware-opal-elog
+++ b/Documentation/ABI/stable/sysfs-firmware-opal-elog
@@ -38,6 +38,7 @@ Description:
For each log entry (directory), there are the following
files:
+ ============== ================================================
id: An ASCII representation of the ID of the
error log, in hex - e.g. "0x01".
@@ -58,3 +59,4 @@ Description:
entry will be removed from sysfs.
Reading this file will list the supported
operations (currently just acknowledge).
+ ============== ================================================
diff --git a/Documentation/ABI/stable/sysfs-hypervisor-xen b/Documentation/ABI/stable/sysfs-hypervisor-xen
index 3cf5cdfcd9a8..01bd46be261e 100644
--- a/Documentation/ABI/stable/sysfs-hypervisor-xen
+++ b/Documentation/ABI/stable/sysfs-hypervisor-xen
@@ -33,6 +33,7 @@ Description: If running under Xen:
Space separated list of supported guest system types. Each type
is in the format: <class>-<major>.<minor>-<arch>
With:
+ ======== ============================================
<class>: "xen" -- x86: paravirtualized, arm: standard
"hvm" -- x86 only: fully virtualized
<major>: major guest interface version
@@ -43,6 +44,7 @@ Description: If running under Xen:
"x86_64": 64 bit x86 guest
"armv7l": 32 bit arm guest
"aarch64": 64 bit arm guest
+ ======== ============================================
What: /sys/hypervisor/properties/changeset
Date: March 2009
diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso
index 55406ec8a35a..73ed1240a5c0 100644
--- a/Documentation/ABI/stable/vdso
+++ b/Documentation/ABI/stable/vdso
@@ -23,6 +23,7 @@ Unless otherwise noted, the set of symbols with any given version and the
ABI of those symbols is considered stable. It may vary across architectures,
though.
-(As of this writing, this ABI documentation as been confirmed for x86_64.
+Note:
+ As of this writing, this ABI documentation as been confirmed for x86_64.
The maintainers of the other vDSO-using architectures should confirm
- that it is correct for their architecture.)
+ that it is correct for their architecture.
Thanks,
Mauro
^ permalink raw reply related
* Re: [PATCH 04/14] ABI: better identificate tables
From: Greg Kroah-Hartman @ 2019-06-21 7:21 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Johan Hovold, Linux Doc Mailing List, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Stefan Achatz
In-Reply-To: <20190620112749.5e3fb4e9@coco.lan>
On Thu, Jun 20, 2019 at 11:27:49AM -0300, Mauro Carvalho Chehab wrote:
> Em Wed, 19 Jun 2019 13:14:08 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
>
> > Em Wed, 19 Jun 2019 17:02:07 +0200
> > Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
> >
> > > On Wed, Jun 19, 2019 at 10:56:33AM -0300, Mauro Carvalho Chehab wrote:
> > > > Hi Johan,
> > > >
> > > > Em Wed, 19 Jun 2019 14:51:35 +0200
> > > > Johan Hovold <johan@kernel.org> escreveu:
> > > >
> > > > > On Thu, Jun 13, 2019 at 11:04:10PM -0300, Mauro Carvalho Chehab wrote:
> > > > > > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > > > >
> > > > > > When parsing via script, it is important to know if the script
> > > > > > should consider a description as a literal block that should
> > > > > > be displayed as-is, or if the description can be considered
> > > > > > as a normal text.
> > > > > >
> > > > > > Change descriptions to ensure that the preceding line of a table
> > > > > > ends with a colon. That makes easy to identify the need of a
> > > > > > literal block.
> > > > >
> > > > > In the cover letter you say that the first four patches of this series,
> > > > > including this one, "fix some ABI descriptions that are violating the
> > > > > syntax described at Documentation/ABI/README". This seems a bit harsh,
> > > > > given that it's you that is now *introducing* a new syntax requirement
> > > > > to assist your script.
> > > >
> > > > Yeah, what's there at the cover letter doesn't apply to this specific
> > > > patch. The thing is that I wrote this series a lot of time ago (2016/17).
> > > >
> > > > I revived those per a request at KS ML, as we still need to expose the
> > > > ABI content on some book that will be used by userspace people.
> > > >
> > > > So, I just rebased it on the top of curent Kernel, add a cover letter
> > > > with the things I remembered and re-sent.
> > > >
> > > > In the specific case of this patch, the ":" there actually makes sense
> > > > for someone that it is reading it as a text file, and it is an easy
> > > > hack to make it parse better.
> > > >
> > > > > Specifically, this new requirement isn't documented anywhere AFAICT, so
> > > > > how will anyone adding new ABI descriptions learn about it?
> > > >
> > > > Yeah, either that or provide an alternative to "Description" tag, to be
> > > > used with more complex ABI descriptions.
> > > >
> > > > One of the things that occurred to me, back on 2017, is that we should
> > > > have a way to to specify that an specific ABI description would have
> > > > a rich format. Something like:
> > > >
> > > > What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_cpi
> > > > Date: August 2010
> > > > Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
> > > > RST-Description:
> > > > It is possible to switch the cpi setting of the mouse with the
> > > > press of a button.
> > > > When read, this file returns the raw number of the actual cpi
> > > > setting reported by the mouse. This number has to be further
> > > > processed to receive the real dpi value:
> > > >
> > > > ===== =====
> > > > VALUE DPI
> > > > ===== =====
> > > > 1 400
> > > > 2 800
> > > > 4 1600
> > > > ===== =====
> > > >
> > > > With that, the script will know that the description contents will be using
> > > > the ReST markup, and parse it accordingly. Right now, what it does, instead,
> > > > is to place the description on a code-block, e. g. it will produce this
> > > > output for the description:
> > > >
> > > > ::
> > > >
> > > > It is possible to switch the cpi setting of the mouse with the
> > > > press of a button.
> > > > When read, this file returns the raw number of the actual cpi
> > > > setting reported by the mouse. This number has to be further
> > > > processed to receive the real dpi value:
> > > >
> > > > VALUE DPI
> > > > 1 400
> > > > 2 800
> > > > 4 1600
> > > >
> > > >
> > > > Greg,
> > > >
> > > > what do you think?
> > >
> > > I don't know when "Description" and "RST-Description" would be used.
> > > Why not just parse "Description" like rst text and if things are "messy"
> > > we fix them up as found, like you did with the ":" here? It doesn't
> > > have to be complex, we can always fix them up after-the-fact if new
> > > stuff gets added that doesn't quite parse properly.
> > >
> > > Just like we do for most kernel-doc formatting :)
> >
> > Works for me. Yet, I guess I tried that, back on 2017.
> >
> > If I'm not mistaken, the initial patchset to solve the broken things
> > won't be small, and will be require a lot of attention in order to
> > identify what's broken and where.
> >
> > Btw, one thing is to pass at ReST validation. Another thing is to
> > produce something that people can read.
> >
> > Right now, the pertinent logic at the script I wrote (scripts/get_abi.pl)
> > is here:
> >
> > if (!($desc =~ /^\s*$/)) {
> > if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
> > # put everything inside a code block
> > $desc =~ s/\n/\n /g;
> >
> > print "::\n\n";
> > print " $desc\n\n";
> > } else {
> > # Escape any special chars from description
> > $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
> >
> > print "$desc\n\n";
> > }
> > }
> >
> > If it discovers something weird enough, it just places everything
> > into a comment block. Otherwise, it assumes that it is a plain
> > text and that any special characters should be escaped.
> >
> > If the above block is replaced by a simple:
> >
> > print "$desc\n\n";
> >
> > The description content will be handled as a ReST file.
> >
> > I don't have any time right now to do this change and to handle the
> > warnings that will start to popup.
> >
> > Btw, a single replace there is enough to show the amount of problems that
> > it will rise, as it will basically break Sphinx build with:
> >
> > reading sources... [ 1%] admin-guide/abi-testing
> > reST markup error:
> > get_abi.pl rest --dir $srctree/Documentation/ABI/testing:45261: (SEVERE/4) Missing matching underline for section title overline.
> >
> > ==========================
> > PCIe Device AER statistics
> > These attributes show up under all the devices that are AER capable. These
>
> To be clear here: the problem with the above is that ReST has zero
> tolerance and actually behaves like a crash, if it receives something like:
>
> ==========================
> PCIe Device AER statistics
> ==========================
>
> For it to work, it has to have zero spaces before ===..=== line, e. g.:
>
> ==========================
> PCIe Device AER statistics
> ==========================
>
> Ok, maybe we could try to teach the parser a way to identify the initial
> spacing of the first description line and remove that amount of
> spaces/tabs for the following lines, but it may require some heuristics.
Or we can clean this type of thing up by hand :)
Let's see how bad this gets, the documentation in these files should not
be very complex as they _should_ only be one-value-per-file, but as you
have shown in this very example, that rule is violated :(
thanks,
greg k-h
^ permalink raw reply
* Re: [PATCH] doc-rst: Add missing newline at end of file
From: Jonathan Corbet @ 2019-06-20 20:17 UTC (permalink / raw)
To: Geert Uytterhoeven; +Cc: linux-doc, linux-kernel
In-Reply-To: <20190617143400.4559-1-geert+renesas@glider.be>
On Mon, 17 Jun 2019 16:34:00 +0200
Geert Uytterhoeven <geert+renesas@glider.be> wrote:
> "git diff" says:
>
> \ No newline at end of file
>
> after modifying the file.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Applied, thanks.
jon
^ permalink raw reply
* Re: [PATCH 0/4] Documentation: x86: resctrl_ui.txt fixes and clarification
From: Jonathan Corbet @ 2019-06-20 20:16 UTC (permalink / raw)
To: James Morse
Cc: linux-doc, x86, Reinette Chatre, Fenghua Yu, Babu Moger,
linux-kernel
In-Reply-To: <20190607151409.15476-1-james.morse@arm.com>
On Fri, 7 Jun 2019 16:14:05 +0100
James Morse <james.morse@arm.com> wrote:
> While updating resctrl_ui.rst for arm64 support these things stuck
> out as being unclear or no longer true.
>
> (I've shortened the CC list to just RDT+Documentation)
>
>
> Thanks,
>
> James Morse (4):
> Documentation: x86: Contiguous cbm isn't all X86
> Documentation: x86: Remove cdpl2 unspported statement and fix
> capitalisation
> Documentation: x86: Clarify MBA takes MB as referring to mba_sc
> Documentation: x86: fix some typos
>
> Documentation/x86/resctrl_ui.rst | 30 ++++++++++++++++++------------
> 1 file changed, 18 insertions(+), 12 deletions(-)
I've applied this set, sorry for the delay.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH 4/6] time: hrtimer: use a bullet for the returns bullet list
From: Mauro Carvalho Chehab @ 2019-06-20 20:16 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Thomas Gleixner
In-Reply-To: <20190620140233.3d7202ee@lwn.net>
Em Thu, 20 Jun 2019 14:02:33 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Tue, 18 Jun 2019 15:51:20 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > That gets rid of this warning:
> >
> > ./kernel/time/hrtimer.c:1119: WARNING: Block quote ends without a blank line; unexpected unindent.
> >
> > and displays nicely both at the source code and at the produced
> > documentation.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> > kernel/time/hrtimer.c | 7 ++++---
> > 1 file changed, 4 insertions(+), 3 deletions(-)
> >
> > diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
> > index edb230aba3d1..49f78453892f 100644
> > --- a/kernel/time/hrtimer.c
> > +++ b/kernel/time/hrtimer.c
> > @@ -1114,9 +1114,10 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
> > * @timer: hrtimer to stop
> > *
> > * Returns:
> > - * 0 when the timer was not active
> > - * 1 when the timer was active
> > - * -1 when the timer is currently executing the callback function and
> > + *
> > + * • 0 when the timer was not active
> > + * • 1 when the timer was active
> > + * • -1 when the timer is currently executing the callback function and
> > * cannot be stopped
>
> So I have taken some grief for letting non-ASCII stuff into the docs
> before; I can only imagine that those who object would be even more
> unhappy to see it in a C source file. I'm all for fixing the warning, but
> I think we shouldn't start introducing exotic characters at this point...
According to:
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists
The ASCII options are: "-", "+" or "*".
Both signs ('-' and '+') aren't too nice here, due to "-1".
So, what's left is '*'.
I remember someone once complained about having something like:
* * -1 when the ...
But if you think we shouldn't use UTF-8 chars, be it.
Feel free to replace it at the patch, or if you prefer, I'll send a new
version tomorrow.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH] docs: fix some broken references due to txt->rst renames
From: Jonathan Corbet @ 2019-06-20 20:14 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Rob Herring, Mark Rutland, Jani Nikula, Joonas Lahtinen,
Rodrigo Vivi, David Airlie, Daniel Vetter, Ajay Gupta,
Amit Kucheria, Sudeep Holla, Otto Sabart, Li Yang, Will Deacon,
devicetree, intel-gfx, dri-devel, linux-i2c
In-Reply-To: <6f09587b7678f2fb378d736f45a02ffa9412cc99.1560864716.git.mchehab+samsung@kernel.org>
On Tue, 18 Jun 2019 10:33:58 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> here are three left-overs from the recent file renames,
> probably due to some other conflicting patch.
>
> Fix them.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>
> This patch is against today's next-20190617 branch. Not sure if it
> will apply cleanly at -docs tree. If not, Please let me know for me to
> split.
Indeed it does not; one of the files being patched doesn't even exist in
my world...
jon
^ permalink raw reply
* Re: [PATCH] docs: stop suggesting strlcpy
From: Jonathan Corbet @ 2019-06-20 20:09 UTC (permalink / raw)
To: Stephen Kitt; +Cc: federico.vaga, linux-doc, keescook, linux-kernel
In-Reply-To: <20190613162548.19792-1-steve@sk2.org>
On Thu, 13 Jun 2019 18:25:48 +0200
Stephen Kitt <steve@sk2.org> wrote:
> Since strlcpy is deprecated, the documentation shouldn't suggest using
> it. This patch fixes the examples to use strscpy instead. It also uses
> sizeof instead of underlying constants as far as possible, to simplify
> future changes to the corresponding data structures.
>
> Signed-off-by: Stephen Kitt <steve@sk2.org>
Applied, thanks.
jon
^ permalink raw reply
* Re: [PATCH 3/6] lib: list_sort.c: add a blank line to avoid kernel-doc warnings
From: Jonathan Corbet @ 2019-06-20 20:07 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Andrew Morton, George Spelvin, Andy Shevchenko, Andrey Abramov,
Rasmus Villemoes
In-Reply-To: <019c38a60bdc87124e58f8acd541b484fc9893bb.1560883872.git.mchehab+samsung@kernel.org>
On Tue, 18 Jun 2019 15:51:19 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> In order for a list to be recognized as such, blank lines
> are required.
>
> Solve those Sphinx warnings:
>
> ./lib/list_sort.c:162: WARNING: Unexpected indentation.
> ./lib/list_sort.c:163: WARNING: Block quote ends without a blank line; unexpected unindent.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Applied, thanks.
jon
^ permalink raw reply
* Re: [PATCH 2/6] docs: trace: add a missing blank line
From: Jonathan Corbet @ 2019-06-20 20:07 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Masami Hiramatsu, Steven Rostedt (VMware), Ingo Molnar,
Andreas Ziegler, Lecopzer Chen
In-Reply-To: <91f90c10c12c6a2f6fb90fc0f9115fbd8dd73848.1560883872.git.mchehab+samsung@kernel.org>
On Tue, 18 Jun 2019 15:51:18 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Sphinx expects a blank line after a literal block markup.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/trace/kprobetrace.rst | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
> index 3d162d432a3c..caa0a8ba081e 100644
> --- a/Documentation/trace/kprobetrace.rst
> +++ b/Documentation/trace/kprobetrace.rst
> @@ -228,6 +228,7 @@ events, you need to enable it.
>
> Use the following command to start tracing in an interval.
> ::
> +
Applied, thanks.
jon
^ permalink raw reply
* Re: [PATCH 1/6] docs: trace: fix a broken label
From: Jonathan Corbet @ 2019-06-20 20:06 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Masami Hiramatsu, Steven Rostedt (VMware), Andreas Ziegler,
Lecopzer Chen
In-Reply-To: <a83ea390bc28784518fce772b4c961ea1c976f14.1560883872.git.mchehab+samsung@kernel.org>
On Tue, 18 Jun 2019 15:51:17 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Sphinx warnings about his:
>
> Documentation/trace/kprobetrace.rst:68: WARNING: undefined label: user_mem_access (if the link has no caption the label must precede a section header)
>
> The problem is quite simple: Sphinx wants a blank line after
> references.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/trace/kprobetrace.rst | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
> index b729b40a5ba5..3d162d432a3c 100644
> --- a/Documentation/trace/kprobetrace.rst
> +++ b/Documentation/trace/kprobetrace.rst
> @@ -96,6 +96,7 @@ which shows given pointer in "symbol+offset" style.
> For $comm, the default type is "string"; any other type is invalid.
>
> .. _user_mem_access:
This one doesn't apply to docs-next; it should probably go through
whichever tree introduced the issue into linux-next.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH 4/6] time: hrtimer: use a bullet for the returns bullet list
From: Jonathan Corbet @ 2019-06-20 20:02 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Thomas Gleixner
In-Reply-To: <a4cab6020e0475e7a4afc65dc5854756dd1bfbe9.1560883872.git.mchehab+samsung@kernel.org>
On Tue, 18 Jun 2019 15:51:20 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> That gets rid of this warning:
>
> ./kernel/time/hrtimer.c:1119: WARNING: Block quote ends without a blank line; unexpected unindent.
>
> and displays nicely both at the source code and at the produced
> documentation.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> kernel/time/hrtimer.c | 7 ++++---
> 1 file changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
> index edb230aba3d1..49f78453892f 100644
> --- a/kernel/time/hrtimer.c
> +++ b/kernel/time/hrtimer.c
> @@ -1114,9 +1114,10 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
> * @timer: hrtimer to stop
> *
> * Returns:
> - * 0 when the timer was not active
> - * 1 when the timer was active
> - * -1 when the timer is currently executing the callback function and
> + *
> + * • 0 when the timer was not active
> + * • 1 when the timer was active
> + * • -1 when the timer is currently executing the callback function and
> * cannot be stopped
So I have taken some grief for letting non-ASCII stuff into the docs
before; I can only imagine that those who object would be even more
unhappy to see it in a C source file. I'm all for fixing the warning, but
I think we shouldn't start introducing exotic characters at this point...
Thanks,
jon
> */
> int hrtimer_try_to_cancel(struct hrtimer *timer)
^ permalink raw reply
* Re: [PATCH] docs: fb: Add TER16x32 to the available font names
From: Jonathan Corbet @ 2019-06-20 19:55 UTC (permalink / raw)
To: Takashi Iwai
Cc: Bartlomiej Zolnierkiewicz, Randy Dunlap, Greg Kroah-Hartman,
linux-doc, linux-fbdev, linux-kernel
In-Reply-To: <20190619053943.6320-1-tiwai@suse.de>
On Wed, 19 Jun 2019 07:39:43 +0200
Takashi Iwai <tiwai@suse.de> wrote:
> The new font is available since recently.
>
> Signed-off-by: Takashi Iwai <tiwai@suse.de>
> ---
> Documentation/fb/fbcon.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst
> index cfb9f7c38f18..1da65b9000de 100644
> --- a/Documentation/fb/fbcon.rst
> +++ b/Documentation/fb/fbcon.rst
> @@ -82,7 +82,7 @@ C. Boot options
>
> Select the initial font to use. The value 'name' can be any of the
> compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6,
> - PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, VGA8x16, VGA8x8.
> + PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, TER16x32, VGA8x16, VGA8x8.
Applied, thanks.
jon
^ permalink raw reply
* Re: [PATCH v2] Documentation: platform: Delete x86-laptop-drivers.txt
From: Andy Shevchenko @ 2019-06-20 19:50 UTC (permalink / raw)
To: Puranjay Mohan
Cc: Shuah Khan, Greg KH, Jonathan Corbet, Cezary Jackiewicz,
Darren Hart, Andy Shevchenko, Linux Documentation List,
linux-kernel-mentees, Linux Kernel Mailing List, Platform Driver
In-Reply-To: <20190620183827.23704-1-puranjay12@gmail.com>
On Thu, Jun 20, 2019 at 9:38 PM Puranjay Mohan <puranjay12@gmail.com> wrote:
>
> The list of laptops supported by drivers in PDx86 subsystem is quite
> big and growing. x86-laptop-drivers.txt contains details of very few
> laptop models. Remove it because it does not serve any purpose.
>
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
> Signed-off-by: Puranjay Mohan <puranjay12@gmail.com>
> ---
> Documentation/platform/x86-laptop-drivers.txt | 18 ------------------
> 1 file changed, 18 deletions(-)
> delete mode 100644 Documentation/platform/x86-laptop-drivers.txt
>
> diff --git a/Documentation/platform/x86-laptop-drivers.txt b/Documentation/platform/x86-laptop-drivers.txt
> deleted file mode 100644
> index 01facd2590bb..000000000000
> --- a/Documentation/platform/x86-laptop-drivers.txt
> +++ /dev/null
> @@ -1,18 +0,0 @@
> -compal-laptop
> -=============
> -List of supported hardware:
> -
> -by Compal:
> - Compal FL90/IFL90
> - Compal FL91/IFL91
> - Compal FL92/JFL92
> - Compal FT00/IFT00
> -
> -by Dell:
> - Dell Vostro 1200
> - Dell Mini 9 (Inspiron 910)
> - Dell Mini 10 (Inspiron 1010)
> - Dell Mini 10v (Inspiron 1011)
> - Dell Mini 1012 (Inspiron 1012)
> - Dell Inspiron 11z (Inspiron 1110)
> - Dell Mini 12 (Inspiron 1210)
> --
> 2.21.0
>
--
With Best Regards,
Andy Shevchenko
^ 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