Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1642478 > unrolled thread
| Started by | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| First post | 2017-05-16 14:20 +0200 |
| Last post | 2017-05-19 01:10 +0200 |
| Articles | 20 on this page of 57 — 8 participants |
Back to article view | Back to linux.kernel
[PATCH v2 00/53] Get rid of Docbook Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
[PATCH v2 18/53] docs-rst: filesystems: use c domain references where needed Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
[PATCH v2 06/53] locking.rst: add captions to two tables Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
[PATCH v2 33/53] scsi: fix some kernel-doc markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
[PATCH v2 17/53] docs-rst: convert filesystems book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
[PATCH v2 39/53] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
Re: [PATCH v2 39/53] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings Boris Brezillon <boris.brezillon@free-electrons.com> - 2017-05-16 15:20 +0200
[PATCH v2 16/53] docs-rst: add userspace API book to pdf output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 20/53] docs-rst: don't ignore internal functions for jbd2 docs Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 15/53] docs-rst: add sound book to pdf output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
Re: [PATCH v2 15/53] docs-rst: add sound book to pdf output Takashi Iwai <tiwai@suse.de> - 2017-05-16 21:10 +0200
[PATCH v2 31/53] docs-rst: convert z8530book DocBook to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 10/53] conf.py: define a color for important markup on PDF output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 44/53] MAINTAINERS: update old references for DocBook directory Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 02/53] kernel-hacking: update document Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 53/53] kernel-doc: describe the ``literal`` syntax Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 20:20 +0200
[PATCH v2 52/53] docs-rst: get rid of Documentation/sphinx/tmplcvt script Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 20:20 +0200
[PATCH v2 50/53] fs: fix the location of the kernel-api book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 20:20 +0200
[PATCH v2 51/53] usb: fix the comment with regards to DocBook Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 20:20 +0200
Re: [PATCH v2 51/53] usb: fix the comment with regards to DocBook Felipe Balbi <balbi@kernel.org> - 2017-05-17 13:20 +0200
[PATCH v2 14/53] docs-rst: add dev-tools book to pdf output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 29/53] net: skbuff.h: properly escape a macro name on kernel-doc Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 07/53] locking.rst: Update some ReST markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 09/53] kgdb.rst: Adjust ReST markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 47/53] irq: update genericirq book location Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 41/53] docs-rst: convert lsm from DocBook to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 46/53] ia64, scsi: update references for the device-io book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 05/53] locking.rst: reformat locking table Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 25/53] libata.rst: add c function and struct cross-references Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 36/53] docs-rst: convert librs book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 42/53] docs: remove DocBook from the building system Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 32/53] docs-rst: convert scsi DocBook to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 48/53] fs: update location of filesystems documentation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 34/53] docs-rst: convert w1 book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 49/53] lib: update location of kgdb documentation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 28/53] docs-rst: convert networking book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 30/53] net: fix some identation issues at kernel-doc markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
Re: [PATCH v2 30/53] net: fix some identation issues at kernel-doc markups David Howells <dhowells@redhat.com> - 2017-05-16 14:40 +0200
[PATCH v2 04/53] mutex, futex: adjust kernel-doc markups to generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
Re: [PATCH v2 04/53] mutex, futex: adjust kernel-doc markups to generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-16 19:40 +0200
Re: [PATCH v2 04/53] mutex, futex: adjust kernel-doc markups to generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 20:30 +0200
Re: [PATCH v2 04/53] mutex, futex: adjust kernel-doc markups to generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-16 21:10 +0200
[PATCH v2 21/53] fs: add a blank lines on some kernel-doc comments Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 11/53] docs-rst: conf.py: sort LaTeX documents in alphabetical order Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 12/53] docs-rst: conf.py: remove kernel-documentation from LaTeX Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 43/53] docs: update old references for DocBook from the documentation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
Re: [PATCH v2 43/53] docs: update old references for DocBook from the documentation Bjorn Helgaas <helgaas@kernel.org> - 2017-05-17 19:00 +0200
[PATCH v2 13/53] docs-rst: add crypto API book to pdf output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
[PATCH v2 22/53] fs: eventfd: fix identation on kernel-doc Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
[PATCH v2 35/53] docs-rst: convert rapidio book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
[PATCH v2 27/53] docs-rst: convert s390-drivers DocBook to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
[PATCH v2 26/53] libata: fix identation on a kernel-doc markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
[PATCH v2 38/53] mtdnand.rst: group the "::" with previous line Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
Re: [PATCH v2 38/53] mtdnand.rst: group the "::" with previous line Boris Brezillon <boris.brezillon@free-electrons.com> - 2017-05-16 15:20 +0200
[PATCH v2 40/53] docs-rst: convert sh book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
Re: [PATCH v2 00/53] Get rid of Docbook Jonathan Corbet <corbet@lwn.net> - 2017-05-18 19:30 +0200
Re: [PATCH v2 00/53] Get rid of Docbook Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 01:10 +0200
Page 1 of 3 [1] 2 3 Next page →
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:20 +0200 |
| Subject | [PATCH v2 00/53] Get rid of Docbook |
| Message-ID | <tHJCh-5vb-5@gated-at.bofh.it> |
This patch series convert the remaining DocBooks to ReST.
The first version was originally
send as 3 patch series:
[PATCH 00/36] Convert DocBook documents to ReST
[PATCH 0/5] Convert more books to ReST
[PATCH 00/13] Get rid of DocBook
The lsm book was added as if it were a text file under
Documentation. The plan is to merge it with another file
under Documentation/security, after both this series and
a security Documentation patch series gets merged.
It also adjusts some Sphinx-pedantic errors/warnings on
some kernel-doc markups.
I also added some patches here to add PDF output for all
existing ReST books.
I did my best to check if what's there is not too outdated, but
the best is if the subsystem maintainers could check it.
This patch series is based on docs tree (next branch):
git://git.lwn.net/linux.git docs-next
The full patch series is on this tree:
https://git.linuxtv.org//mchehab/experimental.git/log/?h=docbook3
And the HTML output at:
http://www.infradead.org/~mchehab/kernel_docs/
https://mchehab.fedorapeople.org/kernel_docs/
--
v2:
- merged the 3 other patch series into just one
- added a patch describing ``literal`` kernel-doc syntax
- addressed the points taken during review process
- removed two patches that will be merged via subsystem
trees:
[PATCH 10/13] sound: fix the comments that refers to kernel-doc
[PATCH 21/36] fs: locks: Fix some troubles at kernel-doc comments
Mauro Carvalho Chehab (53):
docs-rst: convert kernel-hacking to ReST
kernel-hacking: update document
docs-rst: convert kernel-locking to ReST
mutex, futex: adjust kernel-doc markups to generate ReST
locking.rst: reformat locking table
locking.rst: add captions to two tables
locking.rst: Update some ReST markups
docs-rst: convert kgdb DocBook to ReST
kgdb.rst: Adjust ReST markups
conf.py: define a color for important markup on PDF output
docs-rst: conf.py: sort LaTeX documents in alphabetical order
docs-rst: conf.py: remove kernel-documentation from LaTeX
docs-rst: add crypto API book to pdf output
docs-rst: add dev-tools book to pdf output
docs-rst: add sound book to pdf output
docs-rst: add userspace API book to pdf output
docs-rst: convert filesystems book to ReST
docs-rst: filesystems: use c domain references where needed
fs: jbd2: make jbd2_journal_start() kernel-doc parseable
docs-rst: don't ignore internal functions for jbd2 docs
fs: add a blank lines on some kernel-doc comments
fs: eventfd: fix identation on kernel-doc
fs: jbd2: escape a string with special chars on a kernel-doc
docs-rst: convert libata book to ReST
libata.rst: add c function and struct cross-references
libata: fix identation on a kernel-doc markup
docs-rst: convert s390-drivers DocBook to ReST
docs-rst: convert networking book to ReST
net: skbuff.h: properly escape a macro name on kernel-doc
net: fix some identation issues at kernel-doc markups
docs-rst: convert z8530book DocBook to ReST
docs-rst: convert scsi DocBook to ReST
scsi: fix some kernel-doc markups
docs-rst: convert w1 book to ReST
docs-rst: convert rapidio book to ReST
docs-rst: convert librs book to ReST
docs-rst: convert mtdnand book to ReST
mtdnand.rst: group the "::" with previous line
mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
docs-rst: convert sh book to ReST
docs-rst: convert lsm from DocBook to ReST
docs: remove DocBook from the building system
docs: update old references for DocBook from the documentation
MAINTAINERS: update old references for DocBook directory
ata: update references for libata documentation
ia64, scsi: update references for the device-io book
irq: update genericirq book location
fs: update location of filesystems documentation
lib: update location of kgdb documentation
fs: fix the location of the kernel-api book
usb: fix the comment with regards to DocBook
docs-rst: get rid of Documentation/sphinx/tmplcvt script
kernel-doc: describe the ``literal`` syntax
Documentation/00-INDEX | 6 +-
Documentation/DocBook/.gitignore | 17 -
Documentation/DocBook/Makefile | 282 ----
Documentation/DocBook/filesystems.tmpl | 381 -----
Documentation/DocBook/kernel-hacking.tmpl | 1312 -----------------
Documentation/DocBook/kernel-locking.tmpl | 2151 ----------------------------
Documentation/DocBook/kgdb.tmpl | 918 ------------
Documentation/DocBook/libata.tmpl | 1625 ---------------------
Documentation/DocBook/librs.tmpl | 289 ----
Documentation/DocBook/lsm.tmpl | 265 ----
Documentation/DocBook/mtdnand.tmpl | 1291 -----------------
Documentation/DocBook/networking.tmpl | 111 --
Documentation/DocBook/rapidio.tmpl | 155 --
Documentation/DocBook/s390-drivers.tmpl | 161 ---
Documentation/DocBook/scsi.tmpl | 409 ------
Documentation/DocBook/sh.tmpl | 105 --
Documentation/DocBook/stylesheet.xsl | 11 -
Documentation/DocBook/w1.tmpl | 101 --
Documentation/DocBook/z8530book.tmpl | 371 -----
Documentation/Makefile | 125 ++
Documentation/Makefile.sphinx | 130 --
Documentation/PCI/MSI-HOWTO.txt | 2 +-
Documentation/admin-guide/README.rst | 6 -
Documentation/conf.py | 37 +-
Documentation/core-api/index.rst | 1 +
Documentation/core-api/librs.rst | 212 +++
Documentation/crypto/conf.py | 10 +
Documentation/dev-tools/index.rst | 1 +
Documentation/dev-tools/kgdb.rst | 907 ++++++++++++
Documentation/doc-guide/docbook.rst | 90 --
Documentation/doc-guide/index.rst | 1 -
Documentation/doc-guide/kernel-doc.rst | 10 +
Documentation/doc-guide/sphinx.rst | 5 -
Documentation/driver-api/index.rst | 6 +
Documentation/driver-api/libata.rst | 1031 +++++++++++++
Documentation/driver-api/mtdnand.rst | 1007 +++++++++++++
Documentation/driver-api/rapidio.rst | 107 ++
Documentation/driver-api/s390-drivers.rst | 111 ++
Documentation/driver-api/scsi.rst | 344 +++++
Documentation/driver-api/w1.rst | 70 +
Documentation/fb/api.txt | 4 +-
Documentation/filesystems/conf.py | 10 +
Documentation/filesystems/index.rst | 317 ++++
Documentation/gpu/todo.rst | 2 +-
Documentation/index.rst | 14 +
Documentation/kernel-doc-nano-HOWTO.txt | 65 +-
Documentation/kernel-hacking/conf.py | 10 +
Documentation/kernel-hacking/hacking.rst | 811 +++++++++++
Documentation/kernel-hacking/index.rst | 9 +
Documentation/kernel-hacking/locking.rst | 1446 +++++++++++++++++++
Documentation/lsm.txt | 201 +++
Documentation/networking/conf.py | 10 +
Documentation/networking/index.rst | 18 +
Documentation/networking/kapi.rst | 147 ++
Documentation/networking/z8530book.rst | 256 ++++
Documentation/process/changes.rst | 26 +-
Documentation/process/howto.rst | 8 -
Documentation/process/kernel-docs.rst | 34 +-
Documentation/sh/conf.py | 10 +
Documentation/sh/index.rst | 59 +
Documentation/sound/conf.py | 10 +
Documentation/sphinx/tmplcvt | 28 -
Documentation/translations/ja_JP/howto.rst | 7 -
Documentation/translations/ko_KR/howto.rst | 7 -
MAINTAINERS | 5 +-
Makefile | 11 +-
arch/ia64/include/asm/io.h | 2 +-
arch/ia64/sn/kernel/iomv.c | 2 +-
drivers/ata/acard-ahci.c | 2 +-
drivers/ata/ahci.c | 2 +-
drivers/ata/ahci.h | 2 +-
drivers/ata/ata_piix.c | 2 +-
drivers/ata/libahci.c | 2 +-
drivers/ata/libata-core.c | 2 +-
drivers/ata/libata-eh.c | 2 +-
drivers/ata/libata-scsi.c | 9 +-
drivers/ata/libata-sff.c | 2 +-
drivers/ata/libata.h | 2 +-
drivers/ata/pata_pdc2027x.c | 2 +-
drivers/ata/pdc_adma.c | 2 +-
drivers/ata/sata_nv.c | 2 +-
drivers/ata/sata_promise.c | 2 +-
drivers/ata/sata_promise.h | 2 +-
drivers/ata/sata_qstor.c | 2 +-
drivers/ata/sata_sil.c | 2 +-
drivers/ata/sata_sis.c | 2 +-
drivers/ata/sata_svw.c | 2 +-
drivers/ata/sata_sx4.c | 2 +-
drivers/ata/sata_uli.c | 2 +-
drivers/ata/sata_via.c | 2 +-
drivers/ata/sata_vsc.c | 2 +-
drivers/mtd/nand/nand_base.c | 7 +-
drivers/net/phy/phy.c | 1 +
drivers/scsi/qla1280.c | 2 +-
drivers/scsi/scsi_scan.c | 7 +-
drivers/scsi/scsi_transport_fc.c | 18 +-
drivers/scsi/scsicam.c | 4 +-
drivers/usb/gadget/Kconfig | 2 +-
fs/debugfs/file.c | 2 +-
fs/debugfs/inode.c | 2 +-
fs/eventfd.c | 4 +-
fs/fs-writeback.c | 12 +-
fs/jbd2/transaction.c | 42 +-
fs/mpage.c | 1 +
fs/namei.c | 1 +
include/linux/ata.h | 2 +-
include/linux/debugfs.h | 2 +-
include/linux/libata.h | 2 +-
include/linux/mtd/nand.h | 2 +-
include/linux/mutex.h | 6 +-
include/linux/netdevice.h | 9 +-
include/linux/skbuff.h | 2 +-
include/net/sock.h | 9 +-
kernel/futex.c | 40 +-
kernel/irq/chip.c | 2 +-
kernel/irq/handle.c | 2 +-
kernel/irq/irqdesc.c | 2 +-
kernel/locking/mutex.c | 6 +-
lib/Kconfig.debug | 2 +-
lib/Kconfig.kgdb | 2 +-
net/core/datagram.c | 2 +-
net/core/sock.c | 7 +-
scripts/Makefile | 9 +-
scripts/check-lc_ctype.c | 11 -
124 files changed, 7469 insertions(+), 10511 deletions(-)
delete mode 100644 Documentation/DocBook/.gitignore
delete mode 100644 Documentation/DocBook/Makefile
delete mode 100644 Documentation/DocBook/filesystems.tmpl
delete mode 100644 Documentation/DocBook/kernel-hacking.tmpl
delete mode 100644 Documentation/DocBook/kernel-locking.tmpl
delete mode 100644 Documentation/DocBook/kgdb.tmpl
delete mode 100644 Documentation/DocBook/libata.tmpl
delete mode 100644 Documentation/DocBook/librs.tmpl
delete mode 100644 Documentation/DocBook/lsm.tmpl
delete mode 100644 Documentation/DocBook/mtdnand.tmpl
delete mode 100644 Documentation/DocBook/networking.tmpl
delete mode 100644 Documentation/DocBook/rapidio.tmpl
delete mode 100644 Documentation/DocBook/s390-drivers.tmpl
delete mode 100644 Documentation/DocBook/scsi.tmpl
delete mode 100644 Documentation/DocBook/sh.tmpl
delete mode 100644 Documentation/DocBook/stylesheet.xsl
delete mode 100644 Documentation/DocBook/w1.tmpl
delete mode 100644 Documentation/DocBook/z8530book.tmpl
delete mode 100644 Documentation/Makefile.sphinx
create mode 100644 Documentation/core-api/librs.rst
create mode 100644 Documentation/crypto/conf.py
create mode 100644 Documentation/dev-tools/kgdb.rst
delete mode 100644 Documentation/doc-guide/docbook.rst
create mode 100644 Documentation/driver-api/libata.rst
create mode 100644 Documentation/driver-api/mtdnand.rst
create mode 100644 Documentation/driver-api/rapidio.rst
create mode 100644 Documentation/driver-api/s390-drivers.rst
create mode 100644 Documentation/driver-api/scsi.rst
create mode 100644 Documentation/driver-api/w1.rst
create mode 100644 Documentation/filesystems/conf.py
create mode 100644 Documentation/filesystems/index.rst
create mode 100644 Documentation/kernel-hacking/conf.py
create mode 100644 Documentation/kernel-hacking/hacking.rst
create mode 100644 Documentation/kernel-hacking/index.rst
create mode 100644 Documentation/kernel-hacking/locking.rst
create mode 100644 Documentation/lsm.txt
create mode 100644 Documentation/networking/conf.py
create mode 100644 Documentation/networking/index.rst
create mode 100644 Documentation/networking/kapi.rst
create mode 100644 Documentation/networking/z8530book.rst
create mode 100644 Documentation/sh/conf.py
create mode 100644 Documentation/sh/index.rst
create mode 100644 Documentation/sound/conf.py
delete mode 100755 Documentation/sphinx/tmplcvt
delete mode 100644 scripts/check-lc_ctype.c
--
2.9.3
[toc] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:20 +0200 |
| Subject | [PATCH v2 18/53] docs-rst: filesystems: use c domain references where needed |
| Message-ID | <tHJCi-5vb-15@gated-at.bofh.it> |
| In reply to | #1642478 |
Instead of just mention the function names, use cross-references
to the kernel-doc tags where pertinent.
While not all function documentation is included here, I
double-checked that all functions mentioned there still
exists.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/filesystems/index.rst | 76 +++++++++++++++++++------------------
1 file changed, 40 insertions(+), 36 deletions(-)
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 3bc82e9d22f0..148becd91cba 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -125,27 +125,27 @@ Details
The journalling layer is easy to use. You need to first of all create a
journal_t data structure. There are two calls to do this dependent on
how you decide to allocate the physical media on which the journal
-resides. The jbd2_journal_init_inode() call is for journals stored in
-filesystem inodes, or the jbd2_journal_init_dev() call can be used
+resides. The :c:func:`jbd2_journal_init_inode` call is for journals stored in
+filesystem inodes, or the :c:func:`jbd2_journal_init_dev` call can be used
for journal stored on a raw device (in a continuous range of blocks). A
journal_t is a typedef for a struct pointer, so when you are finally
-finished make sure you call jbd2_journal_destroy() on it to free up
+finished make sure you call :c:func:`jbd2_journal_destroy` on it to free up
any used kernel memory.
Once you have got your journal_t object you need to 'mount' or load the
journal file. The journalling layer expects the space for the journal
was already allocated and initialized properly by the userspace tools.
-When loading the journal you must call jbd2_journal_load() to process
+When loading the journal you must call :c:func:`jbd2_journal_load` to process
journal contents. If the client file system detects the journal contents
does not need to be processed (or even need not have valid contents), it
-may call jbd2_journal_wipe() to clear the journal contents before
-calling jbd2_journal_load().
+may call :c:func:`jbd2_journal_wipe` to clear the journal contents before
+calling :c:func:`jbd2_journal_load`.
Note that jbd2_journal_wipe(..,0) calls
-jbd2_journal_skip_recovery() for you if it detects any outstanding
-transactions in the journal and similarly jbd2_journal_load() will
-call jbd2_journal_recover() if necessary. I would advise reading
-ext4_load_journal() in fs/ext4/super.c for examples on this stage.
+:c:func:`jbd2_journal_skip_recovery` for you if it detects any outstanding
+transactions in the journal and similarly :c:func:`jbd2_journal_load` will
+call :c:func:`jbd2_journal_recover` if necessary. I would advise reading
+:c:func:`ext4_load_journal` in fs/ext4/super.c for examples on this stage.
Now you can go ahead and start modifying the underlying filesystem.
Almost.
@@ -154,54 +154,57 @@ You still need to actually journal your filesystem changes, this is done
by wrapping them into transactions. Additionally you also need to wrap
the modification of each of the buffers with calls to the journal layer,
so it knows what the modifications you are actually making are. To do
-this use jbd2_journal_start() which returns a transaction handle.
+this use :c:func:`jbd2_journal_start` which returns a transaction handle.
-jbd2_journal_start() and its counterpart jbd2_journal_stop(), which
-indicates the end of a transaction are nestable calls, so you can
+:c:func:`jbd2_journal_start` and its counterpart :c:func:`jbd2_journal_stop`,
+which indicates the end of a transaction are nestable calls, so you can
reenter a transaction if necessary, but remember you must call
-jbd2_journal_stop() the same number of times as jbd2_journal_start()
-before the transaction is completed (or more accurately leaves the
-update phase). Ext4/VFS makes use of this feature to simplify handling
-of inode dirtying, quota support, etc.
+:c:func:`jbd2_journal_stop` the same number of times as
+:c:func:`jbd2_journal_start` before the transaction is completed (or more
+accurately leaves the update phase). Ext4/VFS makes use of this feature to
+simplify handling of inode dirtying, quota support, etc.
Inside each transaction you need to wrap the modifications to the
individual buffers (blocks). Before you start to modify a buffer you
-need to call jbd2_journal_get_{create,write,undo}_access() as
-appropriate, this allows the journalling layer to copy the unmodified
+need to call :c:func:`jbd2_journal_get_create_access()` /
+:c:func:`jbd2_journal_get_write_access()` /
+:c:func:`jbd2_journal_get_undo_access()` as appropriate, this allows the
+journalling layer to copy the unmodified
data if it needs to. After all the buffer may be part of a previously
uncommitted transaction. At this point you are at last ready to modify a
buffer, and once you are have done so you need to call
-jbd2_journal_dirty_{meta,}data(). Or if you've asked for access to a
+:c:func:`jbd2_journal_dirty_metadata`. Or if you've asked for access to a
buffer you now know is now longer required to be pushed back on the
-device you can call jbd2_journal_forget() in much the same way as you
-might have used bforget() in the past.
+device you can call :c:func:`jbd2_journal_forget` in much the same way as you
+might have used :c:func:`bforget` in the past.
-A jbd2_journal_flush() may be called at any time to commit and
+A :c:func:`jbd2_journal_flush` may be called at any time to commit and
checkpoint all your transactions.
-Then at umount time , in your put_super() you can then call
-jbd2_journal_destroy() to clean up your in-core journal object.
+Then at umount time , in your :c:func:`put_super` you can then call
+:c:func:`jbd2_journal_destroy` to clean up your in-core journal object.
Unfortunately there a couple of ways the journal layer can cause a
deadlock. The first thing to note is that each task can only have a
single outstanding transaction at any one time, remember nothing commits
-until the outermost jbd2_journal_stop(). This means you must complete
+until the outermost :c:func:`jbd2_journal_stop`. This means you must complete
the transaction at the end of each file/inode/address etc. operation you
perform, so that the journalling system isn't re-entered on another
journal. Since transactions can't be nested/batched across differing
journals, and another filesystem other than yours (say ext4) may be
modified in a later syscall.
-The second case to bear in mind is that jbd2_journal_start() can block
+The second case to bear in mind is that :c:func:`jbd2_journal_start` can block
if there isn't enough space in the journal for your transaction (based
on the passed nblocks param) - when it blocks it merely(!) needs to wait
for transactions to complete and be committed from other tasks, so
-essentially we are waiting for jbd2_journal_stop(). So to avoid
-deadlocks you must treat jbd2_journal_start/stop() as if they were
-semaphores and include them in your semaphore ordering rules to prevent
-deadlocks. Note that jbd2_journal_extend() has similar blocking
-behaviour to jbd2_journal_start() so you can deadlock here just as
-easily as on jbd2_journal_start().
+essentially we are waiting for :c:func:`jbd2_journal_stop`. So to avoid
+deadlocks you must treat :c:func:`jbd2_journal_start` /
+:c:func:`jbd2_journal_stop` as if they were semaphores and include them in
+your semaphore ordering rules to prevent
+deadlocks. Note that :c:func:`jbd2_journal_extend` has similar blocking
+behaviour to :c:func:`jbd2_journal_start` so you can deadlock here just as
+easily as on :c:func:`jbd2_journal_start`.
Try to reserve the right number of blocks the first time. ;-). This will
be the maximum number of blocks you are going to touch in this
@@ -222,13 +225,14 @@ With journal commit callbacks you can ask the journalling layer to call
a callback function when the transaction is finally committed to disk,
so that you can do some of your own management. You ask the journalling
layer for calling the callback by simply setting
-journal->j_commit_callback function pointer and that function is
+``journal->j_commit_callback`` function pointer and that function is
called after each transaction commit. You can also use
-transaction->t_private_list for attaching entries to a transaction
+``transaction->t_private_list`` for attaching entries to a transaction
that need processing when the transaction commits.
JBD2 also provides a way to block all transaction updates via
-jbd2_journal_{un,}lock_updates(). Ext4 uses this when it wants a
+:c:func:`jbd2_journal_lock_updates()` /
+:c:func:`jbd2_journal_unlock_updates()`. Ext4 uses this when it wants a
window with a clean and stable fs for a moment. E.g.
::
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:20 +0200 |
| Subject | [PATCH v2 06/53] locking.rst: add captions to two tables |
| Message-ID | <tHJCi-5vb-23@gated-at.bofh.it> |
| In reply to | #1642478 |
Those tables have a "caption" at the end, but ReST actually expects it on a different way. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/kernel-hacking/locking.rst | 66 ++++++++++++++++---------------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst index 17774b1f7587..b70c2c4eb147 100644 --- a/Documentation/kernel-hacking/locking.rst +++ b/Documentation/kernel-hacking/locking.rst @@ -29,43 +29,45 @@ In a normal program, you can increment a counter like so: This is what they would expect to happen: -+------------------------------------+------------------------------------+ -| Instance 1 | Instance 2 | -+====================================+====================================+ -| read very_important_count (5) | | -+------------------------------------+------------------------------------+ -| add 1 (6) | | -+------------------------------------+------------------------------------+ -| write very_important_count (6) | | -+------------------------------------+------------------------------------+ -| | read very_important_count (6) | -+------------------------------------+------------------------------------+ -| | add 1 (7) | -+------------------------------------+------------------------------------+ -| | write very_important_count (7) | -+------------------------------------+------------------------------------+ -Table: Expected Results +.. table:: Expected Results + + +------------------------------------+------------------------------------+ + | Instance 1 | Instance 2 | + +====================================+====================================+ + | read very_important_count (5) | | + +------------------------------------+------------------------------------+ + | add 1 (6) | | + +------------------------------------+------------------------------------+ + | write very_important_count (6) | | + +------------------------------------+------------------------------------+ + | | read very_important_count (6) | + +------------------------------------+------------------------------------+ + | | add 1 (7) | + +------------------------------------+------------------------------------+ + | | write very_important_count (7) | + +------------------------------------+------------------------------------+ This is what might happen: -+------------------------------------+------------------------------------+ -| Instance 1 | Instance 2 | -+====================================+====================================+ -| read very_important_count (5) | | -+------------------------------------+------------------------------------+ -| | read very_important_count (5) | -+------------------------------------+------------------------------------+ -| add 1 (6) | | -+------------------------------------+------------------------------------+ -| | add 1 (6) | -+------------------------------------+------------------------------------+ -| write very_important_count (6) | | -+------------------------------------+------------------------------------+ -| | write very_important_count (6) | -+------------------------------------+------------------------------------+ +.. table:: Possible Results + + +------------------------------------+------------------------------------+ + | Instance 1 | Instance 2 | + +====================================+====================================+ + | read very_important_count (5) | | + +------------------------------------+------------------------------------+ + | | read very_important_count (5) | + +------------------------------------+------------------------------------+ + | add 1 (6) | | + +------------------------------------+------------------------------------+ + | | add 1 (6) | + +------------------------------------+------------------------------------+ + | write very_important_count (6) | | + +------------------------------------+------------------------------------+ + | | write very_important_count (6) | + +------------------------------------+------------------------------------+ -Table: Possible Results Race Conditions and Critical Regions ------------------------------------ -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:20 +0200 |
| Subject | [PATCH v2 33/53] scsi: fix some kernel-doc markups |
| Message-ID | <tHJCi-5vb-25@gated-at.bofh.it> |
| In reply to | #1642478 |
Sphinx is very pedantic with regards to ident/spacing. Fix some kernel-doc markups in order to solve those errors/warnings: ./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string. ./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string. ./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string. ./drivers/scsi/scsi_scan.c:1056: ERROR: Unexpected indentation. ./drivers/scsi/scsi_scan.c:1057: WARNING: Block quote ends without a blank line; unexpected unindent. ./drivers/scsi/scsi_transport_fc.c:2918: ERROR: Unexpected indentation. ./drivers/scsi/scsi_transport_fc.c:2921: WARNING: Block quote ends without a blank line; unexpected unindent. ./drivers/scsi/scsi_transport_fc.c:2922: WARNING: Enumerated list ends without a blank line; unexpected unindent. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- drivers/scsi/scsi_scan.c | 7 ++++--- drivers/scsi/scsi_transport_fc.c | 18 ++++++++++-------- drivers/scsi/scsicam.c | 4 ++-- 3 files changed, 16 insertions(+), 13 deletions(-) diff --git a/drivers/scsi/scsi_scan.c b/drivers/scsi/scsi_scan.c index 6f7128f49c30..69979574004f 100644 --- a/drivers/scsi/scsi_scan.c +++ b/drivers/scsi/scsi_scan.c @@ -1051,10 +1051,11 @@ static unsigned char *scsi_inq_str(unsigned char *buf, unsigned char *inq, * allocate and set it up by calling scsi_add_lun. * * Return: - * SCSI_SCAN_NO_RESPONSE: could not allocate or setup a scsi_device - * SCSI_SCAN_TARGET_PRESENT: target responded, but no device is + * + * - SCSI_SCAN_NO_RESPONSE: could not allocate or setup a scsi_device + * - SCSI_SCAN_TARGET_PRESENT: target responded, but no device is * attached at the LUN - * SCSI_SCAN_LUN_PRESENT: a new scsi_device was allocated and initialized + * - SCSI_SCAN_LUN_PRESENT: a new scsi_device was allocated and initialized **/ static int scsi_probe_and_add_lun(struct scsi_target *starget, u64 lun, int *bflagsp, diff --git a/drivers/scsi/scsi_transport_fc.c b/drivers/scsi/scsi_transport_fc.c index d4cf32d55546..1df77453f6b6 100644 --- a/drivers/scsi/scsi_transport_fc.c +++ b/drivers/scsi/scsi_transport_fc.c @@ -2914,16 +2914,18 @@ EXPORT_SYMBOL(fc_remote_port_add); * port is no longer part of the topology. Note: Although a port * may no longer be part of the topology, it may persist in the remote * ports displayed by the fc_host. We do this under 2 conditions: + * * 1) If the port was a scsi target, we delay its deletion by "blocking" it. - * This allows the port to temporarily disappear, then reappear without - * disrupting the SCSI device tree attached to it. During the "blocked" - * period the port will still exist. + * This allows the port to temporarily disappear, then reappear without + * disrupting the SCSI device tree attached to it. During the "blocked" + * period the port will still exist. + * * 2) If the port was a scsi target and disappears for longer than we - * expect, we'll delete the port and the tear down the SCSI device tree - * attached to it. However, we want to semi-persist the target id assigned - * to that port if it eventually does exist. The port structure will - * remain (although with minimal information) so that the target id - * bindings remails. + * expect, we'll delete the port and the tear down the SCSI device tree + * attached to it. However, we want to semi-persist the target id assigned + * to that port if it eventually does exist. The port structure will + * remain (although with minimal information) so that the target id + * bindings remails. * * If the remote port is not an FCP Target, it will be fully torn down * and deallocated, including the fc_remote_port class device. diff --git a/drivers/scsi/scsicam.c b/drivers/scsi/scsicam.c index 910f4a7a3924..31273468589c 100644 --- a/drivers/scsi/scsicam.c +++ b/drivers/scsi/scsicam.c @@ -116,8 +116,8 @@ EXPORT_SYMBOL(scsicam_bios_param); * @hds: put heads here * @secs: put sectors here * - * Description: determine the BIOS mapping/geometry used to create the partition - * table, storing the results in *cyls, *hds, and *secs + * Determine the BIOS mapping/geometry used to create the partition + * table, storing the results in @cyls, @hds, and @secs * * Returns: -1 on failure, 0 on success. */ -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:20 +0200 |
| Subject | [PATCH v2 17/53] docs-rst: convert filesystems book to ReST |
| Message-ID | <tHJCi-5vb-31@gated-at.bofh.it> |
| In reply to | #1642478 |
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DocBook/Makefile | 2 +-
Documentation/DocBook/filesystems.tmpl | 381 ---------------------------------
Documentation/conf.py | 2 +
Documentation/filesystems/conf.py | 10 +
Documentation/filesystems/index.rst | 314 +++++++++++++++++++++++++++
Documentation/index.rst | 1 +
6 files changed, 328 insertions(+), 382 deletions(-)
delete mode 100644 Documentation/DocBook/filesystems.tmpl
create mode 100644 Documentation/filesystems/conf.py
create mode 100644 Documentation/filesystems/index.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index b9d2b88b9905..2f767e30b59e 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -8,7 +8,7 @@
DOCBOOKS := z8530book.xml \
networking.xml \
- filesystems.xml lsm.xml \
+ lsm.xml \
libata.xml mtdnand.xml librs.xml rapidio.xml \
s390-drivers.xml scsi.xml \
sh.xml w1.xml
diff --git a/Documentation/DocBook/filesystems.tmpl b/Documentation/DocBook/filesystems.tmpl
deleted file mode 100644
index 6006b6358c86..000000000000
--- a/Documentation/DocBook/filesystems.tmpl
+++ /dev/null
@@ -1,381 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Linux-filesystems-API">
- <bookinfo>
- <title>Linux Filesystems API</title>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="vfs">
- <title>The Linux VFS</title>
- <sect1 id="the_filesystem_types"><title>The Filesystem types</title>
-!Iinclude/linux/fs.h
- </sect1>
- <sect1 id="the_directory_cache"><title>The Directory Cache</title>
-!Efs/dcache.c
-!Iinclude/linux/dcache.h
- </sect1>
- <sect1 id="inode_handling"><title>Inode Handling</title>
-!Efs/inode.c
-!Efs/bad_inode.c
- </sect1>
- <sect1 id="registration_and_superblocks"><title>Registration and Superblocks</title>
-!Efs/super.c
- </sect1>
- <sect1 id="file_locks"><title>File Locks</title>
-!Efs/locks.c
-!Ifs/locks.c
- </sect1>
- <sect1 id="other_functions"><title>Other Functions</title>
-!Efs/mpage.c
-!Efs/namei.c
-!Efs/buffer.c
-!Eblock/bio.c
-!Efs/seq_file.c
-!Efs/filesystems.c
-!Efs/fs-writeback.c
-!Efs/block_dev.c
- </sect1>
- </chapter>
-
- <chapter id="proc">
- <title>The proc filesystem</title>
-
- <sect1 id="sysctl_interface"><title>sysctl interface</title>
-!Ekernel/sysctl.c
- </sect1>
-
- <sect1 id="proc_filesystem_interface"><title>proc filesystem interface</title>
-!Ifs/proc/base.c
- </sect1>
- </chapter>
-
- <chapter id="fs_events">
- <title>Events based on file descriptors</title>
-!Efs/eventfd.c
- </chapter>
-
- <chapter id="sysfs">
- <title>The Filesystem for Exporting Kernel Objects</title>
-!Efs/sysfs/file.c
-!Efs/sysfs/symlink.c
- </chapter>
-
- <chapter id="debugfs">
- <title>The debugfs filesystem</title>
-
- <sect1 id="debugfs_interface"><title>debugfs interface</title>
-!Efs/debugfs/inode.c
-!Efs/debugfs/file.c
- </sect1>
- </chapter>
-
- <chapter id="LinuxJDBAPI">
- <chapterinfo>
- <title>The Linux Journalling API</title>
-
- <authorgroup>
- <author>
- <firstname>Roger</firstname>
- <surname>Gammans</surname>
- <affiliation>
- <address>
- <email>rgammans@computer-surgery.co.uk</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <authorgroup>
- <author>
- <firstname>Stephen</firstname>
- <surname>Tweedie</surname>
- <affiliation>
- <address>
- <email>sct@redhat.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2002</year>
- <holder>Roger Gammans</holder>
- </copyright>
- </chapterinfo>
-
- <title>The Linux Journalling API</title>
-
- <sect1 id="journaling_overview">
- <title>Overview</title>
- <sect2 id="journaling_details">
- <title>Details</title>
-<para>
-The journalling layer is easy to use. You need to
-first of all create a journal_t data structure. There are
-two calls to do this dependent on how you decide to allocate the physical
-media on which the journal resides. The jbd2_journal_init_inode() call
-is for journals stored in filesystem inodes, or the jbd2_journal_init_dev()
-call can be used for journal stored on a raw device (in a continuous range
-of blocks). A journal_t is a typedef for a struct pointer, so when
-you are finally finished make sure you call jbd2_journal_destroy() on it
-to free up any used kernel memory.
-</para>
-
-<para>
-Once you have got your journal_t object you need to 'mount' or load the journal
-file. The journalling layer expects the space for the journal was already
-allocated and initialized properly by the userspace tools. When loading the
-journal you must call jbd2_journal_load() to process journal contents. If the
-client file system detects the journal contents does not need to be processed
-(or even need not have valid contents), it may call jbd2_journal_wipe() to
-clear the journal contents before calling jbd2_journal_load().
-</para>
-
-<para>
-Note that jbd2_journal_wipe(..,0) calls jbd2_journal_skip_recovery() for you if
-it detects any outstanding transactions in the journal and similarly
-jbd2_journal_load() will call jbd2_journal_recover() if necessary. I would
-advise reading ext4_load_journal() in fs/ext4/super.c for examples on this
-stage.
-</para>
-
-<para>
-Now you can go ahead and start modifying the underlying
-filesystem. Almost.
-</para>
-
-<para>
-
-You still need to actually journal your filesystem changes, this
-is done by wrapping them into transactions. Additionally you
-also need to wrap the modification of each of the buffers
-with calls to the journal layer, so it knows what the modifications
-you are actually making are. To do this use jbd2_journal_start() which
-returns a transaction handle.
-</para>
-
-<para>
-jbd2_journal_start()
-and its counterpart jbd2_journal_stop(), which indicates the end of a
-transaction are nestable calls, so you can reenter a transaction if necessary,
-but remember you must call jbd2_journal_stop() the same number of times as
-jbd2_journal_start() before the transaction is completed (or more accurately
-leaves the update phase). Ext4/VFS makes use of this feature to simplify
-handling of inode dirtying, quota support, etc.
-</para>
-
-<para>
-Inside each transaction you need to wrap the modifications to the
-individual buffers (blocks). Before you start to modify a buffer you
-need to call jbd2_journal_get_{create,write,undo}_access() as appropriate,
-this allows the journalling layer to copy the unmodified data if it
-needs to. After all the buffer may be part of a previously uncommitted
-transaction.
-At this point you are at last ready to modify a buffer, and once
-you are have done so you need to call jbd2_journal_dirty_{meta,}data().
-Or if you've asked for access to a buffer you now know is now longer
-required to be pushed back on the device you can call jbd2_journal_forget()
-in much the same way as you might have used bforget() in the past.
-</para>
-
-<para>
-A jbd2_journal_flush() may be called at any time to commit and checkpoint
-all your transactions.
-</para>
-
-<para>
-Then at umount time , in your put_super() you can then call jbd2_journal_destroy()
-to clean up your in-core journal object.
-</para>
-
-<para>
-Unfortunately there a couple of ways the journal layer can cause a deadlock.
-The first thing to note is that each task can only have
-a single outstanding transaction at any one time, remember nothing
-commits until the outermost jbd2_journal_stop(). This means
-you must complete the transaction at the end of each file/inode/address
-etc. operation you perform, so that the journalling system isn't re-entered
-on another journal. Since transactions can't be nested/batched
-across differing journals, and another filesystem other than
-yours (say ext4) may be modified in a later syscall.
-</para>
-
-<para>
-The second case to bear in mind is that jbd2_journal_start() can
-block if there isn't enough space in the journal for your transaction
-(based on the passed nblocks param) - when it blocks it merely(!) needs to
-wait for transactions to complete and be committed from other tasks,
-so essentially we are waiting for jbd2_journal_stop(). So to avoid
-deadlocks you must treat jbd2_journal_start/stop() as if they
-were semaphores and include them in your semaphore ordering rules to prevent
-deadlocks. Note that jbd2_journal_extend() has similar blocking behaviour to
-jbd2_journal_start() so you can deadlock here just as easily as on
-jbd2_journal_start().
-</para>
-
-<para>
-Try to reserve the right number of blocks the first time. ;-). This will
-be the maximum number of blocks you are going to touch in this transaction.
-I advise having a look at at least ext4_jbd.h to see the basis on which
-ext4 uses to make these decisions.
-</para>
-
-<para>
-Another wriggle to watch out for is your on-disk block allocation strategy.
-Why? Because, if you do a delete, you need to ensure you haven't reused any
-of the freed blocks until the transaction freeing these blocks commits. If you
-reused these blocks and crash happens, there is no way to restore the contents
-of the reallocated blocks at the end of the last fully committed transaction.
-
-One simple way of doing this is to mark blocks as free in internal in-memory
-block allocation structures only after the transaction freeing them commits.
-Ext4 uses journal commit callback for this purpose.
-</para>
-
-<para>
-With journal commit callbacks you can ask the journalling layer to call a
-callback function when the transaction is finally committed to disk, so that
-you can do some of your own management. You ask the journalling layer for
-calling the callback by simply setting journal->j_commit_callback function
-pointer and that function is called after each transaction commit. You can also
-use transaction->t_private_list for attaching entries to a transaction that
-need processing when the transaction commits.
-</para>
-
-<para>
-JBD2 also provides a way to block all transaction updates via
-jbd2_journal_{un,}lock_updates(). Ext4 uses this when it wants a window with a
-clean and stable fs for a moment. E.g.
-</para>
-
-<programlisting>
-
- jbd2_journal_lock_updates() //stop new stuff happening..
- jbd2_journal_flush() // checkpoint everything.
- ..do stuff on stable fs
- jbd2_journal_unlock_updates() // carry on with filesystem use.
-</programlisting>
-
-<para>
-The opportunities for abuse and DOS attacks with this should be obvious,
-if you allow unprivileged userspace to trigger codepaths containing these
-calls.
-</para>
-
- </sect2>
-
- <sect2 id="jbd_summary">
- <title>Summary</title>
-<para>
-Using the journal is a matter of wrapping the different context changes,
-being each mount, each modification (transaction) and each changed buffer
-to tell the journalling layer about them.
-</para>
-
- </sect2>
-
- </sect1>
-
- <sect1 id="data_types">
- <title>Data Types</title>
- <para>
- The journalling layer uses typedefs to 'hide' the concrete definitions
- of the structures used. As a client of the JBD2 layer you can
- just rely on the using the pointer as a magic cookie of some sort.
-
- Obviously the hiding is not enforced as this is 'C'.
- </para>
- <sect2 id="structures"><title>Structures</title>
-!Iinclude/linux/jbd2.h
- </sect2>
- </sect1>
-
- <sect1 id="functions">
- <title>Functions</title>
- <para>
- The functions here are split into two groups those that
- affect a journal as a whole, and those which are used to
- manage transactions
- </para>
- <sect2 id="journal_level"><title>Journal Level</title>
-!Efs/jbd2/journal.c
-!Ifs/jbd2/recovery.c
- </sect2>
- <sect2 id="transaction_level"><title>Transasction Level</title>
-!Efs/jbd2/transaction.c
- </sect2>
- </sect1>
- <sect1 id="see_also">
- <title>See also</title>
- <para>
- <citation>
- <ulink url="http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz">
- Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen Tweedie
- </ulink>
- </citation>
- </para>
- <para>
- <citation>
- <ulink url="http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html">
- Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen Tweedie
- </ulink>
- </citation>
- </para>
- </sect1>
-
- </chapter>
-
- <chapter id="splice">
- <title>splice API</title>
- <para>
- splice is a method for moving blocks of data around inside the
- kernel, without continually transferring them between the kernel
- and user space.
- </para>
-!Ffs/splice.c
- </chapter>
-
- <chapter id="pipes">
- <title>pipes API</title>
- <para>
- Pipe interfaces are all for in-kernel (builtin image) use.
- They are not exported for use by modules.
- </para>
-!Iinclude/linux/pipe_fs_i.h
-!Ffs/pipe.c
- </chapter>
-
-</book>
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 2e215477edf5..ad9a4781b330 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -359,6 +359,8 @@ latex_documents = [
'The kernel development community', 'manual'),
('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',
'The kernel development community', 'manual'),
+ ('filesystems/index', 'filesystems.tex', 'Linux Filesystems API',
+ 'The kernel development community', 'manual'),
('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
'The kernel development community', 'manual'),
('input/index', 'linux-input.tex', 'The Linux input driver subsystem',
diff --git a/Documentation/filesystems/conf.py b/Documentation/filesystems/conf.py
new file mode 100644
index 000000000000..ea44172af5c4
--- /dev/null
+++ b/Documentation/filesystems/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Linux Filesystems API"
+
+tags.add("subproject")
+
+latex_documents = [
+ ('index', 'filesystems.tex', project,
+ 'The kernel development community', 'manual'),
+]
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
new file mode 100644
index 000000000000..3bc82e9d22f0
--- /dev/null
+++ b/Documentation/filesystems/index.rst
@@ -0,0 +1,314 @@
+=====================
+Linux Filesystems API
+=====================
+
+The Linux VFS
+=============
+
+The Filesystem types
+--------------------
+
+.. kernel-doc:: include/linux/fs.h
+ :internal:
+
+The Directory Cache
+-------------------
+
+.. kernel-doc:: fs/dcache.c
+ :export:
+
+.. kernel-doc:: include/linux/dcache.h
+ :internal:
+
+Inode Handling
+--------------
+
+.. kernel-doc:: fs/inode.c
+ :export:
+
+.. kernel-doc:: fs/bad_inode.c
+ :export:
+
+Registration and Superblocks
+----------------------------
+
+.. kernel-doc:: fs/super.c
+ :export:
+
+File Locks
+----------
+
+.. kernel-doc:: fs/locks.c
+ :export:
+
+.. kernel-doc:: fs/locks.c
+ :internal:
+
+Other Functions
+---------------
+
+.. kernel-doc:: fs/mpage.c
+ :export:
+
+.. kernel-doc:: fs/namei.c
+ :export:
+
+.. kernel-doc:: fs/buffer.c
+ :export:
+
+.. kernel-doc:: block/bio.c
+ :export:
+
+.. kernel-doc:: fs/seq_file.c
+ :export:
+
+.. kernel-doc:: fs/filesystems.c
+ :export:
+
+.. kernel-doc:: fs/fs-writeback.c
+ :export:
+
+.. kernel-doc:: fs/block_dev.c
+ :export:
+
+The proc filesystem
+===================
+
+sysctl interface
+----------------
+
+.. kernel-doc:: kernel/sysctl.c
+ :export:
+
+proc filesystem interface
+-------------------------
+
+.. kernel-doc:: fs/proc/base.c
+ :internal:
+
+Events based on file descriptors
+================================
+
+.. kernel-doc:: fs/eventfd.c
+ :export:
+
+The Filesystem for Exporting Kernel Objects
+===========================================
+
+.. kernel-doc:: fs/sysfs/file.c
+ :export:
+
+.. kernel-doc:: fs/sysfs/symlink.c
+ :export:
+
+The debugfs filesystem
+======================
+
+debugfs interface
+-----------------
+
+.. kernel-doc:: fs/debugfs/inode.c
+ :export:
+
+.. kernel-doc:: fs/debugfs/file.c
+ :export:
+
+The Linux Journalling API
+=========================
+
+Overview
+--------
+
+Details
+~~~~~~~
+
+The journalling layer is easy to use. You need to first of all create a
+journal_t data structure. There are two calls to do this dependent on
+how you decide to allocate the physical media on which the journal
+resides. The jbd2_journal_init_inode() call is for journals stored in
+filesystem inodes, or the jbd2_journal_init_dev() call can be used
+for journal stored on a raw device (in a continuous range of blocks). A
+journal_t is a typedef for a struct pointer, so when you are finally
+finished make sure you call jbd2_journal_destroy() on it to free up
+any used kernel memory.
+
+Once you have got your journal_t object you need to 'mount' or load the
+journal file. The journalling layer expects the space for the journal
+was already allocated and initialized properly by the userspace tools.
+When loading the journal you must call jbd2_journal_load() to process
+journal contents. If the client file system detects the journal contents
+does not need to be processed (or even need not have valid contents), it
+may call jbd2_journal_wipe() to clear the journal contents before
+calling jbd2_journal_load().
+
+Note that jbd2_journal_wipe(..,0) calls
+jbd2_journal_skip_recovery() for you if it detects any outstanding
+transactions in the journal and similarly jbd2_journal_load() will
+call jbd2_journal_recover() if necessary. I would advise reading
+ext4_load_journal() in fs/ext4/super.c for examples on this stage.
+
+Now you can go ahead and start modifying the underlying filesystem.
+Almost.
+
+You still need to actually journal your filesystem changes, this is done
+by wrapping them into transactions. Additionally you also need to wrap
+the modification of each of the buffers with calls to the journal layer,
+so it knows what the modifications you are actually making are. To do
+this use jbd2_journal_start() which returns a transaction handle.
+
+jbd2_journal_start() and its counterpart jbd2_journal_stop(), which
+indicates the end of a transaction are nestable calls, so you can
+reenter a transaction if necessary, but remember you must call
+jbd2_journal_stop() the same number of times as jbd2_journal_start()
+before the transaction is completed (or more accurately leaves the
+update phase). Ext4/VFS makes use of this feature to simplify handling
+of inode dirtying, quota support, etc.
+
+Inside each transaction you need to wrap the modifications to the
+individual buffers (blocks). Before you start to modify a buffer you
+need to call jbd2_journal_get_{create,write,undo}_access() as
+appropriate, this allows the journalling layer to copy the unmodified
+data if it needs to. After all the buffer may be part of a previously
+uncommitted transaction. At this point you are at last ready to modify a
+buffer, and once you are have done so you need to call
+jbd2_journal_dirty_{meta,}data(). Or if you've asked for access to a
+buffer you now know is now longer required to be pushed back on the
+device you can call jbd2_journal_forget() in much the same way as you
+might have used bforget() in the past.
+
+A jbd2_journal_flush() may be called at any time to commit and
+checkpoint all your transactions.
+
+Then at umount time , in your put_super() you can then call
+jbd2_journal_destroy() to clean up your in-core journal object.
+
+Unfortunately there a couple of ways the journal layer can cause a
+deadlock. The first thing to note is that each task can only have a
+single outstanding transaction at any one time, remember nothing commits
+until the outermost jbd2_journal_stop(). This means you must complete
+the transaction at the end of each file/inode/address etc. operation you
+perform, so that the journalling system isn't re-entered on another
+journal. Since transactions can't be nested/batched across differing
+journals, and another filesystem other than yours (say ext4) may be
+modified in a later syscall.
+
+The second case to bear in mind is that jbd2_journal_start() can block
+if there isn't enough space in the journal for your transaction (based
+on the passed nblocks param) - when it blocks it merely(!) needs to wait
+for transactions to complete and be committed from other tasks, so
+essentially we are waiting for jbd2_journal_stop(). So to avoid
+deadlocks you must treat jbd2_journal_start/stop() as if they were
+semaphores and include them in your semaphore ordering rules to prevent
+deadlocks. Note that jbd2_journal_extend() has similar blocking
+behaviour to jbd2_journal_start() so you can deadlock here just as
+easily as on jbd2_journal_start().
+
+Try to reserve the right number of blocks the first time. ;-). This will
+be the maximum number of blocks you are going to touch in this
+transaction. I advise having a look at at least ext4_jbd.h to see the
+basis on which ext4 uses to make these decisions.
+
+Another wriggle to watch out for is your on-disk block allocation
+strategy. Why? Because, if you do a delete, you need to ensure you
+haven't reused any of the freed blocks until the transaction freeing
+these blocks commits. If you reused these blocks and crash happens,
+there is no way to restore the contents of the reallocated blocks at the
+end of the last fully committed transaction. One simple way of doing
+this is to mark blocks as free in internal in-memory block allocation
+structures only after the transaction freeing them commits. Ext4 uses
+journal commit callback for this purpose.
+
+With journal commit callbacks you can ask the journalling layer to call
+a callback function when the transaction is finally committed to disk,
+so that you can do some of your own management. You ask the journalling
+layer for calling the callback by simply setting
+journal->j_commit_callback function pointer and that function is
+called after each transaction commit. You can also use
+transaction->t_private_list for attaching entries to a transaction
+that need processing when the transaction commits.
+
+JBD2 also provides a way to block all transaction updates via
+jbd2_journal_{un,}lock_updates(). Ext4 uses this when it wants a
+window with a clean and stable fs for a moment. E.g.
+
+::
+
+
+ jbd2_journal_lock_updates() //stop new stuff happening..
+ jbd2_journal_flush() // checkpoint everything.
+ ..do stuff on stable fs
+ jbd2_journal_unlock_updates() // carry on with filesystem use.
+
+The opportunities for abuse and DOS attacks with this should be obvious,
+if you allow unprivileged userspace to trigger codepaths containing
+these calls.
+
+Summary
+~~~~~~~
+
+Using the journal is a matter of wrapping the different context changes,
+being each mount, each modification (transaction) and each changed
+buffer to tell the journalling layer about them.
+
+Data Types
+----------
+
+The journalling layer uses typedefs to 'hide' the concrete definitions
+of the structures used. As a client of the JBD2 layer you can just rely
+on the using the pointer as a magic cookie of some sort. Obviously the
+hiding is not enforced as this is 'C'.
+
+Structures
+~~~~~~~~~~
+
+.. kernel-doc:: include/linux/jbd2.h
+ :internal:
+
+Functions
+---------
+
+The functions here are split into two groups those that affect a journal
+as a whole, and those which are used to manage transactions
+
+Journal Level
+~~~~~~~~~~~~~
+
+.. kernel-doc:: fs/jbd2/journal.c
+ :export:
+
+.. kernel-doc:: fs/jbd2/recovery.c
+ :internal:
+
+Transasction Level
+~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: fs/jbd2/transaction.c
+ :export:
+
+See also
+--------
+
+`Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen
+Tweedie <http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz>`__
+
+`Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen
+Tweedie <http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html>`__
+
+splice API
+==========
+
+splice is a method for moving blocks of data around inside the kernel,
+without continually transferring them between the kernel and user space.
+
+.. kernel-doc:: fs/splice.c
+
+pipes API
+=========
+
+Pipe interfaces are all for in-kernel (builtin image) use. They are not
+exported for use by modules.
+
+.. kernel-doc:: include/linux/pipe_fs_i.h
+ :internal:
+
+.. kernel-doc:: fs/pipe.c
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 01a24486ea5f..dae365f3820e 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -73,6 +73,7 @@ needed).
security/index
sound/index
crypto/index
+ filesystems/index
Korean translations
-------------------
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:20 +0200 |
| Subject | [PATCH v2 39/53] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings |
| Message-ID | <tHJCi-5vb-27@gated-at.bofh.it> |
| In reply to | #1642478 |
./drivers/mtd/nand/nand_bbt.c:1: warning: no structured comments found
./include/linux/mtd/nand.h:785: ERROR: Unexpected indentation.
./drivers/mtd/nand/nand_base.c:449: WARNING: Definition list ends without a blank line; unexpected unindent.
./drivers/mtd/nand/nand_base.c:1161: ERROR: Unexpected indentation.
./drivers/mtd/nand/nand_base.c:1162: WARNING: Block quote ends without a blank line; unexpected unindent.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/mtdnand.rst | 3 ---
drivers/mtd/nand/nand_base.c | 7 +++++--
include/linux/mtd/nand.h | 2 +-
3 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/driver-api/mtdnand.rst b/Documentation/driver-api/mtdnand.rst
index 7c19795ebb4a..e9afa586d15e 100644
--- a/Documentation/driver-api/mtdnand.rst
+++ b/Documentation/driver-api/mtdnand.rst
@@ -970,9 +970,6 @@ hints" for an explanation.
.. kernel-doc:: drivers/mtd/nand/nand_base.c
:export:
-.. kernel-doc:: drivers/mtd/nand/nand_bbt.c
- :export:
-
.. kernel-doc:: drivers/mtd/nand/nand_ecc.c
:export:
diff --git a/drivers/mtd/nand/nand_base.c b/drivers/mtd/nand/nand_base.c
index b0524f8accb6..c8988c01e0d7 100644
--- a/drivers/mtd/nand/nand_base.c
+++ b/drivers/mtd/nand/nand_base.c
@@ -442,10 +442,12 @@ static int nand_default_block_markbad(struct mtd_info *mtd, loff_t ofs)
* specify how to write bad block markers to OOB (chip->block_markbad).
*
* We try operations in the following order:
+ *
* (1) erase the affected block, to allow OOB marker to be written cleanly
* (2) write bad block marker to OOB area of affected block (unless flag
* NAND_BBT_NO_OOB_BBM is present)
* (3) update the BBT
+ *
* Note that we retain the first error encountered in (2) or (3), finish the
* procedures, and dump the error in the end.
*/
@@ -1155,9 +1157,10 @@ int nand_reset(struct nand_chip *chip, int chipnr)
* @mtd: mtd info
* @ofs: offset to start unlock from
* @len: length to unlock
- * @invert: when = 0, unlock the range of blocks within the lower and
+ * @invert:
+ * - when = 0, unlock the range of blocks within the lower and
* upper boundary address
- * when = 1, unlock the range of blocks outside the boundaries
+ * - when = 1, unlock the range of blocks outside the boundaries
* of the lower and upper boundary address
*
* Returs unlock status.
diff --git a/include/linux/mtd/nand.h b/include/linux/mtd/nand.h
index 9591e0fbe5bd..3d5b20379ba3 100644
--- a/include/linux/mtd/nand.h
+++ b/include/linux/mtd/nand.h
@@ -779,7 +779,7 @@ nand_get_sdr_timings(const struct nand_data_interface *conf)
* Minimum amount of bit errors per @ecc_step_ds guaranteed
* to be correctable. If unknown, set to zero.
* @ecc_step_ds: [INTERN] ECC step required by the @ecc_strength_ds,
- * also from the datasheet. It is the recommended ECC step
+ * also from the datasheet. It is the recommended ECC step
* size, if known; if unknown, set to zero.
* @onfi_timing_mode_default: [INTERN] default ONFI timing mode. This field is
* set to the actually used ONFI mode if the chip is
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Boris Brezillon <boris.brezillon@free-electrons.com> |
|---|---|
| Date | 2017-05-16 15:20 +0200 |
| Subject | Re: [PATCH v2 39/53] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings |
| Message-ID | <tHKym-65Z-21@gated-at.bofh.it> |
| In reply to | #1642484 |
On Tue, 16 May 2017 09:16:31 -0300 Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > ./drivers/mtd/nand/nand_bbt.c:1: warning: no structured comments found > ./include/linux/mtd/nand.h:785: ERROR: Unexpected indentation. > ./drivers/mtd/nand/nand_base.c:449: WARNING: Definition list ends without a blank line; unexpected unindent. > ./drivers/mtd/nand/nand_base.c:1161: ERROR: Unexpected indentation. > ./drivers/mtd/nand/nand_base.c:1162: WARNING: Block quote ends without a blank line; unexpected unindent. > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Acked-by: Boris Brezillon <boris.brezillon@free-electrons.com> > --- > Documentation/driver-api/mtdnand.rst | 3 --- > drivers/mtd/nand/nand_base.c | 7 +++++-- > include/linux/mtd/nand.h | 2 +- > 3 files changed, 6 insertions(+), 6 deletions(-) > > diff --git a/Documentation/driver-api/mtdnand.rst b/Documentation/driver-api/mtdnand.rst > index 7c19795ebb4a..e9afa586d15e 100644 > --- a/Documentation/driver-api/mtdnand.rst > +++ b/Documentation/driver-api/mtdnand.rst > @@ -970,9 +970,6 @@ hints" for an explanation. > .. kernel-doc:: drivers/mtd/nand/nand_base.c > :export: > > -.. kernel-doc:: drivers/mtd/nand/nand_bbt.c > - :export: > - > .. kernel-doc:: drivers/mtd/nand/nand_ecc.c > :export: > > diff --git a/drivers/mtd/nand/nand_base.c b/drivers/mtd/nand/nand_base.c > index b0524f8accb6..c8988c01e0d7 100644 > --- a/drivers/mtd/nand/nand_base.c > +++ b/drivers/mtd/nand/nand_base.c > @@ -442,10 +442,12 @@ static int nand_default_block_markbad(struct mtd_info *mtd, loff_t ofs) > * specify how to write bad block markers to OOB (chip->block_markbad). > * > * We try operations in the following order: > + * > * (1) erase the affected block, to allow OOB marker to be written cleanly > * (2) write bad block marker to OOB area of affected block (unless flag > * NAND_BBT_NO_OOB_BBM is present) > * (3) update the BBT > + * > * Note that we retain the first error encountered in (2) or (3), finish the > * procedures, and dump the error in the end. > */ > @@ -1155,9 +1157,10 @@ int nand_reset(struct nand_chip *chip, int chipnr) > * @mtd: mtd info > * @ofs: offset to start unlock from > * @len: length to unlock > - * @invert: when = 0, unlock the range of blocks within the lower and > + * @invert: > + * - when = 0, unlock the range of blocks within the lower and > * upper boundary address > - * when = 1, unlock the range of blocks outside the boundaries > + * - when = 1, unlock the range of blocks outside the boundaries > * of the lower and upper boundary address > * > * Returs unlock status. > diff --git a/include/linux/mtd/nand.h b/include/linux/mtd/nand.h > index 9591e0fbe5bd..3d5b20379ba3 100644 > --- a/include/linux/mtd/nand.h > +++ b/include/linux/mtd/nand.h > @@ -779,7 +779,7 @@ nand_get_sdr_timings(const struct nand_data_interface *conf) > * Minimum amount of bit errors per @ecc_step_ds guaranteed > * to be correctable. If unknown, set to zero. > * @ecc_step_ds: [INTERN] ECC step required by the @ecc_strength_ds, > - * also from the datasheet. It is the recommended ECC step > + * also from the datasheet. It is the recommended ECC step > * size, if known; if unknown, set to zero. > * @onfi_timing_mode_default: [INTERN] default ONFI timing mode. This field is > * set to the actually used ONFI mode if the chip is
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 16/53] docs-rst: add userspace API book to pdf output |
| Message-ID | <tHJLY-5yL-3@gated-at.bofh.it> |
| In reply to | #1642478 |
The userspace API book was added without the bits required to
generate PDF output. Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/conf.py | 2 ++
1 file changed, 2 insertions(+)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index bca751960dec..2e215477edf5 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -373,6 +373,8 @@ latex_documents = [
'The kernel development community', 'manual'),
('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
'The kernel development community', 'manual'),
+ ('userspace-api/index', 'userspace-api.tex', 'The Linux kernel user-space API guide',
+ 'The kernel development community', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 20/53] docs-rst: don't ignore internal functions for jbd2 docs |
| Message-ID | <tHJLY-5yL-7@gated-at.bofh.it> |
| In reply to | #1642478 |
Those functions are currently ignored, causing references at the documentation to be lost. Don't ignore it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/filesystems/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 148becd91cba..256e10eedba4 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -287,7 +287,6 @@ Transasction Level ~~~~~~~~~~~~~~~~~~ .. kernel-doc:: fs/jbd2/transaction.c - :export: See also -------- -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 15/53] docs-rst: add sound book to pdf output |
| Message-ID | <tHJLY-5yL-9@gated-at.bofh.it> |
| In reply to | #1642478 |
The sound subsystem book was added without the bits required to
generate PDF output. Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/conf.py | 2 ++
Documentation/sound/conf.py | 10 ++++++++++
2 files changed, 12 insertions(+)
create mode 100644 Documentation/sound/conf.py
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 1d461f0c1cd0..bca751960dec 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -371,6 +371,8 @@ latex_documents = [
'The kernel development community', 'manual'),
('security/index', 'security.tex', 'The kernel security subsystem manual',
'The kernel development community', 'manual'),
+ ('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
+ 'The kernel development community', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
diff --git a/Documentation/sound/conf.py b/Documentation/sound/conf.py
new file mode 100644
index 000000000000..3f1fc5e74e7b
--- /dev/null
+++ b/Documentation/sound/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Linux Sound Subsystem Documentation"
+
+tags.add("subproject")
+
+latex_documents = [
+ ('index', 'sound.tex', project,
+ 'The kernel development community', 'manual'),
+]
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Takashi Iwai <tiwai@suse.de> |
|---|---|
| Date | 2017-05-16 21:10 +0200 |
| Subject | Re: [PATCH v2 15/53] docs-rst: add sound book to pdf output |
| Message-ID | <tHQ14-157-21@gated-at.bofh.it> |
| In reply to | #1642490 |
On Tue, 16 May 2017 14:16:07 +0200,
Mauro Carvalho Chehab wrote:
>
> The sound subsystem book was added without the bits required to
> generate PDF output. Add them.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Looks good to me.
Reviewed-by: Takashi Iwai <tiwai@suse.de>
thanks,
Takashi
> ---
> Documentation/conf.py | 2 ++
> Documentation/sound/conf.py | 10 ++++++++++
> 2 files changed, 12 insertions(+)
> create mode 100644 Documentation/sound/conf.py
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 1d461f0c1cd0..bca751960dec 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -371,6 +371,8 @@ latex_documents = [
> 'The kernel development community', 'manual'),
> ('security/index', 'security.tex', 'The kernel security subsystem manual',
> 'The kernel development community', 'manual'),
> + ('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
> + 'The kernel development community', 'manual'),
> ]
>
> # The name of an image file (relative to this directory) to place at the top of
> diff --git a/Documentation/sound/conf.py b/Documentation/sound/conf.py
> new file mode 100644
> index 000000000000..3f1fc5e74e7b
> --- /dev/null
> +++ b/Documentation/sound/conf.py
> @@ -0,0 +1,10 @@
> +# -*- coding: utf-8; mode: python -*-
> +
> +project = "Linux Sound Subsystem Documentation"
> +
> +tags.add("subproject")
> +
> +latex_documents = [
> + ('index', 'sound.tex', project,
> + 'The kernel development community', 'manual'),
> +]
> --
> 2.9.3
>
>
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 31/53] docs-rst: convert z8530book DocBook to ReST |
| Message-ID | <tHJLY-5yL-5@gated-at.bofh.it> |
| In reply to | #1642478 |
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Some manual adjustments were required due to some
conversion error on some literals.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DocBook/Makefile | 2 +-
Documentation/DocBook/z8530book.tmpl | 371 ---------------------------------
Documentation/networking/index.rst | 1 +
Documentation/networking/z8530book.rst | 257 +++++++++++++++++++++++
4 files changed, 259 insertions(+), 372 deletions(-)
delete mode 100644 Documentation/DocBook/z8530book.tmpl
create mode 100644 Documentation/networking/z8530book.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 8a90891c3712..00a61f4ffcff 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -6,7 +6,7 @@
# To add a new book the only step required is to add the book to the
# list of DOCBOOKS.
-DOCBOOKS := z8530book.xml \
+DOCBOOKS := \
lsm.xml \
mtdnand.xml librs.xml rapidio.xml \
scsi.xml \
diff --git a/Documentation/DocBook/z8530book.tmpl b/Documentation/DocBook/z8530book.tmpl
deleted file mode 100644
index 6f3883be877e..000000000000
--- a/Documentation/DocBook/z8530book.tmpl
+++ /dev/null
@@ -1,371 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Z85230Guide">
- <bookinfo>
- <title>Z8530 Programming Guide</title>
-
- <authorgroup>
- <author>
- <firstname>Alan</firstname>
- <surname>Cox</surname>
- <affiliation>
- <address>
- <email>alan@lxorguk.ukuu.org.uk</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2000</year>
- <holder>Alan Cox</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- The Z85x30 family synchronous/asynchronous controller chips are
- used on a large number of cheap network interface cards. The
- kernel provides a core interface layer that is designed to make
- it easy to provide WAN services using this chip.
- </para>
- <para>
- The current driver only support synchronous operation. Merging the
- asynchronous driver support into this code to allow any Z85x30
- device to be used as both a tty interface and as a synchronous
- controller is a project for Linux post the 2.4 release
- </para>
- </chapter>
-
- <chapter id="Driver_Modes">
- <title>Driver Modes</title>
- <para>
- The Z85230 driver layer can drive Z8530, Z85C30 and Z85230 devices
- in three different modes. Each mode can be applied to an individual
- channel on the chip (each chip has two channels).
- </para>
- <para>
- The PIO synchronous mode supports the most common Z8530 wiring. Here
- the chip is interface to the I/O and interrupt facilities of the
- host machine but not to the DMA subsystem. When running PIO the
- Z8530 has extremely tight timing requirements. Doing high speeds,
- even with a Z85230 will be tricky. Typically you should expect to
- achieve at best 9600 baud with a Z8C530 and 64Kbits with a Z85230.
- </para>
- <para>
- The DMA mode supports the chip when it is configured to use dual DMA
- channels on an ISA bus. The better cards tend to support this mode
- of operation for a single channel. With DMA running the Z85230 tops
- out when it starts to hit ISA DMA constraints at about 512Kbits. It
- is worth noting here that many PC machines hang or crash when the
- chip is driven fast enough to hold the ISA bus solid.
- </para>
- <para>
- Transmit DMA mode uses a single DMA channel. The DMA channel is used
- for transmission as the transmit FIFO is smaller than the receive
- FIFO. it gives better performance than pure PIO mode but is nowhere
- near as ideal as pure DMA mode.
- </para>
- </chapter>
-
- <chapter id="Using_the_Z85230_driver">
- <title>Using the Z85230 driver</title>
- <para>
- The Z85230 driver provides the back end interface to your board. To
- configure a Z8530 interface you need to detect the board and to
- identify its ports and interrupt resources. It is also your problem
- to verify the resources are available.
- </para>
- <para>
- Having identified the chip you need to fill in a struct z8530_dev,
- which describes each chip. This object must exist until you finally
- shutdown the board. Firstly zero the active field. This ensures
- nothing goes off without you intending it. The irq field should
- be set to the interrupt number of the chip. (Each chip has a single
- interrupt source rather than each channel). You are responsible
- for allocating the interrupt line. The interrupt handler should be
- set to <function>z8530_interrupt</function>. The device id should
- be set to the z8530_dev structure pointer. Whether the interrupt can
- be shared or not is board dependent, and up to you to initialise.
- </para>
- <para>
- The structure holds two channel structures.
- Initialise chanA.ctrlio and chanA.dataio with the address of the
- control and data ports. You can or this with Z8530_PORT_SLEEP to
- indicate your interface needs the 5uS delay for chip settling done
- in software. The PORT_SLEEP option is architecture specific. Other
- flags may become available on future platforms, eg for MMIO.
- Initialise the chanA.irqs to &z8530_nop to start the chip up
- as disabled and discarding interrupt events. This ensures that
- stray interrupts will be mopped up and not hang the bus. Set
- chanA.dev to point to the device structure itself. The
- private and name field you may use as you wish. The private field
- is unused by the Z85230 layer. The name is used for error reporting
- and it may thus make sense to make it match the network name.
- </para>
- <para>
- Repeat the same operation with the B channel if your chip has
- both channels wired to something useful. This isn't always the
- case. If it is not wired then the I/O values do not matter, but
- you must initialise chanB.dev.
- </para>
- <para>
- If your board has DMA facilities then initialise the txdma and
- rxdma fields for the relevant channels. You must also allocate the
- ISA DMA channels and do any necessary board level initialisation
- to configure them. The low level driver will do the Z8530 and
- DMA controller programming but not board specific magic.
- </para>
- <para>
- Having initialised the device you can then call
- <function>z8530_init</function>. This will probe the chip and
- reset it into a known state. An identification sequence is then
- run to identify the chip type. If the checks fail to pass the
- function returns a non zero error code. Typically this indicates
- that the port given is not valid. After this call the
- type field of the z8530_dev structure is initialised to either
- Z8530, Z85C30 or Z85230 according to the chip found.
- </para>
- <para>
- Once you have called z8530_init you can also make use of the utility
- function <function>z8530_describe</function>. This provides a
- consistent reporting format for the Z8530 devices, and allows all
- the drivers to provide consistent reporting.
- </para>
- </chapter>
-
- <chapter id="Attaching_Network_Interfaces">
- <title>Attaching Network Interfaces</title>
- <para>
- If you wish to use the network interface facilities of the driver,
- then you need to attach a network device to each channel that is
- present and in use. In addition to use the generic HDLC
- you need to follow some additional plumbing rules. They may seem
- complex but a look at the example hostess_sv11 driver should
- reassure you.
- </para>
- <para>
- The network device used for each channel should be pointed to by
- the netdevice field of each channel. The hdlc-> priv field of the
- network device points to your private data - you will need to be
- able to find your private data from this.
- </para>
- <para>
- The way most drivers approach this particular problem is to
- create a structure holding the Z8530 device definition and
- put that into the private field of the network device. The
- network device fields of the channels then point back to the
- network devices.
- </para>
- <para>
- If you wish to use the generic HDLC then you need to register
- the HDLC device.
- </para>
- <para>
- Before you register your network device you will also need to
- provide suitable handlers for most of the network device callbacks.
- See the network device documentation for more details on this.
- </para>
- </chapter>
-
- <chapter id="Configuring_And_Activating_The_Port">
- <title>Configuring And Activating The Port</title>
- <para>
- The Z85230 driver provides helper functions and tables to load the
- port registers on the Z8530 chips. When programming the register
- settings for a channel be aware that the documentation recommends
- initialisation orders. Strange things happen when these are not
- followed.
- </para>
- <para>
- <function>z8530_channel_load</function> takes an array of
- pairs of initialisation values in an array of u8 type. The first
- value is the Z8530 register number. Add 16 to indicate the alternate
- register bank on the later chips. The array is terminated by a 255.
- </para>
- <para>
- The driver provides a pair of public tables. The
- z8530_hdlc_kilostream table is for the UK 'Kilostream' service and
- also happens to cover most other end host configurations. The
- z8530_hdlc_kilostream_85230 table is the same configuration using
- the enhancements of the 85230 chip. The configuration loaded is
- standard NRZ encoded synchronous data with HDLC bitstuffing. All
- of the timing is taken from the other end of the link.
- </para>
- <para>
- When writing your own tables be aware that the driver internally
- tracks register values. It may need to reload values. You should
- therefore be sure to set registers 1-7, 9-11, 14 and 15 in all
- configurations. Where the register settings depend on DMA selection
- the driver will update the bits itself when you open or close.
- Loading a new table with the interface open is not recommended.
- </para>
- <para>
- There are three standard configurations supported by the core
- code. In PIO mode the interface is programmed up to use
- interrupt driven PIO. This places high demands on the host processor
- to avoid latency. The driver is written to take account of latency
- issues but it cannot avoid latencies caused by other drivers,
- notably IDE in PIO mode. Because the drivers allocate buffers you
- must also prevent MTU changes while the port is open.
- </para>
- <para>
- Once the port is open it will call the rx_function of each channel
- whenever a completed packet arrived. This is invoked from
- interrupt context and passes you the channel and a network
- buffer (struct sk_buff) holding the data. The data includes
- the CRC bytes so most users will want to trim the last two
- bytes before processing the data. This function is very timing
- critical. When you wish to simply discard data the support
- code provides the function <function>z8530_null_rx</function>
- to discard the data.
- </para>
- <para>
- To active PIO mode sending and receiving the <function>
- z8530_sync_open</function> is called. This expects to be passed
- the network device and the channel. Typically this is called from
- your network device open callback. On a failure a non zero error
- status is returned. The <function>z8530_sync_close</function>
- function shuts down a PIO channel. This must be done before the
- channel is opened again and before the driver shuts down
- and unloads.
- </para>
- <para>
- The ideal mode of operation is dual channel DMA mode. Here the
- kernel driver will configure the board for DMA in both directions.
- The driver also handles ISA DMA issues such as controller
- programming and the memory range limit for you. This mode is
- activated by calling the <function>z8530_sync_dma_open</function>
- function. On failure a non zero error value is returned.
- Once this mode is activated it can be shut down by calling the
- <function>z8530_sync_dma_close</function>. You must call the close
- function matching the open mode you used.
- </para>
- <para>
- The final supported mode uses a single DMA channel to drive the
- transmit side. As the Z85C30 has a larger FIFO on the receive
- channel this tends to increase the maximum speed a little.
- This is activated by calling the <function>z8530_sync_txdma_open
- </function>. This returns a non zero error code on failure. The
- <function>z8530_sync_txdma_close</function> function closes down
- the Z8530 interface from this mode.
- </para>
- </chapter>
-
- <chapter id="Network_Layer_Functions">
- <title>Network Layer Functions</title>
- <para>
- The Z8530 layer provides functions to queue packets for
- transmission. The driver internally buffers the frame currently
- being transmitted and one further frame (in order to keep back
- to back transmission running). Any further buffering is up to
- the caller.
- </para>
- <para>
- The function <function>z8530_queue_xmit</function> takes a network
- buffer in sk_buff format and queues it for transmission. The
- caller must provide the entire packet with the exception of the
- bitstuffing and CRC. This is normally done by the caller via
- the generic HDLC interface layer. It returns 0 if the buffer has been
- queued and non zero values for queue full. If the function accepts
- the buffer it becomes property of the Z8530 layer and the caller
- should not free it.
- </para>
- <para>
- The function <function>z8530_get_stats</function> returns a pointer
- to an internally maintained per interface statistics block. This
- provides most of the interface code needed to implement the network
- layer get_stats callback.
- </para>
- </chapter>
-
- <chapter id="Porting_The_Z8530_Driver">
- <title>Porting The Z8530 Driver</title>
- <para>
- The Z8530 driver is written to be portable. In DMA mode it makes
- assumptions about the use of ISA DMA. These are probably warranted
- in most cases as the Z85230 in particular was designed to glue to PC
- type machines. The PIO mode makes no real assumptions.
- </para>
- <para>
- Should you need to retarget the Z8530 driver to another architecture
- the only code that should need changing are the port I/O functions.
- At the moment these assume PC I/O port accesses. This may not be
- appropriate for all platforms. Replacing
- <function>z8530_read_port</function> and <function>z8530_write_port
- </function> is intended to be all that is required to port this
- driver layer.
- </para>
- </chapter>
-
- <chapter id="bugs">
- <title>Known Bugs And Assumptions</title>
- <para>
- <variablelist>
- <varlistentry><term>Interrupt Locking</term>
- <listitem>
- <para>
- The locking in the driver is done via the global cli/sti lock. This
- makes for relatively poor SMP performance. Switching this to use a
- per device spin lock would probably materially improve performance.
- </para>
- </listitem></varlistentry>
-
- <varlistentry><term>Occasional Failures</term>
- <listitem>
- <para>
- We have reports of occasional failures when run for very long
- periods of time and the driver starts to receive junk frames. At
- the moment the cause of this is not clear.
- </para>
- </listitem></varlistentry>
- </variablelist>
-
- </para>
- </chapter>
-
- <chapter id="pubfunctions">
- <title>Public Functions Provided</title>
-!Edrivers/net/wan/z85230.c
- </chapter>
-
- <chapter id="intfunctions">
- <title>Internal Functions</title>
-!Idrivers/net/wan/z85230.c
- </chapter>
-
-</book>
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index ff652ff279e8..b5bd87e01f52 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -7,6 +7,7 @@ Contents:
:maxdepth: 2
kapi
+ z8530book
.. only:: subproject
diff --git a/Documentation/networking/z8530book.rst b/Documentation/networking/z8530book.rst
new file mode 100644
index 000000000000..31032ee36081
--- /dev/null
+++ b/Documentation/networking/z8530book.rst
@@ -0,0 +1,257 @@
+=======================
+Z8530 Programming Guide
+=======================
+
+:Author: Alan Cox
+
+Introduction
+============
+
+The Z85x30 family synchronous/asynchronous controller chips are used on
+a large number of cheap network interface cards. The kernel provides a
+core interface layer that is designed to make it easy to provide WAN
+services using this chip.
+
+The current driver only support synchronous operation. Merging the
+asynchronous driver support into this code to allow any Z85x30 device to
+be used as both a tty interface and as a synchronous controller is a
+project for Linux post the 2.4 release
+
+Driver Modes
+============
+
+The Z85230 driver layer can drive Z8530, Z85C30 and Z85230 devices in
+three different modes. Each mode can be applied to an individual channel
+on the chip (each chip has two channels).
+
+The PIO synchronous mode supports the most common Z8530 wiring. Here the
+chip is interface to the I/O and interrupt facilities of the host
+machine but not to the DMA subsystem. When running PIO the Z8530 has
+extremely tight timing requirements. Doing high speeds, even with a
+Z85230 will be tricky. Typically you should expect to achieve at best
+9600 baud with a Z8C530 and 64Kbits with a Z85230.
+
+The DMA mode supports the chip when it is configured to use dual DMA
+channels on an ISA bus. The better cards tend to support this mode of
+operation for a single channel. With DMA running the Z85230 tops out
+when it starts to hit ISA DMA constraints at about 512Kbits. It is worth
+noting here that many PC machines hang or crash when the chip is driven
+fast enough to hold the ISA bus solid.
+
+Transmit DMA mode uses a single DMA channel. The DMA channel is used for
+transmission as the transmit FIFO is smaller than the receive FIFO. it
+gives better performance than pure PIO mode but is nowhere near as ideal
+as pure DMA mode.
+
+Using the Z85230 driver
+=======================
+
+The Z85230 driver provides the back end interface to your board. To
+configure a Z8530 interface you need to detect the board and to identify
+its ports and interrupt resources. It is also your problem to verify the
+resources are available.
+
+Having identified the chip you need to fill in a struct z8530_dev,
+which describes each chip. This object must exist until you finally
+shutdown the board. Firstly zero the active field. This ensures nothing
+goes off without you intending it. The irq field should be set to the
+interrupt number of the chip. (Each chip has a single interrupt source
+rather than each channel). You are responsible for allocating the
+interrupt line. The interrupt handler should be set to
+:c:func:`z8530_interrupt()`. The device id should be set to the
+z8530_dev structure pointer. Whether the interrupt can be shared or not
+is board dependent, and up to you to initialise.
+
+The structure holds two channel structures. Initialise chanA.ctrlio and
+chanA.dataio with the address of the control and data ports. You can or
+this with Z8530_PORT_SLEEP to indicate your interface needs the 5uS
+delay for chip settling done in software. The PORT_SLEEP option is
+architecture specific. Other flags may become available on future
+platforms, eg for MMIO. Initialise the chanA.irqs to &z8530_nop to
+start the chip up as disabled and discarding interrupt events. This
+ensures that stray interrupts will be mopped up and not hang the bus.
+Set chanA.dev to point to the device structure itself. The private and
+name field you may use as you wish. The private field is unused by the
+Z85230 layer. The name is used for error reporting and it may thus make
+sense to make it match the network name.
+
+Repeat the same operation with the B channel if your chip has both
+channels wired to something useful. This isn't always the case. If it is
+not wired then the I/O values do not matter, but you must initialise
+chanB.dev.
+
+If your board has DMA facilities then initialise the txdma and rxdma
+fields for the relevant channels. You must also allocate the ISA DMA
+channels and do any necessary board level initialisation to configure
+them. The low level driver will do the Z8530 and DMA controller
+programming but not board specific magic.
+
+Having initialised the device you can then call
+:c:func:`z8530_init()`. This will probe the chip and reset it into
+a known state. An identification sequence is then run to identify the
+chip type. If the checks fail to pass the function returns a non zero
+error code. Typically this indicates that the port given is not valid.
+After this call the type field of the z8530_dev structure is
+initialised to either Z8530, Z85C30 or Z85230 according to the chip
+found.
+
+Once you have called z8530_init you can also make use of the utility
+function :c:func:`z8530_describe()`. This provides a consistent
+reporting format for the Z8530 devices, and allows all the drivers to
+provide consistent reporting.
+
+Attaching Network Interfaces
+============================
+
+If you wish to use the network interface facilities of the driver, then
+you need to attach a network device to each channel that is present and
+in use. In addition to use the generic HDLC you need to follow some
+additional plumbing rules. They may seem complex but a look at the
+example hostess_sv11 driver should reassure you.
+
+The network device used for each channel should be pointed to by the
+netdevice field of each channel. The hdlc-> priv field of the network
+device points to your private data - you will need to be able to find
+your private data from this.
+
+The way most drivers approach this particular problem is to create a
+structure holding the Z8530 device definition and put that into the
+private field of the network device. The network device fields of the
+channels then point back to the network devices.
+
+If you wish to use the generic HDLC then you need to register the HDLC
+device.
+
+Before you register your network device you will also need to provide
+suitable handlers for most of the network device callbacks. See the
+network device documentation for more details on this.
+
+Configuring And Activating The Port
+===================================
+
+The Z85230 driver provides helper functions and tables to load the port
+registers on the Z8530 chips. When programming the register settings for
+a channel be aware that the documentation recommends initialisation
+orders. Strange things happen when these are not followed.
+
+:c:func:`z8530_channel_load()` takes an array of pairs of
+initialisation values in an array of u8 type. The first value is the
+Z8530 register number. Add 16 to indicate the alternate register bank on
+the later chips. The array is terminated by a 255.
+
+The driver provides a pair of public tables. The z8530_hdlc_kilostream
+table is for the UK 'Kilostream' service and also happens to cover most
+other end host configurations. The z8530_hdlc_kilostream_85230 table
+is the same configuration using the enhancements of the 85230 chip. The
+configuration loaded is standard NRZ encoded synchronous data with HDLC
+bitstuffing. All of the timing is taken from the other end of the link.
+
+When writing your own tables be aware that the driver internally tracks
+register values. It may need to reload values. You should therefore be
+sure to set registers 1-7, 9-11, 14 and 15 in all configurations. Where
+the register settings depend on DMA selection the driver will update the
+bits itself when you open or close. Loading a new table with the
+interface open is not recommended.
+
+There are three standard configurations supported by the core code. In
+PIO mode the interface is programmed up to use interrupt driven PIO.
+This places high demands on the host processor to avoid latency. The
+driver is written to take account of latency issues but it cannot avoid
+latencies caused by other drivers, notably IDE in PIO mode. Because the
+drivers allocate buffers you must also prevent MTU changes while the
+port is open.
+
+Once the port is open it will call the rx_function of each channel
+whenever a completed packet arrived. This is invoked from interrupt
+context and passes you the channel and a network buffer (struct
+sk_buff) holding the data. The data includes the CRC bytes so most
+users will want to trim the last two bytes before processing the data.
+This function is very timing critical. When you wish to simply discard
+data the support code provides the function
+:c:func:`z8530_null_rx()` to discard the data.
+
+To active PIO mode sending and receiving the ``
+ z8530_sync_open`` is called. This expects to be passed the network
+device and the channel. Typically this is called from your network
+device open callback. On a failure a non zero error status is returned.
+The :c:func:`z8530_sync_close()` function shuts down a PIO
+channel. This must be done before the channel is opened again and before
+the driver shuts down and unloads.
+
+The ideal mode of operation is dual channel DMA mode. Here the kernel
+driver will configure the board for DMA in both directions. The driver
+also handles ISA DMA issues such as controller programming and the
+memory range limit for you. This mode is activated by calling the
+:c:func:`z8530_sync_dma_open()` function. On failure a non zero
+error value is returned. Once this mode is activated it can be shut down
+by calling the :c:func:`z8530_sync_dma_close()`. You must call
+the close function matching the open mode you used.
+
+The final supported mode uses a single DMA channel to drive the transmit
+side. As the Z85C30 has a larger FIFO on the receive channel this tends
+to increase the maximum speed a little. This is activated by calling the
+``z8530_sync_txdma_open
+ ``. This returns a non zero error code on failure. The
+:c:func:`z8530_sync_txdma_close()` function closes down the Z8530
+interface from this mode.
+
+Network Layer Functions
+=======================
+
+The Z8530 layer provides functions to queue packets for transmission.
+The driver internally buffers the frame currently being transmitted and
+one further frame (in order to keep back to back transmission running).
+Any further buffering is up to the caller.
+
+The function :c:func:`z8530_queue_xmit()` takes a network buffer
+in sk_buff format and queues it for transmission. The caller must
+provide the entire packet with the exception of the bitstuffing and CRC.
+This is normally done by the caller via the generic HDLC interface
+layer. It returns 0 if the buffer has been queued and non zero values
+for queue full. If the function accepts the buffer it becomes property
+of the Z8530 layer and the caller should not free it.
+
+The function :c:func:`z8530_get_stats()` returns a pointer to an
+internally maintained per interface statistics block. This provides most
+of the interface code needed to implement the network layer get_stats
+callback.
+
+Porting The Z8530 Driver
+========================
+
+The Z8530 driver is written to be portable. In DMA mode it makes
+assumptions about the use of ISA DMA. These are probably warranted in
+most cases as the Z85230 in particular was designed to glue to PC type
+machines. The PIO mode makes no real assumptions.
+
+Should you need to retarget the Z8530 driver to another architecture the
+only code that should need changing are the port I/O functions. At the
+moment these assume PC I/O port accesses. This may not be appropriate
+for all platforms. Replacing :c:func:`z8530_read_port()` and
+``z8530_write_port
+ `` is intended to be all that is required to port this driver layer.
+
+Known Bugs And Assumptions
+==========================
+
+Interrupt Locking
+ The locking in the driver is done via the global cli/sti lock. This
+ makes for relatively poor SMP performance. Switching this to use a
+ per device spin lock would probably materially improve performance.
+
+Occasional Failures
+ We have reports of occasional failures when run for very long
+ periods of time and the driver starts to receive junk frames. At the
+ moment the cause of this is not clear.
+
+Public Functions Provided
+=========================
+
+.. kernel-doc:: drivers/net/wan/z85230.c
+ :export:
+
+Internal Functions
+==================
+
+.. kernel-doc:: drivers/net/wan/z85230.c
+ :internal:
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 10/53] conf.py: define a color for important markup on PDF output |
| Message-ID | <tHJLY-5yL-13@gated-at.bofh.it> |
| In reply to | #1642478 |
As kdbg.rst uses the ".. important::" annotation, let's define a
color for PDF output.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/conf.py | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 0ce8001a50b6..1774357150a3 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -281,6 +281,7 @@ latex_elements = {
\\definecolor{NoteColor}{RGB}{204,255,255}
\\definecolor{WarningColor}{RGB}{255,204,204}
\\definecolor{AttentionColor}{RGB}{255,255,204}
+ \\definecolor{ImportantColor}{RGB}{192,255,204}
\\definecolor{OtherColor}{RGB}{204,204,204}
\\newlength{\\mynoticelength}
\\makeatletter\\newenvironment{coloredbox}[1]{%
@@ -301,7 +302,12 @@ latex_elements = {
\\ifthenelse%
{\\equal{\\py@noticetype}{attention}}%
{\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
- {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
+ {%
+ \\ifthenelse%
+ {\\equal{\\py@noticetype}{important}}%
+ {\\colorbox{ImportantColor}{\\usebox{\\@tempboxa}}}%
+ {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
+ }%
}%
}%
}\\makeatother
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 44/53] MAINTAINERS: update old references for DocBook directory |
| Message-ID | <tHJLY-5yL-15@gated-at.bofh.it> |
| In reply to | #1642478 |
As everything was converted, update the references to point to the new places. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- MAINTAINERS | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/MAINTAINERS b/MAINTAINERS index f42daf74f541..8609dba03cbc 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3567,7 +3567,6 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/herbert/crypto-2.6.git S: Maintained F: Documentation/crypto/ F: Documentation/devicetree/bindings/crypto/ -F: Documentation/DocBook/crypto-API.tmpl F: arch/*/crypto/ F: crypto/ F: drivers/crypto/ @@ -7364,7 +7363,7 @@ W: http://kgdb.wiki.kernel.org/ L: kgdb-bugreport@lists.sourceforge.net T: git git://git.kernel.org/pub/scm/linux/kernel/git/jwessel/kgdb.git S: Maintained -F: Documentation/DocBook/kgdb.tmpl +F: Documentation/dev-tools/kgdb.rst F: drivers/misc/kgdbts.c F: drivers/tty/serial/kgdboc.c F: include/linux/kdb.h @@ -10971,7 +10970,7 @@ S: Supported F: arch/s390/ F: drivers/s390/ F: Documentation/s390/ -F: Documentation/DocBook/s390* +F: Documentation/driver-api/s390-drivers.rst S390 COMMON I/O LAYER M: Sebastian Ott <sebott@linux.vnet.ibm.com> -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 02/53] kernel-hacking: update document |
| Message-ID | <tHJLY-5yL-17@gated-at.bofh.it> |
| In reply to | #1642478 |
This document is fairly updated. Yet, some stuff moved to
other kernel headers. So, update to point to the right
places.
While here, adjust some minor ReST markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/kernel-hacking/hacking.rst | 179 +++++++++++++++++--------------
1 file changed, 98 insertions(+), 81 deletions(-)
diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst
index 75597e627791..1a456b60a7cf 100644
--- a/Documentation/kernel-hacking/hacking.rst
+++ b/Documentation/kernel-hacking/hacking.rst
@@ -56,7 +56,7 @@ interrupts. You can sleep, by calling :c:func:`schedule()`.
In user context, the ``current`` pointer (indicating the task we are
currently executing) is valid, and :c:func:`in_interrupt()`
-(``include/linux/interrupt.h``) is false.
+(``include/linux/preempt.h``) is false.
.. warning::
@@ -114,12 +114,12 @@ time, although different tasklets can run simultaneously.
Kuznetsov had at the time.
You can tell you are in a softirq (or tasklet) using the
-:c:func:`in_softirq()` macro (``include/linux/interrupt.h``).
+:c:func:`in_softirq()` macro (``include/linux/preempt.h``).
.. warning::
- Beware that this will return a false positive if a bh lock (see
- below) is held.
+ Beware that this will return a false positive if a
+ :ref:`botton half lock <local_bh_disable>` is held.
Some Basic Rules
================
@@ -154,9 +154,7 @@ The Linux kernel is portable
ioctls: Not writing a new system call
=====================================
-A system call generally looks like this
-
-::
+A system call generally looks like this::
asmlinkage long sys_mycall(int arg)
{
@@ -175,7 +173,9 @@ If all your routine does is read or write some parameter, consider
implementing a :c:func:`sysfs()` interface instead.
Inside the ioctl you're in user context to a process. When a error
-occurs you return a negated errno (see ``include/linux/errno.h``),
+occurs you return a negated errno (see
+``include/uapi/asm-generic/errno-base.h``,
+``include/uapi/asm-generic/errno.h`` and ``include/linux/errno.h``),
otherwise you return 0.
After you slept you should check if a signal occurred: the Unix/Linux
@@ -195,9 +195,7 @@ some data structure.
If you're doing longer computations: first think userspace. If you
**really** want to do it in kernel you should regularly check if you need
to give up the CPU (remember there is cooperative multitasking per CPU).
-Idiom:
-
-::
+Idiom::
cond_resched(); /* Will sleep */
@@ -231,26 +229,24 @@ Really.
Common Routines
===============
-:c:func:`printk()` ``include/linux/kernel.h``
----------------------------------------------
+:c:func:`printk()`
+------------------
+
+Defined in ``include/linux/printk.h``
:c:func:`printk()` feeds kernel messages to the console, dmesg, and
the syslog daemon. It is useful for debugging and reporting errors, and
can be used inside interrupt context, but use with caution: a machine
which has its console flooded with printk messages is unusable. It uses
a format string mostly compatible with ANSI C printf, and C string
-concatenation to give it a first "priority" argument:
-
-::
+concatenation to give it a first "priority" argument::
printk(KERN_INFO "i = %u\n", i);
-See ``include/linux/kernel.h``; for other ``KERN_`` values; these are
+See ``include/linux/kern_levels.h``; for other ``KERN_`` values; these are
interpreted by syslog as the level. Special case: for printing an IP
-address use
-
-::
+address use::
__be32 ipaddress;
printk(KERN_INFO "my ip: %pI4\n", &ipaddress);
@@ -270,8 +266,10 @@ overruns. Make sure that will be enough.
on top of its printf function: "Printf should not be used for
chit-chat". You should follow that advice.
-:c:func:`copy_[to/from]_user()` / :c:func:`get_user()` / :c:func:`put_user()` ``include/linux/uaccess.h``
----------------------------------------------------------------------------------------------------------
+:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()`
+---------------------------------------------------------------------------------------------------
+
+Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h``
**[SLEEPS]**
@@ -297,8 +295,10 @@ The functions may sleep implicitly. This should never be called outside
user context (it makes no sense), with interrupts disabled, or a
spinlock held.
-:c:func:`kmalloc()`/:c:func:`kfree()` ``include/linux/slab.h``
---------------------------------------------------------------
+:c:func:`kmalloc()`/:c:func:`kfree()`
+-------------------------------------
+
+Defined in ``include/linux/slab.h``
**[MAY SLEEP: SEE BELOW]**
@@ -324,9 +324,9 @@ message, then maybe you called a sleeping allocation function from
interrupt context without ``GFP_ATOMIC``. You should really fix that.
Run, don't walk.
-If you are allocating at least ``PAGE_SIZE`` (``include/asm/page.h``)
-bytes, consider using :c:func:`__get_free_pages()`
-(``include/linux/mm.h``). It takes an order argument (0 for page sized,
+If you are allocating at least ``PAGE_SIZE`` (``asm/page.h`` or
+``asm/page_types.h``) bytes, consider using :c:func:`__get_free_pages()`
+(``include/linux/gfp.h``). It takes an order argument (0 for page sized,
1 for double page, 2 for four pages etc.) and the same memory priority
flag word as above.
@@ -344,24 +344,30 @@ routine.
Before inventing your own cache of often-used objects consider using a
slab cache in ``include/linux/slab.h``
-:c:func:`current()` ``include/asm/current.h``
----------------------------------------------
+:c:func:`current()`
+-------------------
+
+Defined in ``include/asm/current.h``
This global variable (really a macro) contains a pointer to the current
task structure, so is only valid in user context. For example, when a
process makes a system call, this will point to the task structure of
the calling process. It is **not NULL** in interrupt context.
-:c:func:`mdelay()`/:c:func:`udelay()` ``include/asm/delay.h`` ``include/linux/delay.h``
----------------------------------------------------------------------------------------
+:c:func:`mdelay()`/:c:func:`udelay()`
+-------------------------------------
+
+Defined in ``include/asm/delay.h`` / ``include/linux/delay.h``
The :c:func:`udelay()` and :c:func:`ndelay()` functions can be
used for small pauses. Do not use large values with them as you risk
overflow - the helper function :c:func:`mdelay()` is useful here, or
consider :c:func:`msleep()`.
-:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` ``include/asm/byteorder.h``
----------------------------------------------------------------------------------------------------------------------------
+:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()`
+-----------------------------------------------------------------------------------------------
+
+Defined in ``include/asm/byteorder.h``
The :c:func:`cpu_to_be32()` family (where the "32" can be replaced
by 64 or 16, and the "be" can be replaced by "le") are the general way
@@ -375,8 +381,10 @@ to the given type, and return the converted value. The other variation
is the "in-situ" family, such as :c:func:`cpu_to_be32s()`, which
convert value referred to by the pointer, and return void.
-:c:func:`local_irq_save()`/:c:func:`local_irq_restore()` ``include/linux/irqflags.h``
--------------------------------------------------------------------------------------
+:c:func:`local_irq_save()`/:c:func:`local_irq_restore()`
+--------------------------------------------------------
+
+Defined in ``include/linux/irqflags.h``
These routines disable hard interrupts on the local CPU, and restore
them. They are reentrant; saving the previous state in their one
@@ -384,16 +392,23 @@ them. They are reentrant; saving the previous state in their one
enabled, you can simply use :c:func:`local_irq_disable()` and
:c:func:`local_irq_enable()`.
-:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()` ``include/linux/interrupt.h``
---------------------------------------------------------------------------------------
+.. _local_bh_disable:
+
+:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()`
+--------------------------------------------------------
+
+Defined in ``include/linux/bottom_half.h``
+
These routines disable soft interrupts on the local CPU, and restore
them. They are reentrant; if soft interrupts were disabled before, they
will still be disabled after this pair of functions has been called.
They prevent softirqs and tasklets from running on the current CPU.
-:c:func:`smp_processor_id()`() ``include/asm/smp.h``
-----------------------------------------------------
+:c:func:`smp_processor_id()`
+----------------------------
+
+Defined in ``include/linux/smp.h``
:c:func:`get_cpu()` disables preemption (so you won't suddenly get
moved to another CPU) and returns the current processor number, between
@@ -405,8 +420,10 @@ If you know you cannot be preempted by another task (ie. you are in
interrupt context, or have preemption disabled) you can use
smp_processor_id().
-``__init``/``__exit``/``__initdata`` ``include/linux/init.h``
--------------------------------------------------------------
+``__init``/``__exit``/``__initdata``
+------------------------------------
+
+Defined in ``include/linux/init.h``
After boot, the kernel frees up a special section; functions marked with
``__init`` and data structures marked with ``__initdata`` are dropped
@@ -415,10 +432,13 @@ initialization. ``__exit`` is used to declare a function which is only
required on exit: the function will be dropped if this file is not
compiled as a module. See the header file for use. Note that it makes no
sense for a function marked with ``__init`` to be exported to modules
-with :c:func:`EXPORT_SYMBOL()` - this will break.
+with :c:func:`EXPORT_SYMBOL()` or :c:func:`EXPORT_SYMBOL_GPL()`- this
+will break.
-:c:func:`__initcall()`/:c:func:`module_init()` ``include/linux/init.h``
------------------------------------------------------------------------
+:c:func:`__initcall()`/:c:func:`module_init()`
+----------------------------------------------
+
+Defined in ``include/linux/init.h`` / ``include/linux/module.h``
Many parts of the kernel are well served as a module
(dynamically-loadable parts of the kernel). Using the
@@ -438,8 +458,11 @@ to fail (unfortunately, this has no effect if the module is compiled
into the kernel). This function is called in user context with
interrupts enabled, so it can sleep.
-:c:func:`module_exit()` ``include/linux/init.h``
-------------------------------------------------
+:c:func:`module_exit()`
+-----------------------
+
+
+Defined in ``include/linux/module.h``
This macro defines the function to be called at module removal time (or
never, in the case of the file compiled into the kernel). It will only
@@ -450,8 +473,10 @@ it returns.
Note that this macro is optional: if it is not present, your module will
not be removable (except for 'rmmod -f').
-:c:func:`try_module_get()`/:c:func:`module_put()` ``include/linux/module.h``
-----------------------------------------------------------------------------
+:c:func:`try_module_get()`/:c:func:`module_put()`
+-------------------------------------------------
+
+Defined in ``include/linux/module.h``
These manipulate the module usage count, to protect against removal (a
module also can't be removed if another module uses one of its exported
@@ -472,8 +497,8 @@ Wait Queues ``include/linux/wait.h``
A wait queue is used to wait for someone to wake you up when a certain
condition is true. They must be used carefully to ensure there is no
-race condition. You declare a ``wait_queue_head_t``, and then processes
-which want to wait for that condition declare a ``wait_queue_t``
+race condition. You declare a :c:type:`wait_queue_head_t`, and then processes
+which want to wait for that condition declare a :c:type:`wait_queue_t`
referring to themselves, and place that in the queue.
Declaring
@@ -490,15 +515,15 @@ Queuing
Placing yourself in the waitqueue is fairly complex, because you must
put yourself in the queue before checking the condition. There is a
macro to do this: :c:func:`wait_event_interruptible()`
-``include/linux/wait.h`` The first argument is the wait queue head, and
+(``include/linux/wait.h``) The first argument is the wait queue head, and
the second is an expression which is evaluated; the macro returns 0 when
-this expression is true, or -ERESTARTSYS if a signal is received. The
+this expression is true, or ``-ERESTARTSYS`` if a signal is received. The
:c:func:`wait_event()` version ignores signals.
Waking Up Queued Tasks
----------------------
-Call :c:func:`wake_up()` ``include/linux/wait.h``;, which will wake
+Call :c:func:`wake_up()` (``include/linux/wait.h``);, which will wake
up every process in the queue. The exception is if one has
``TASK_EXCLUSIVE`` set, in which case the remainder of the queue will
not be woken. There are other variants of this basic function available
@@ -508,9 +533,9 @@ Atomic Operations
=================
Certain operations are guaranteed atomic on all platforms. The first
-class of operations work on ``atomic_t`` ``include/asm/atomic.h``; this
-contains a signed integer (at least 32 bits long), and you must use
-these functions to manipulate or read atomic_t variables.
+class of operations work on :c:type:`atomic_t` (``include/asm/atomic.h``);
+this contains a signed integer (at least 32 bits long), and you must use
+these functions to manipulate or read :c:type:`atomic_t` variables.
:c:func:`atomic_read()` and :c:func:`atomic_set()` get and set
the counter, :c:func:`atomic_add()`, :c:func:`atomic_sub()`,
:c:func:`atomic_inc()`, :c:func:`atomic_dec()`, and
@@ -534,7 +559,7 @@ true if the bit was previously set; these are particularly useful for
atomically setting flags.
It is possible to call these operations with bit indices greater than
-BITS_PER_LONG. The resulting behavior is strange on big-endian
+``BITS_PER_LONG``. The resulting behavior is strange on big-endian
platforms though so it is a good idea not to do this.
Symbols
@@ -546,14 +571,18 @@ be used anywhere in the kernel). However, for modules, a special
exported symbol table is kept which limits the entry points to the
kernel proper. Modules can also export symbols.
-:c:func:`EXPORT_SYMBOL()` ``include/linux/export.h``
-----------------------------------------------------
+:c:func:`EXPORT_SYMBOL()`
+-------------------------
+
+Defined in ``include/linux/export.h``
This is the classic method of exporting a symbol: dynamically loaded
modules will be able to use the symbol as normal.
-:c:func:`EXPORT_SYMBOL_GPL()` ``include/linux/export.h``
---------------------------------------------------------
+:c:func:`EXPORT_SYMBOL_GPL()`
+-----------------------------
+
+Defined in ``include/linux/export.h``
Similar to :c:func:`EXPORT_SYMBOL()` except that the symbols
exported by :c:func:`EXPORT_SYMBOL_GPL()` can only be seen by
@@ -579,11 +608,11 @@ Return Conventions
------------------
For code called in user context, it's very common to defy C convention,
-and return 0 for success, and a negative error number (eg. -EFAULT) for
+and return 0 for success, and a negative error number (eg. ``-EFAULT``) for
failure. This can be unintuitive at first, but it's fairly widespread in
the kernel.
-Using :c:func:`ERR_PTR()` ``include/linux/err.h``; to encode a
+Using :c:func:`ERR_PTR()` (``include/linux/err.h``) to encode a
negative error number into a pointer, and :c:func:`IS_ERR()` and
:c:func:`PTR_ERR()` to get it back out again: avoids a separate
pointer parameter for the error number. Icky, but in a good way.
@@ -603,9 +632,7 @@ Initializing structure members
------------------------------
The preferred method of initializing structures is to use designated
-initialisers, as defined by ISO C99, eg:
-
-::
+initialisers, as defined by ISO C99, eg::
static struct block_device_operations opt_fops = {
.open = opt_open,
@@ -716,18 +743,14 @@ Kernel Cantrips
Some favorites from browsing the source. Feel free to add to this list.
-``arch/x86/include/asm/delay.h:``
-
-::
+``arch/x86/include/asm/delay.h``::
#define ndelay(n) (__builtin_constant_p(n) ? \
((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
__ndelay(n))
-``include/linux/fs.h``:
-
-::
+``include/linux/fs.h``::
/*
* Kernel pointers have redundant information, so we can use a
@@ -741,9 +764,7 @@ Some favorites from browsing the source. Feel free to add to this list.
#define PTR_ERR(ptr) ((long)(ptr))
#define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000))
-``arch/x86/include/asm/uaccess_32.h:``
-
-::
+``arch/x86/include/asm/uaccess_32.h:``::
#define copy_to_user(to,from,n) \
(__builtin_constant_p(n) ? \
@@ -751,9 +772,7 @@ Some favorites from browsing the source. Feel free to add to this list.
__generic_copy_to_user((to),(from),(n)))
-``arch/sparc/kernel/head.S:``
-
-::
+``arch/sparc/kernel/head.S:``::
/*
* Sun people can't spell worth damn. "compatability" indeed.
@@ -772,9 +791,7 @@ Some favorites from browsing the source. Feel free to add to this list.
.asciz "compatible"
-``arch/sparc/lib/checksum.S:``
-
-::
+``arch/sparc/lib/checksum.S:``::
/* Sun, you just can't beat me, you just can't. Stop trying,
* give up. I'm serious, I am going to kick the living shit
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 20:20 +0200 |
| Subject | [PATCH v2 53/53] kernel-doc: describe the ``literal`` syntax |
| Message-ID | <tHPeF-yr-3@gated-at.bofh.it> |
| In reply to | #1642495 |
changeset b97f193abf83 ("scripts/kernel-doc: fix parser
for apostrophes") added support for ``literal`` inside
kernel-doc, in order to allow using the "%" symbol inside
a literal block, as this is used at printk() description.
Document it.
Fixes: b97f193abf83 ("scripts/kernel-doc: fix parser for apostrophes")
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/doc-guide/kernel-doc.rst | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index b32e4813ff6f..b24854b5d6be 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -149,6 +149,16 @@ Domain`_ references.
``%CONST``
Name of a constant. (No cross-referencing, just formatting.)
+````literal````
+ A literal block that should be handled as-is. The output will use a
+ ``monospaced font``.
+
+ Useful if you need to use special characters that would otherwise have some
+ meaning either by kernel-doc script of by reStructuredText.
+
+ This is particularly useful if you need to use things like ``%ph`` inside
+ a function description.
+
``$ENVVAR``
Name of an environment variable. (No cross-referencing, just formatting.)
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 20:20 +0200 |
| Subject | [PATCH v2 52/53] docs-rst: get rid of Documentation/sphinx/tmplcvt script |
| Message-ID | <tHPeF-yr-9@gated-at.bofh.it> |
| In reply to | #1642495 |
As everything was converted to ReST, we don't need this script anymore. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/sphinx/tmplcvt | 28 ---------------------------- 1 file changed, 28 deletions(-) delete mode 100755 Documentation/sphinx/tmplcvt diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt deleted file mode 100755 index 6848f0a26fa5..000000000000 --- a/Documentation/sphinx/tmplcvt +++ /dev/null @@ -1,28 +0,0 @@ -#!/bin/bash -# -# Convert a template file into something like RST -# -# fix <function> -# feed to pandoc -# fix \_ -# title line? -# -set -eu - -if [ "$#" != "2" ]; then - echo "$0 <docbook file> <rst file>" - exit -fi - -DIR=$(dirname $0) - -in=$1 -rst=$2 -tmp=$rst.tmp - -cp $in $tmp -sed --in-place -f $DIR/convert_template.sed $tmp -pandoc -s -S -f docbook -t rst -o $rst $tmp -sed --in-place -f $DIR/post_convert.sed $rst -rm $tmp -echo "book writen to $rst" -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 20:20 +0200 |
| Subject | [PATCH v2 50/53] fs: fix the location of the kernel-api book |
| Message-ID | <tHPeF-yr-13@gated-at.bofh.it> |
| In reply to | #1642495 |
The kernel-api book is now part of the core-api. Update its location. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- fs/debugfs/inode.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fs/debugfs/inode.c b/fs/debugfs/inode.c index e892ae7d89f8..77440e4aa9d4 100644 --- a/fs/debugfs/inode.c +++ b/fs/debugfs/inode.c @@ -9,7 +9,7 @@ * 2 as published by the Free Software Foundation. * * debugfs is for people to use instead of /proc or /sys. - * See Documentation/DocBook/kernel-api for more details. + * See ./Documentation/core-api/kernel-api.rst for more details. * */ -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 20:20 +0200 |
| Subject | [PATCH v2 51/53] usb: fix the comment with regards to DocBook |
| Message-ID | <tHPeG-yr-19@gated-at.bofh.it> |
| In reply to | #1642495 |
The USB gadget documentation is not at DocBook anymore. The main file was converted to ReST, and stored at Documentation/driver-api/usb/gadget.rst, but there are still several plain text files related to gadget under Documentation/usb. So, be generic and just mention documentation without specifying where it is. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- drivers/usb/gadget/Kconfig | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/usb/gadget/Kconfig b/drivers/usb/gadget/Kconfig index c164d6b788c3..b3c879b75a39 100644 --- a/drivers/usb/gadget/Kconfig +++ b/drivers/usb/gadget/Kconfig @@ -41,7 +41,7 @@ menuconfig USB_GADGET don't have this kind of hardware (except maybe inside Linux PDAs). For more information, see <http://www.linux-usb.org/gadget> and - the kernel DocBook documentation for this API. + the kernel documentation for this API. if USB_GADGET -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Felipe Balbi <balbi@kernel.org> |
|---|---|
| Date | 2017-05-17 13:20 +0200 |
| Subject | Re: [PATCH v2 51/53] usb: fix the comment with regards to DocBook |
| Message-ID | <tI59L-2mF-3@gated-at.bofh.it> |
| In reply to | #1642724 |
[Multipart message — attachments visible in raw view] — view raw
Mauro Carvalho Chehab <mchehab@s-opensource.com> writes: > The USB gadget documentation is not at DocBook anymore. > The main file was converted to ReST, and stored at > Documentation/driver-api/usb/gadget.rst, but there are > still several plain text files related to gadget under > Documentation/usb. > > So, be generic and just mention documentation > without specifying where it is. > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> I'm adding this to my queue. If this is part of a larger series, let me know and I'll drop it :-) -- balbi
[toc] | [prev] | [next] | [standalone]
Page 1 of 3 [1] 2 3 Next page →
Back to top | Article view | linux.kernel
csiph-web