[PATCH v6 00/80] htmldoc build fixes with Sphinx 2.x and 3.x

[PATCH v6 00/80] htmldoc build fixes with Sphinx 2.x and 3.x

[Mauro Carvalho Chehab]

This series actually folds the previous Sphinx 3.x patch series
with the other patches I sent fixing warnings with Sphinx
2.x and with kernel-doc and that weren't merged yet via
some other tree.

It is based on the top of upstream, plus the media
pull request I sent yesterday:

	https://lore.kernel.org/lkml/20201012134139.0d58f5d7@coco.lan/

My plan is to send a pull request with those patches after Thursday's
linux next release.

On this series, I removed the patches that depend on material
currently found only at linux-next. 

Mauro Carvalho Chehab (79):
  scripts: kernel-doc: add support for typedef enum
  scripts: kernel-doc: make it more compatible with Sphinx 3.x
  scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx
    3.x
  scripts: kernel-doc: fix troubles with line counts
  scripts: kernel-doc: reimplement -nofunction argument
  scripts: kernel-doc: fix typedef identification
  scripts: kernel-doc: don't mangle with parameter list
  scripts: kernel-doc: allow passing desired Sphinx C domain dialect
  scripts: kernel-doc: fix line number handling
  scripts: kernel-doc: try to use c:function if possible
  docs: cdomain.py: add support for a new Sphinx 3.1+ tag
  docs: cdomain.py: extend it to handle new Sphinx 3.x tags
  docs: kerneldoc.py: append the name of the parsed doc file
  docs: kerneldoc.py: add support for kerneldoc -nosymbol
  media: docs: make CEC documents compatible with Sphinx 3.1+
  media: docs: make V4L documents more compatible with Sphinx 3.1+
  media: docs: make DVB documents more compatible with Sphinx 3.1+
  media: docs: make MC documents more compatible with Sphinx 3.1+
  media: docs: make RC documents more compatible with Sphinx 3.1+
  media: cec-core.rst: don't use c:type for structs
  docs: remove some replace macros like |struct foo|
  docs: get rid of :c:type explicit declarations for structs
  docs: trace-uses.rst: remove bogus c-domain tags
  docs: it_IT: fix namespace collisions at locking.rst
  docs: net: ieee802154.rst: fix C expressions
  docs: genericirq.rst: don't document chip.c functions twice
  docs: kernel-api.rst: drop kernel/irq/manage.c kernel-doc tag
  docs: remove sound API duplication
  docs: basics.rst: move kernel-doc workqueue markups to workqueue.rst
  docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup
  docs: device_link.rst: remove duplicated kernel-doc include
  docs: basics.rst: get rid of rcu kernel-doc macros
  docs: pstore-blk.rst: fix kernel-doc tags
  docs: fs: fscrypt.rst: get rid of :c:type: tags
  docs: devices.rst: get rid of :c:type macros
  docs: sound: writing-an-alsa-driver.rst: get rid of :c:type
  docs: block: blk-mq.rst: get rid of :c:type
  docs: writing-an-alsa-driver.rst: fix some bad c:func: markups
  docs: fpga: replace :c:member: macros
  docs: kgdb.rst: fix :c:type: usages
  docs: libata.rst: fix a wrong usage of :c:type: tag
  docs: infrastructure.rst: don't include firmware kernel-doc
  docs: gpu: i915.rst: Fix several C duplication warnings
  docs: devices.rst: fix a C reference markup
  docs: it_IT: hacking.rst: fix a typo on a markup
  docs: mei.rst: fix a C expression markup
  docs: basics.rst: avoid duplicated C function declaration
  docs: conf.py: fix c:function support with Sphinx 3.x
  docs: conf.py: change the Sphinx 3.x+ text
  docs: infrastructure.rst: exclude device_link_state from device.h
  docs: zh_CN: amu.rst: fix document title markup
  media: uAPI: buffer.rst: remove a left-over documentation
  math64.h: kernel-docs: Convert some markups into normal comments
  memblock: get rid of a :c:type leftover
  dt-bindings: fix references to files converted to yaml
  net: appletalk: Kconfig: Fix docs location
  drivers: net: hamradio: fix document location
  docs: powerpc: syscall64-abi.rst: fix a malformed table
  block: bio: fix a warning at the kernel-doc markups
  kunit: test.h: solve kernel-doc warnings
  docs: bio: fix a kerneldoc markup
  drivers: core: fix kernel-doc markup for dev_err_probe()
  kunit: test.h: fix a bad kernel-doc markup
  docs: amdgpu: fix a warning when building the documentation
  locking/refcount: document the new "oldp" pointer value
  usb: docs: document altmode register/unregister functions
  nl80211: docs: add a description for s1g_cap parameter
  IB/srpt: docs: add a description for cq_size member
  rcu/tree: docs: document bkvcache new members at struct kfree_rcu_cpu
  Input: sparse-keymap: add a description for @sw
  drm/amd/display: kernel-doc: document force_timing_sync
  drm: kernel-doc: drm_dp_helper.h: fix a typo
  gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markups
  drm: kernel-doc: add description for a new function parameter
  docs: virt: user_mode_linux_howto_v2.rst: fix a literal block markup
  workqueue: fix a kernel-doc warning
  mm/doc: fix a literal block markup
  drm: drm_edid: remove a duplicated kernel-doc declaration
  PM / devfreq: remove a duplicated kernel-doc markup

Nícolas F. R. A. Prado (1):
  docs: automarkup.py: make it ready for Sphinx 3.1+

 Documentation/admin-guide/pm/cpufreq.rst      |  11 +-
 Documentation/admin-guide/pstore-blk.rst      |  10 +-
 Documentation/block/blk-mq.rst                |  12 +-
 Documentation/block/inline-encryption.rst     |   8 +-
 Documentation/conf.py                         |  65 +++-
 Documentation/core-api/genericirq.rst         |   2 +
 Documentation/core-api/kernel-api.rst         |   6 -
 Documentation/core-api/workqueue.rst          |   2 +
 Documentation/dev-tools/kgdb.rst              |   6 +-
 .../bindings/display/tilcdc/tilcdc.txt        |   2 +-
 .../bindings/mailbox/omap-mailbox.txt         |   2 +-
 .../devicetree/bindings/media/i2c/tvp5150.txt |   2 +-
 .../bindings/pwm/google,cros-ec-pwm.yaml      |   2 +-
 .../bindings/soc/qcom/qcom,smd-rpm.yaml       |   2 +-
 .../bindings/sound/google,cros-ec-codec.yaml  |   2 +-
 Documentation/doc-guide/kernel-doc.rst        |   8 +
 Documentation/driver-api/basics.rst           |  19 +-
 Documentation/driver-api/device_link.rst      |  13 +-
 Documentation/driver-api/fpga/fpga-bridge.rst |   4 +-
 Documentation/driver-api/fpga/fpga-mgr.rst    |   6 +-
 .../driver-api/fpga/fpga-programming.rst      |   2 +-
 Documentation/driver-api/fpga/fpga-region.rst |   6 +-
 Documentation/driver-api/iio/buffers.rst      |   2 +-
 Documentation/driver-api/iio/core.rst         |   6 +-
 Documentation/driver-api/iio/hw-consumer.rst  |   2 +-
 .../driver-api/iio/triggered-buffers.rst      |   2 +-
 Documentation/driver-api/iio/triggers.rst     |   4 +-
 Documentation/driver-api/index.rst            |   1 -
 Documentation/driver-api/infrastructure.rst   |   4 +-
 Documentation/driver-api/libata.rst           |   2 +-
 Documentation/driver-api/media/cec-core.rst   |   2 +-
 .../driver-api/media/dtv-frontend.rst         |   4 +-
 Documentation/driver-api/media/mc-core.rst    |  24 +-
 .../driver-api/media/v4l2-controls.rst        |   2 +-
 Documentation/driver-api/media/v4l2-dev.rst   |   8 +-
 .../driver-api/media/v4l2-device.rst          |   6 +-
 Documentation/driver-api/media/v4l2-event.rst |  10 +-
 Documentation/driver-api/media/v4l2-fh.rst    |  16 +-
 .../driver-api/media/v4l2-subdev.rst          |   2 +-
 Documentation/driver-api/mei/mei.rst          |   2 +-
 Documentation/driver-api/pm/cpuidle.rst       |  65 ++--
 Documentation/driver-api/pm/devices.rst       |  26 +-
 Documentation/driver-api/regulator.rst        |   4 +-
 Documentation/driver-api/sound.rst            |  54 ----
 Documentation/driver-api/target.rst           |  12 -
 Documentation/driver-api/usb/URB.rst          |   2 +-
 Documentation/driver-api/usb/gadget.rst       |  10 +-
 Documentation/driver-api/usb/hotplug.rst      |   2 +-
 Documentation/driver-api/usb/typec_bus.rst    |   8 +-
 Documentation/filesystems/fscrypt.rst         |  61 ++--
 Documentation/filesystems/fsverity.rst        |   2 +-
 Documentation/gpu/amdgpu.rst                  |  11 +-
 Documentation/gpu/i915.rst                    |  29 +-
 Documentation/networking/ieee802154.rst       |  18 +-
 Documentation/powerpc/syscall64-abi.rst       |  32 +-
 Documentation/sound/designs/tracepoints.rst   |  22 +-
 .../sound/kernel-api/alsa-driver-api.rst      |   1 +
 .../kernel-api/writing-an-alsa-driver.rst     | 110 +++----
 Documentation/sphinx/automarkup.py            |  69 +++-
 Documentation/sphinx/cdomain.py               |  93 +++++-
 Documentation/sphinx/kerneldoc.py             |  15 +-
 Documentation/sphinx/parse-headers.pl         |   2 +-
 Documentation/trace/ftrace-uses.rst           |  12 +-
 .../it_IT/kernel-hacking/hacking.rst          |   2 +-
 .../it_IT/kernel-hacking/locking.rst          |   2 +
 .../translations/zh_CN/arm64/amu.rst          |   4 +-
 .../media/cec/cec-func-close.rst              |  10 +-
 .../media/cec/cec-func-ioctl.rst              |  11 +-
 .../userspace-api/media/cec/cec-func-open.rst |  10 +-
 .../userspace-api/media/cec/cec-func-poll.rst |  14 +-
 .../media/cec/cec-ioc-adap-g-caps.rst         |  10 +-
 .../media/cec/cec-ioc-adap-g-conn-info.rst    |  11 +-
 .../media/cec/cec-ioc-adap-g-log-addrs.rst    |  20 +-
 .../media/cec/cec-ioc-adap-g-phys-addr.rst    |  15 +-
 .../media/cec/cec-ioc-dqevent.rst             |  15 +-
 .../media/cec/cec-ioc-g-mode.rst              |  16 +-
 .../media/cec/cec-ioc-receive.rst             |  18 +-
 .../dvb/audio-bilingual-channel-select.rst    |   7 +-
 .../media/dvb/audio-channel-select.rst        |   8 +-
 .../media/dvb/audio-clear-buffer.rst          |   8 +-
 .../media/dvb/audio-continue.rst              |   7 +-
 .../userspace-api/media/dvb/audio-fclose.rst  |   7 +-
 .../userspace-api/media/dvb/audio-fopen.rst   |   7 +-
 .../userspace-api/media/dvb/audio-fwrite.rst  |   7 +-
 .../media/dvb/audio-get-capabilities.rst      |   8 +-
 .../media/dvb/audio-get-status.rst            |   8 +-
 .../userspace-api/media/dvb/audio-pause.rst   |   9 +-
 .../userspace-api/media/dvb/audio-play.rst    |   7 +-
 .../media/dvb/audio-select-source.rst         |   8 +-
 .../media/dvb/audio-set-av-sync.rst           |   8 +-
 .../media/dvb/audio-set-bypass-mode.rst       |   9 +-
 .../userspace-api/media/dvb/audio-set-id.rst  |   9 +-
 .../media/dvb/audio-set-mixer.rst             |   9 +-
 .../media/dvb/audio-set-mute.rst              |   8 +-
 .../media/dvb/audio-set-streamtype.rst        |  10 +-
 .../userspace-api/media/dvb/audio-stop.rst    |   9 +-
 .../userspace-api/media/dvb/ca-fclose.rst     |   7 +-
 .../userspace-api/media/dvb/ca-fopen.rst      |   7 +-
 .../userspace-api/media/dvb/ca-get-cap.rst    |   8 +-
 .../media/dvb/ca-get-descr-info.rst           |   9 +-
 .../userspace-api/media/dvb/ca-get-msg.rst    |  10 +-
 .../media/dvb/ca-get-slot-info.rst            |   9 +-
 .../userspace-api/media/dvb/ca-reset.rst      |   9 +-
 .../userspace-api/media/dvb/ca-send-msg.rst   |   9 +-
 .../userspace-api/media/dvb/ca-set-descr.rst  |   8 +-
 .../userspace-api/media/dvb/dmx-add-pid.rst   |  10 +-
 .../userspace-api/media/dvb/dmx-expbuf.rst    |  11 +-
 .../userspace-api/media/dvb/dmx-fclose.rst    |   9 +-
 .../userspace-api/media/dvb/dmx-fopen.rst     |   5 +-
 .../userspace-api/media/dvb/dmx-fread.rst     |   7 +-
 .../userspace-api/media/dvb/dmx-fwrite.rst    |   6 +-
 .../media/dvb/dmx-get-pes-pids.rst            |  12 +-
 .../userspace-api/media/dvb/dmx-get-stc.rst   |  12 +-
 .../userspace-api/media/dvb/dmx-mmap.rst      |  15 +-
 .../userspace-api/media/dvb/dmx-munmap.rst    |  14 +-
 .../userspace-api/media/dvb/dmx-qbuf.rst      |  17 +-
 .../userspace-api/media/dvb/dmx-querybuf.rst  |   9 +-
 .../media/dvb/dmx-remove-pid.rst              |  10 +-
 .../userspace-api/media/dvb/dmx-reqbufs.rst   |   9 +-
 .../media/dvb/dmx-set-buffer-size.rst         |  10 +-
 .../media/dvb/dmx-set-filter.rst              |  12 +-
 .../media/dvb/dmx-set-pes-filter.rst          |  13 +-
 .../userspace-api/media/dvb/dmx-start.rst     |  11 +-
 .../userspace-api/media/dvb/dmx-stop.rst      |   9 +-
 .../media/dvb/fe-diseqc-recv-slave-reply.rst  |   9 +-
 .../media/dvb/fe-diseqc-reset-overload.rst    |   9 +-
 .../media/dvb/fe-diseqc-send-burst.rst        |  10 +-
 .../media/dvb/fe-diseqc-send-master-cmd.rst   |   9 +-
 .../dvb/fe-dishnetwork-send-legacy-cmd.rst    |  10 +-
 .../media/dvb/fe-enable-high-lnb-voltage.rst  |  10 +-
 .../userspace-api/media/dvb/fe-get-event.rst  |  12 +-
 .../media/dvb/fe-get-frontend.rst             |  12 +-
 .../userspace-api/media/dvb/fe-get-info.rst   |  11 +-
 .../media/dvb/fe-get-property.rst             |  15 +-
 .../userspace-api/media/dvb/fe-read-ber.rst   |   9 +-
 .../media/dvb/fe-read-signal-strength.rst     |   9 +-
 .../userspace-api/media/dvb/fe-read-snr.rst   |   9 +-
 .../media/dvb/fe-read-status.rst              |  11 +-
 .../media/dvb/fe-read-uncorrected-blocks.rst  |   9 +-
 .../media/dvb/fe-set-frontend-tune-mode.rst   |  10 +-
 .../media/dvb/fe-set-frontend.rst             |  11 +-
 .../userspace-api/media/dvb/fe-set-tone.rst   |  10 +-
 .../media/dvb/fe-set-voltage.rst              |  10 +-
 .../media/dvb/frontend_f_close.rst            |   8 +-
 .../media/dvb/frontend_f_open.rst             |  10 +-
 .../userspace-api/media/dvb/net-add-if.rst    |   9 +-
 .../userspace-api/media/dvb/net-get-if.rst    |  10 +-
 .../userspace-api/media/dvb/net-remove-if.rst |  10 +-
 .../media/dvb/video-clear-buffer.rst          |   8 +-
 .../userspace-api/media/dvb/video-command.rst |  10 +-
 .../media/dvb/video-continue.rst              |   8 +-
 .../media/dvb/video-fast-forward.rst          |  10 +-
 .../userspace-api/media/dvb/video-fclose.rst  |   6 +-
 .../userspace-api/media/dvb/video-fopen.rst   |   6 +-
 .../userspace-api/media/dvb/video-freeze.rst  |   8 +-
 .../userspace-api/media/dvb/video-fwrite.rst  |   6 +-
 .../media/dvb/video-get-capabilities.rst      |   8 +-
 .../media/dvb/video-get-event.rst             |   8 +-
 .../media/dvb/video-get-frame-count.rst       |   8 +-
 .../userspace-api/media/dvb/video-get-pts.rst |   8 +-
 .../media/dvb/video-get-size.rst              |   8 +-
 .../media/dvb/video-get-status.rst            |   7 +-
 .../userspace-api/media/dvb/video-play.rst    |   8 +-
 .../media/dvb/video-select-source.rst         |   7 +-
 .../media/dvb/video-set-blank.rst             |   8 +-
 .../media/dvb/video-set-display-format.rst    |   8 +-
 .../media/dvb/video-set-format.rst            |   9 +-
 .../media/dvb/video-set-streamtype.rst        |   8 +-
 .../media/dvb/video-slowmotion.rst            |  10 +-
 .../media/dvb/video-stillpicture.rst          |   8 +-
 .../userspace-api/media/dvb/video-stop.rst    |   8 +-
 .../media/dvb/video-try-command.rst           |   8 +-
 .../media/mediactl/media-func-close.rst       |  10 +-
 .../media/mediactl/media-func-ioctl.rst       |  10 +-
 .../media/mediactl/media-func-open.rst        |  10 +-
 .../media/mediactl/media-ioc-device-info.rst  |  13 +-
 .../mediactl/media-ioc-enum-entities.rst      |  11 +-
 .../media/mediactl/media-ioc-enum-links.rst   |  13 +-
 .../media/mediactl/media-ioc-g-topology.rst   |  14 +-
 .../mediactl/media-ioc-request-alloc.rst      |  11 +-
 .../media/mediactl/media-ioc-setup-link.rst   |  10 +-
 .../mediactl/media-request-ioc-queue.rst      |   7 +-
 .../mediactl/media-request-ioc-reinit.rst     |   8 +-
 .../media/mediactl/request-api.rst            |   5 +-
 .../media/mediactl/request-func-close.rst     |   8 +-
 .../media/mediactl/request-func-ioctl.rst     |   8 +-
 .../media/mediactl/request-func-poll.rst      |  12 +-
 .../media/rc/lirc-get-features.rst            |   9 +-
 .../media/rc/lirc-get-rec-mode.rst            |  12 +-
 .../media/rc/lirc-get-rec-resolution.rst      |   8 +-
 .../media/rc/lirc-get-send-mode.rst           |  14 +-
 .../media/rc/lirc-get-timeout.rst             |  13 +-
 .../userspace-api/media/rc/lirc-read.rst      |  10 +-
 .../rc/lirc-set-measure-carrier-mode.rst      |   8 +-
 .../media/rc/lirc-set-rec-carrier-range.rst   |   6 +-
 .../media/rc/lirc-set-rec-carrier.rst         |   8 +-
 .../media/rc/lirc-set-rec-timeout-reports.rst |   8 +-
 .../media/rc/lirc-set-rec-timeout.rst         |  13 +-
 .../media/rc/lirc-set-send-carrier.rst        |   8 +-
 .../media/rc/lirc-set-send-duty-cycle.rst     |   8 +-
 .../media/rc/lirc-set-transmitter-mask.rst    |   8 +-
 .../media/rc/lirc-set-wideband-receiver.rst   |   8 +-
 .../userspace-api/media/rc/lirc-write.rst     |   7 +-
 .../userspace-api/media/v4l/buffer.rst        |  28 +-
 .../userspace-api/media/v4l/dev-capture.rst   |   7 +-
 .../userspace-api/media/v4l/dev-output.rst    |   7 +-
 .../userspace-api/media/v4l/dev-raw-vbi.rst   |  19 +-
 .../userspace-api/media/v4l/dev-rds.rst       |  12 +-
 .../media/v4l/dev-sliced-vbi.rst              |  31 +-
 .../userspace-api/media/v4l/diff-v4l.rst      |  39 +--
 .../userspace-api/media/v4l/dmabuf.rst        |   8 +-
 .../userspace-api/media/v4l/format.rst        |   7 +-
 .../userspace-api/media/v4l/func-close.rst    |   8 +-
 .../userspace-api/media/v4l/func-ioctl.rst    |  10 +-
 .../userspace-api/media/v4l/func-mmap.rst     |  18 +-
 .../userspace-api/media/v4l/func-munmap.rst   |  14 +-
 .../userspace-api/media/v4l/func-open.rst     |  14 +-
 .../userspace-api/media/v4l/func-poll.rst     |  40 ++-
 .../userspace-api/media/v4l/func-read.rst     |  39 ++-
 .../userspace-api/media/v4l/func-select.rst   |  42 ++-
 .../userspace-api/media/v4l/func-write.rst    |  13 +-
 .../userspace-api/media/v4l/hist-v4l2.rst     |  70 +---
 Documentation/userspace-api/media/v4l/io.rst  |   6 +-
 .../media/v4l/libv4l-introduction.rst         |  30 +-
 .../userspace-api/media/v4l/mmap.rst          |  26 +-
 .../userspace-api/media/v4l/open.rst          |  15 +-
 Documentation/userspace-api/media/v4l/rw.rst  |  18 +-
 .../userspace-api/media/v4l/streaming-par.rst |   5 +-
 .../userspace-api/media/v4l/userp.rst         |  11 +-
 .../media/v4l/vidioc-create-bufs.rst          |  11 +-
 .../media/v4l/vidioc-cropcap.rst              |  11 +-
 .../media/v4l/vidioc-dbg-g-chip-info.rst      |  13 +-
 .../media/v4l/vidioc-dbg-g-register.rst       |  18 +-
 .../media/v4l/vidioc-decoder-cmd.rst          |  19 +-
 .../media/v4l/vidioc-dqevent.rst              |  19 +-
 .../media/v4l/vidioc-dv-timings-cap.rst       |  17 +-
 .../media/v4l/vidioc-encoder-cmd.rst          |  25 +-
 .../media/v4l/vidioc-enum-dv-timings.rst      |  16 +-
 .../media/v4l/vidioc-enum-fmt.rst             |  12 +-
 .../media/v4l/vidioc-enum-frameintervals.rst  |  15 +-
 .../media/v4l/vidioc-enum-framesizes.rst      |  16 +-
 .../media/v4l/vidioc-enum-freq-bands.rst      |  12 +-
 .../media/v4l/vidioc-enumaudio.rst            |  10 +-
 .../media/v4l/vidioc-enumaudioout.rst         |  10 +-
 .../media/v4l/vidioc-enuminput.rst            |  14 +-
 .../media/v4l/vidioc-enumoutput.rst           |  13 +-
 .../media/v4l/vidioc-enumstd.rst              |  23 +-
 .../userspace-api/media/v4l/vidioc-expbuf.rst |  14 +-
 .../media/v4l/vidioc-g-audio.rst              |  18 +-
 .../media/v4l/vidioc-g-audioout.rst           |  16 +-
 .../userspace-api/media/v4l/vidioc-g-crop.rst |  16 +-
 .../userspace-api/media/v4l/vidioc-g-ctrl.rst |  16 +-
 .../media/v4l/vidioc-g-dv-timings.rst         |  26 +-
 .../userspace-api/media/v4l/vidioc-g-edid.rst |  25 +-
 .../media/v4l/vidioc-g-enc-index.rst          |  13 +-
 .../media/v4l/vidioc-g-ext-ctrls.rst          |  21 +-
 .../userspace-api/media/v4l/vidioc-g-fbuf.rst |  18 +-
 .../userspace-api/media/v4l/vidioc-g-fmt.rst  |  22 +-
 .../media/v4l/vidioc-g-frequency.rst          |  16 +-
 .../media/v4l/vidioc-g-input.rst              |  15 +-
 .../media/v4l/vidioc-g-jpegcomp.rst           |  17 +-
 .../media/v4l/vidioc-g-modulator.rst          |  17 +-
 .../media/v4l/vidioc-g-output.rst             |  15 +-
 .../userspace-api/media/v4l/vidioc-g-parm.rst |  30 +-
 .../media/v4l/vidioc-g-priority.rst           |  16 +-
 .../media/v4l/vidioc-g-selection.rst          |  15 +-
 .../media/v4l/vidioc-g-sliced-vbi-cap.rst     |  12 +-
 .../userspace-api/media/v4l/vidioc-g-std.rst  |  24 +-
 .../media/v4l/vidioc-g-tuner.rst              |  19 +-
 .../media/v4l/vidioc-log-status.rst           |  10 +-
 .../media/v4l/vidioc-overlay.rst              |  10 +-
 .../media/v4l/vidioc-prepare-buf.rst          |  10 +-
 .../userspace-api/media/v4l/vidioc-qbuf.rst   |  17 +-
 .../media/v4l/vidioc-query-dv-timings.rst     |  15 +-
 .../media/v4l/vidioc-querybuf.rst             |  10 +-
 .../media/v4l/vidioc-querycap.rst             |  16 +-
 .../media/v4l/vidioc-queryctrl.rst            |  22 +-
 .../media/v4l/vidioc-querystd.rst             |  15 +-
 .../media/v4l/vidioc-reqbufs.rst              |  10 +-
 .../media/v4l/vidioc-s-hw-freq-seek.rst       |  11 +-
 .../media/v4l/vidioc-streamon.rst             |  14 +-
 .../v4l/vidioc-subdev-enum-frame-interval.rst |  10 +-
 .../v4l/vidioc-subdev-enum-frame-size.rst     |  11 +-
 .../v4l/vidioc-subdev-enum-mbus-code.rst      |  10 +-
 .../media/v4l/vidioc-subdev-g-crop.rst        |  16 +-
 .../media/v4l/vidioc-subdev-g-fmt.rst         |  17 +-
 .../v4l/vidioc-subdev-g-frame-interval.rst    |  16 +-
 .../media/v4l/vidioc-subdev-g-selection.rst   |  17 +-
 .../media/v4l/vidioc-subdev-querycap.rst      |   9 +-
 .../media/v4l/vidioc-subscribe-event.rst      |  17 +-
 .../virt/uml/user_mode_linux_howto_v2.rst     |   1 +
 Documentation/vm/hmm.rst                      |   2 +-
 Documentation/vm/ksm.rst                      |   2 +-
 Documentation/vm/memory-model.rst             |   6 +-
 MAINTAINERS                                   |  16 +-
 block/bio.c                                   |   4 +-
 drivers/base/core.c                           |   7 +-
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h |   2 +
 drivers/gpu/drm/drm_prime.c                   |   1 +
 drivers/infiniband/ulp/srpt/ib_srpt.h         |   1 +
 drivers/net/appletalk/Kconfig                 |   2 +-
 drivers/net/hamradio/scc.c                    |   2 +-
 include/drm/drm_dp_helper.h                   |   2 +-
 include/drm/drm_edid.h                        |   7 -
 include/kunit/test.h                          |  16 +-
 include/linux/devfreq.h                       |   7 +-
 include/linux/input/sparse-keymap.h           |   1 +
 include/linux/math64.h                        |   8 +-
 include/linux/refcount.h                      |   7 +
 include/linux/usb/typec_altmode.h             |  16 +
 include/net/cfg80211.h                        |   1 +
 kernel/rcu/tree.c                             |  14 +-
 kernel/workqueue.c                            |   3 +
 mm/ksm.c                                      |   2 +-
 mm/memblock.c                                 |   8 +-
 scripts/kernel-doc                            | 303 +++++++++++++-----
 316 files changed, 1921 insertions(+), 2285 deletions(-)
 delete mode 100644 Documentation/driver-api/sound.rst

-- 
2.26.2

[PATCH v6 01/80] scripts: kernel-doc: add support for typedef enum

[Mauro Carvalho Chehab]

The PHY kernel-doc markup has gained support for documenting
a typedef enum.

However, right now the parser was not prepared for it.

So, add support for parsing it.

Fixes: 4069a572d423 ("net: phy: Document core PHY structures")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 724528f4b7d6..adc05406c68e 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1265,14 +1265,22 @@ sub show_warnings($$) {
 sub dump_enum($$) {
     my $x = shift;
     my $file = shift;
+    my $members;
+
 
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
     # strip #define macros inside enums
     $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
 
-    if ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
+    if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
+	$declaration_name = $2;
+	$members = $1;
+    } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
 	$declaration_name = $1;
-	my $members = $2;
+	$members = $2;
+    }
+
+    if ($declaration_name) {
 	my %_members;
 
 	$members =~ s/\s+$//;
@@ -1307,8 +1315,7 @@ sub dump_enum($$) {
 			    'sections' => \%sections,
 			    'purpose' => $declaration_purpose
 			   });
-    }
-    else {
+    } else {
 	print STDERR "${file}:$.: error: Cannot parse enum!\n";
 	++$errors;
     }
-- 
2.26.2

[PATCH v6 02/80] scripts: kernel-doc: make it more compatible with Sphinx 3.x

[Mauro Carvalho Chehab]

With Sphinx 3.x, the ".. c:type:" tag was changed to accept either:

	.. c:type:: typedef-like declaration
	.. c:type:: name

Using it for other types (including functions) don't work anymore.

So, there are newer tags for macro, enum, struct, union, and others,
which doesn't exist on older versions.

Add a check for the Sphinx version and change the produced tags
accordingly.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 71 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 65 insertions(+), 6 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index adc05406c68e..096317ef2e97 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -271,6 +271,8 @@ if ($#ARGV == -1) {
 }
 
 my $kernelversion;
+my $sphinx_major;
+
 my $dohighlight = "";
 
 my $verbose = 0;
@@ -465,6 +467,43 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
 
 # continue execution near EOF;
 
+# The C domain dialect changed on Sphinx 3. So, we need to check the
+# version in order to produce the right tags.
+sub findprog($)
+{
+	foreach(split(/:/, $ENV{PATH})) {
+		return "$_/$_[0]" if(-x "$_/$_[0]");
+	}
+}
+
+sub get_sphinx_version()
+{
+	my $ver;
+	my $major = 1;
+
+	my $cmd = "sphinx-build";
+	if (!findprog($cmd)) {
+		my $cmd = "sphinx-build3";
+		return $major if (!findprog($cmd));
+	}
+
+	open IN, "$cmd --version 2>&1 |";
+	while (<IN>) {
+		if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
+			$major=$1;
+			last;
+		}
+		# Sphinx 1.2.x uses a different format
+		if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
+			$major=$1;
+			last;
+		}
+	}
+	close IN;
+
+	return $major;
+}
+
 # get kernel version from env
 sub get_kernel_version() {
     my $version = 'unknown kernel version';
@@ -848,7 +887,11 @@ sub output_function_rst(%) {
     my $start = "";
 
     if ($args{'typedef'}) {
-	print ".. c:type:: ". $args{'function'} . "\n\n";
+	if ($sphinx_major < 3) {
+	    print ".. c:type:: ". $args{'function'} . "\n\n";
+	} else {
+	    print ".. c:function:: ". $args{'function'} . "\n\n";
+	}
 	print_lineno($declaration_start_line);
 	print "   **Typedef**: ";
 	$lineprefix = "";
@@ -938,9 +981,14 @@ sub output_enum_rst(%) {
     my ($parameter);
     my $oldprefix = $lineprefix;
     my $count;
-    my $name = "enum " . $args{'enum'};
 
-    print "\n\n.. c:type:: " . $name . "\n\n";
+    if ($sphinx_major < 3) {
+	my $name = "enum " . $args{'enum'};
+	print "\n\n.. c:type:: " . $name . "\n\n";
+    } else {
+	my $name = $args{'enum'};
+	print "\n\n.. c:enum:: " . $name . "\n\n";
+    }
     print_lineno($declaration_start_line);
     $lineprefix = "   ";
     output_highlight_rst($args{'purpose'});
@@ -966,8 +1014,13 @@ sub output_typedef_rst(%) {
     my %args = %{$_[0]};
     my ($parameter);
     my $oldprefix = $lineprefix;
-    my $name = "typedef " . $args{'typedef'};
+    my $name;
 
+    if ($sphinx_major < 3) {
+	$name = "typedef " . $args{'typedef'};
+    } else {
+	$name = $args{'typedef'};
+    }
     print "\n\n.. c:type:: " . $name . "\n\n";
     print_lineno($declaration_start_line);
     $lineprefix = "   ";
@@ -982,9 +1035,14 @@ sub output_struct_rst(%) {
     my %args = %{$_[0]};
     my ($parameter);
     my $oldprefix = $lineprefix;
-    my $name = $args{'type'} . " " . $args{'struct'};
 
-    print "\n\n.. c:type:: " . $name . "\n\n";
+    if ($sphinx_major < 3) {
+	my $name = $args{'type'} . " " . $args{'struct'};
+	print "\n\n.. c:type:: " . $name . "\n\n";
+    } else {
+	my $name = $args{'struct'};
+	print "\n\n.. c:struct:: " . $name . "\n\n";
+    }
     print_lineno($declaration_start_line);
     $lineprefix = "   ";
     output_highlight_rst($args{'purpose'});
@@ -2242,6 +2300,7 @@ sub process_file($) {
 }
 
 
+$sphinx_major = get_sphinx_version();
 $kernelversion = get_kernel_version();
 
 # generate a sequence of code that will splice in highlighting information
-- 
2.26.2

[PATCH v6 03/80] scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x

[Mauro Carvalho Chehab]

Unfortunately, Sphinx 3.x parser for c functions is too pedantic:

	https://github.com/sphinx-doc/sphinx/issues/8241

While it could be relaxed with some configurations, there are
several corner cases that it would make it hard to maintain,
and will require teaching conf.py about several macros.

So, let's instead use the :c:macro notation. This will
produce an output that it is not as nice as currently, but it
should still be acceptable, and will provide cross-references,
removing thousands of warnings when building with newer
versions of Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 34 ++++++++++++++++++++++++----------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 096317ef2e97..d9783c98f33b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -886,19 +886,29 @@ sub output_function_rst(%) {
     my $oldprefix = $lineprefix;
     my $start = "";
 
-    if ($args{'typedef'}) {
-	if ($sphinx_major < 3) {
+    if ($sphinx_major < 3) {
+	if ($args{'typedef'}) {
 	    print ".. c:type:: ". $args{'function'} . "\n\n";
+	    print_lineno($declaration_start_line);
+	    print "   **Typedef**: ";
+	    $lineprefix = "";
+	    output_highlight_rst($args{'purpose'});
+	    $start = "\n\n**Syntax**\n\n  ``";
 	} else {
-	    print ".. c:function:: ". $args{'function'} . "\n\n";
+	    print ".. c:function:: ";
 	}
-	print_lineno($declaration_start_line);
-	print "   **Typedef**: ";
-	$lineprefix = "";
-	output_highlight_rst($args{'purpose'});
-	$start = "\n\n**Syntax**\n\n  ``";
     } else {
-	print ".. c:function:: ";
+	print ".. c:macro:: ". $args{'function'} . "\n\n";
+
+	if ($args{'typedef'}) {
+	    print_lineno($declaration_start_line);
+	    print "   **Typedef**: ";
+	    $lineprefix = "";
+	    output_highlight_rst($args{'purpose'});
+	    $start = "\n\n**Syntax**\n\n  ``";
+	} else {
+	    print "``";
+	}
     }
     if ($args{'functiontype'} ne "") {
 	$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
@@ -925,7 +935,11 @@ sub output_function_rst(%) {
     if ($args{'typedef'}) {
 	print ");``\n\n";
     } else {
-	print ")\n\n";
+	if ($sphinx_major < 3) {
+	    print ")\n\n";
+	} else {
+	    print ")``\n";
+	}
 	print_lineno($declaration_start_line);
 	$lineprefix = "   ";
 	output_highlight_rst($args{'purpose'});
-- 
2.26.2

[PATCH v6 04/80] scripts: kernel-doc: fix troubles with line counts

[Mauro Carvalho Chehab]

There's currently a bug with the way kernel-doc script
counts line numbers that can be seen with:

	$ ./scripts/kernel-doc -rst  -enable-lineno include/linux/math64.h >all && ./scripts/kernel-doc -rst -internal -enable-lineno include/linux/math64.h >int && diff -U0 int all

	--- int	2020-09-28 12:58:08.927486808 +0200
	+++ all	2020-09-28 12:58:08.905486845 +0200
	@@ -1 +1 @@
	-#define LINENO 27
	+#define LINENO 26
	@@ -3 +3 @@
	-#define LINENO 16
	+#define LINENO 15
	@@ -9 +9 @@
	-#define LINENO 17
	+#define LINENO 16
	...

This is happening with perl version 5.30.3, but I'm not
so sure if this is a perl bug, or if this is due to something
else.

In any case, fixing it is easy. Basically, when "-internal"
parameter is used, the process_export_file() function opens the
handle "IN". This makes the line number to be incremented, as the
handler for the main open is also "IN".

Fix the problem by using a different handler for the
main open().

While here, add a missing close for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index d9783c98f33b..bdd2ebb4ac41 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2268,7 +2268,7 @@ sub process_file($) {
 
     $file = map_filename($orig_file);
 
-    if (!open(IN,"<$file")) {
+    if (!open(IN_FILE,"<$file")) {
 	print STDERR "Error: Cannot open file $file\n";
 	++$errors;
 	return;
@@ -2277,9 +2277,9 @@ sub process_file($) {
     $. = 1;
 
     $section_counter = 0;
-    while (<IN>) {
+    while (<IN_FILE>) {
 	while (s/\\\s*$//) {
-	    $_ .= <IN>;
+	    $_ .= <IN_FILE>;
 	}
 	# Replace tabs by spaces
         while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
@@ -2311,6 +2311,7 @@ sub process_file($) {
 	    print STDERR "${file}:1: warning: no structured comments found\n";
 	}
     }
+    close IN_FILE;
 }
 
 
-- 
2.26.2

[PATCH v6 05/80] scripts: kernel-doc: reimplement -nofunction argument

[Mauro Carvalho Chehab]

Right now, the build system doesn't use -nofunction, as
it is pretty much useless, because it doesn't consider
the other output modes (extern, internal), working only
with all.

Also, it is limited to exclude functions.

Re-implement it in order to allow excluding any symbols from
the document output, no matter what mode is used.

The parameter was also renamed to "-nosymbol", as it express
better its meaning.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 44 +++++++++++++++++++++-----------------------
 1 file changed, 21 insertions(+), 23 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index bdd2ebb4ac41..6a7996c96bbb 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -66,9 +66,8 @@ Output selection (mutually exclusive):
   -function NAME	Only output documentation for the given function(s)
 			or DOC: section title(s). All other functions and DOC:
 			sections are ignored. May be specified multiple times.
-  -nofunction NAME	Do NOT output documentation for the given function(s);
-			only output documentation for the other functions and
-			DOC: sections. May be specified multiple times.
+  -nosymbol NAME	Exclude the specified symbols from the output
+		        documentation. May be specified multiple times.
 
 Output selection modifiers:
   -no-doc-sections	Do not output DOC: sections.
@@ -288,9 +287,8 @@ my $modulename = "Kernel API";
 use constant {
     OUTPUT_ALL          => 0, # output all symbols and doc sections
     OUTPUT_INCLUDE      => 1, # output only specified symbols
-    OUTPUT_EXCLUDE      => 2, # output everything except specified symbols
-    OUTPUT_EXPORTED     => 3, # output exported symbols
-    OUTPUT_INTERNAL     => 4, # output non-exported symbols
+    OUTPUT_EXPORTED     => 2, # output exported symbols
+    OUTPUT_INTERNAL     => 3, # output non-exported symbols
 };
 my $output_selection = OUTPUT_ALL;
 my $show_not_found = 0;	# No longer used
@@ -315,6 +313,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
 # CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
 # could cause "use of undefined value" or other bugs.
 my ($function, %function_table, %parametertypes, $declaration_purpose);
+my %nosymbol_table = ();
 my $declaration_start_line;
 my ($type, $declaration_name, $return_type);
 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
@@ -434,10 +433,9 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
 	$output_selection = OUTPUT_INCLUDE;
 	$function = shift @ARGV;
 	$function_table{$function} = 1;
-    } elsif ($cmd eq "nofunction") { # output all except specific functions
-	$output_selection = OUTPUT_EXCLUDE;
-	$function = shift @ARGV;
-	$function_table{$function} = 1;
+    } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
+	my $symbol = shift @ARGV;
+	$nosymbol_table{$symbol} = 1;
     } elsif ($cmd eq "export") { # only exported symbols
 	$output_selection = OUTPUT_EXPORTED;
 	%function_table = ();
@@ -570,11 +568,11 @@ sub dump_doc_section {
         return;
     }
 
+    return if (defined($nosymbol_table{$name}));
+
     if (($output_selection == OUTPUT_ALL) ||
-	($output_selection == OUTPUT_INCLUDE &&
-	 defined($function_table{$name})) ||
-	($output_selection == OUTPUT_EXCLUDE &&
-	 !defined($function_table{$name})))
+	(($output_selection == OUTPUT_INCLUDE) &&
+	 defined($function_table{$name})))
     {
 	dump_section($file, $name, $contents);
 	output_blockhead({'sectionlist' => \@sectionlist,
@@ -800,6 +798,8 @@ sub output_blockhead_rst(%) {
     my ($parameter, $section);
 
     foreach $section (@{$args{'sectionlist'}}) {
+	next if (defined($nosymbol_table{$section}));
+
 	if ($output_selection != OUTPUT_INCLUDE) {
 	    print "**$section**\n\n";
 	}
@@ -1115,12 +1115,14 @@ sub output_declaration {
     my $name = shift;
     my $functype = shift;
     my $func = "output_${functype}_$output_mode";
+
+    return if (defined($nosymbol_table{$name}));
+
     if (($output_selection == OUTPUT_ALL) ||
 	(($output_selection == OUTPUT_INCLUDE ||
 	  $output_selection == OUTPUT_EXPORTED) &&
 	 defined($function_table{$name})) ||
-	(($output_selection == OUTPUT_EXCLUDE ||
-	  $output_selection == OUTPUT_INTERNAL) &&
+	($output_selection == OUTPUT_INTERNAL &&
 	 !($functype eq "function" && defined($function_table{$name}))))
     {
 	&$func(@_);
@@ -1301,6 +1303,8 @@ sub show_warnings($$) {
 	my $functype = shift;
 	my $name = shift;
 
+	return 0 if (defined($nosymbol_table{$name}));
+
 	return 1 if ($output_selection == OUTPUT_ALL);
 
 	if ($output_selection == OUTPUT_EXPORTED) {
@@ -1324,13 +1328,6 @@ sub show_warnings($$) {
 			return 0;
 		}
 	}
-	if ($output_selection == OUTPUT_EXCLUDE) {
-		if (!defined($function_table{$name})) {
-			return 1;
-		} else {
-			return 0;
-		}
-	}
 	die("Please add the new output type at show_warnings()");
 }
 
@@ -1952,6 +1949,7 @@ sub process_export_file($) {
 
     while (<IN>) {
 	if (/$export_symbol/) {
+	    next if (defined($nosymbol_table{$2}));
 	    $function_table{$2} = 1;
 	}
     }
-- 
2.26.2

[PATCH v6 06/80] scripts: kernel-doc: fix typedef identification

[Mauro Carvalho Chehab]

Some typedef expressions are output as normal functions.

As we need to be clearer about the type with Sphinx 3.x,
detect such cases.

While here, fix a wrongly-indented block.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 62 ++++++++++++++++++++++++++++++----------------
 1 file changed, 40 insertions(+), 22 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 6a7996c96bbb..33ad3ce66f73 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1748,30 +1748,48 @@ sub dump_function($$) {
 	return;
     }
 
-	my $prms = join " ", @parameterlist;
-	check_sections($file, $declaration_name, "function", $sectcheck, $prms);
+    my $prms = join " ", @parameterlist;
+    check_sections($file, $declaration_name, "function", $sectcheck, $prms);
 
-        # This check emits a lot of warnings at the moment, because many
-        # functions don't have a 'Return' doc section. So until the number
-        # of warnings goes sufficiently down, the check is only performed in
-        # verbose mode.
-        # TODO: always perform the check.
-        if ($verbose && !$noret) {
-                check_return_section($file, $declaration_name, $return_type);
-        }
+    # This check emits a lot of warnings at the moment, because many
+    # functions don't have a 'Return' doc section. So until the number
+    # of warnings goes sufficiently down, the check is only performed in
+    # verbose mode.
+    # TODO: always perform the check.
+    if ($verbose && !$noret) {
+	    check_return_section($file, $declaration_name, $return_type);
+    }
 
-    output_declaration($declaration_name,
-		       'function',
-		       {'function' => $declaration_name,
-			'module' => $modulename,
-			'functiontype' => $return_type,
-			'parameterlist' => \@parameterlist,
-			'parameterdescs' => \%parameterdescs,
-			'parametertypes' => \%parametertypes,
-			'sectionlist' => \@sectionlist,
-			'sections' => \%sections,
-			'purpose' => $declaration_purpose
-		       });
+    # The function parser can be called with a typedef parameter.
+    # Handle it.
+    if ($return_type =~ /typedef/) {
+	output_declaration($declaration_name,
+			   'function',
+			   {'function' => $declaration_name,
+			    'typedef' => 1,
+			    'module' => $modulename,
+			    'functiontype' => $return_type,
+			    'parameterlist' => \@parameterlist,
+			    'parameterdescs' => \%parameterdescs,
+			    'parametertypes' => \%parametertypes,
+			    'sectionlist' => \@sectionlist,
+			    'sections' => \%sections,
+			    'purpose' => $declaration_purpose
+			   });
+    } else {
+	output_declaration($declaration_name,
+			   'function',
+			   {'function' => $declaration_name,
+			    'module' => $modulename,
+			    'functiontype' => $return_type,
+			    'parameterlist' => \@parameterlist,
+			    'parameterdescs' => \%parameterdescs,
+			    'parametertypes' => \%parametertypes,
+			    'sectionlist' => \@sectionlist,
+			    'sections' => \%sections,
+			    'purpose' => $declaration_purpose
+			   });
+    }
 }
 
 sub reset_state {
-- 
2.26.2

[PATCH v6 07/80] scripts: kernel-doc: don't mangle with parameter list

[Mauro Carvalho Chehab]

While kernel-doc needs to parse parameters in order to
identify its name, it shouldn't be touching the type,
as parsing it is very difficult, and errors happen.

One current error is when parsing this parameter:

	const u32 (*tab)[256]

Found at ./lib/crc32.c, on this function:

	u32 __pure crc32_be_generic (u32 crc, unsigned char const *p, size_t len, const u32 (*tab)[256], u32 polynomial);

The current logic mangles it, producing this output:

	const u32 ( *tab

That's something that it is not recognizeable.

So, instead, let's push the argument as-is, and use it
when printing the function prototype and when describing
each argument.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 26 ++++++++++++++------------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 33ad3ce66f73..09e3e78b9723 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -655,10 +655,10 @@ sub output_function_man(%) {
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
-	    print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
+	    print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";
 	} else {
 	    $type =~ s/([^\*])$/$1 /;
-	    print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
+	    print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
 	}
 	$count++;
 	$parenth = "";
@@ -929,7 +929,7 @@ sub output_function_rst(%) {
 	    # pointer-to-function
 	    print $1 . $parameter . ") (" . $2 . ")";
 	} else {
-	    print $type . " " . $parameter;
+	    print $type;
 	}
     }
     if ($args{'typedef'}) {
@@ -954,7 +954,7 @@ sub output_function_rst(%) {
 	$type = $args{'parametertypes'}{$parameter};
 
 	if ($type ne "") {
-	    print "``$type $parameter``\n";
+	    print "``$type``\n";
 	} else {
 	    print "``$parameter``\n";
 	}
@@ -1479,7 +1479,7 @@ sub create_parameterlist($$$$) {
 	    # Treat preprocessor directive as a typeless variable just to fill
 	    # corresponding data structures "correctly". Catch it later in
 	    # output_* subs.
-	    push_parameter($arg, "", $file);
+	    push_parameter($arg, "", "", $file);
 	} elsif ($arg =~ m/\(.+\)\s*\(/) {
 	    # pointer-to-function
 	    $arg =~ tr/#/,/;
@@ -1488,7 +1488,7 @@ sub create_parameterlist($$$$) {
 	    $type = $arg;
 	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
 	    save_struct_actual($param);
-	    push_parameter($param, $type, $file, $declaration_name);
+	    push_parameter($param, $type, $arg, $file, $declaration_name);
 	} elsif ($arg) {
 	    $arg =~ s/\s*:\s*/:/g;
 	    $arg =~ s/\s*\[/\[/g;
@@ -1513,26 +1513,28 @@ sub create_parameterlist($$$$) {
 	    foreach $param (@args) {
 		if ($param =~ m/^(\*+)\s*(.*)/) {
 		    save_struct_actual($2);
-		    push_parameter($2, "$type $1", $file, $declaration_name);
+
+		    push_parameter($2, "$type $1", $arg, $file, $declaration_name);
 		}
 		elsif ($param =~ m/(.*?):(\d+)/) {
 		    if ($type ne "") { # skip unnamed bit-fields
 			save_struct_actual($1);
-			push_parameter($1, "$type:$2", $file, $declaration_name)
+			push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
 		    }
 		}
 		else {
 		    save_struct_actual($param);
-		    push_parameter($param, $type, $file, $declaration_name);
+		    push_parameter($param, $type, $arg, $file, $declaration_name);
 		}
 	    }
 	}
     }
 }
 
-sub push_parameter($$$$) {
+sub push_parameter($$$$$) {
 	my $param = shift;
 	my $type = shift;
+	my $org_arg = shift;
 	my $file = shift;
 	my $declaration_name = shift;
 
@@ -1596,8 +1598,8 @@ sub push_parameter($$$$) {
 	# "[blah" in a parameter string;
 	###$param =~ s/\s*//g;
 	push @parameterlist, $param;
-	$type =~ s/\s\s+/ /g;
-	$parametertypes{$param} = $type;
+	$org_arg =~ s/\s\s+/ /g;
+	$parametertypes{$param} = $org_arg;
 }
 
 sub check_sections($$$$$) {
-- 
2.26.2

[PATCH v6 08/80] scripts: kernel-doc: allow passing desired Sphinx C domain dialect

[Mauro Carvalho Chehab]

When kernel-doc is called via kerneldoc.py, there's no need to
auto-detect the Sphinx version, as the Sphinx module already
knows it. So, add an optional parameter to allow changing the
Sphinx dialect.

As kernel-doc can also be manually called, keep the auto-detection
logic if the parameter was not specified. On such case, emit
a warning if sphinx-build can't be found at PATH.

I ended using a suggestion from Joe for using a more readable
regex, instead of using a complex one with a hidden group like:

	m/^(\d+)\.(\d+)(?:\.?(\d+)?)/

in order to get the optional <patch> argument.

Thanks-to: Joe Perches <joe@perches.com>
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/kerneldoc.py |  5 +++
 scripts/kernel-doc                | 51 ++++++++++++++++++++++++++-----
 2 files changed, 48 insertions(+), 8 deletions(-)

diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index 4bcbd6ae01cd..1a1b12242a45 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -70,6 +70,11 @@ class KernelDocDirective(Directive):
         env = self.state.document.settings.env
         cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno']
 
+	# Pass the version string to kernel-doc, as it needs to use a different
+	# dialect, depending what the C domain supports for each specific
+	# Sphinx versions
+        cmd += ['-sphinx-version', sphinx.__version__]
+
         filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
         export_file_patterns = []
 
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 09e3e78b9723..ed32883c3221 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -56,6 +56,13 @@ Output format selection (mutually exclusive):
   -rst			Output reStructuredText format.
   -none			Do not output documentation, only warnings.
 
+Output format selection modifier (affects only ReST output):
+
+  -sphinx-version	Use the ReST C domain dialect compatible with an
+			specific Sphinx Version.
+			If not specified, kernel-doc will auto-detect using
+			the sphinx-build version found on PATH.
+
 Output selection (mutually exclusive):
   -export		Only output documentation for symbols that have been
 			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
@@ -270,7 +277,7 @@ if ($#ARGV == -1) {
 }
 
 my $kernelversion;
-my $sphinx_major;
+my ($sphinx_major, $sphinx_minor, $sphinx_patch);
 
 my $dohighlight = "";
 
@@ -457,6 +464,23 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
 	    $enable_lineno = 1;
     } elsif ($cmd eq 'show-not-found') {
 	$show_not_found = 1;  # A no-op but don't fail
+    } elsif ($cmd eq "sphinx-version") {
+	my $ver_string = shift @ARGV;
+	if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {
+	    $sphinx_major = $1;
+	    if (defined($2)) {
+		$sphinx_minor = substr($2,1);
+	    } else {
+		$sphinx_minor = 0;
+	    }
+	    if (defined($3)) {
+		$sphinx_patch = substr($3,1)
+	    } else {
+		$sphinx_patch = 0;
+	    }
+	} else {
+	    die "Sphinx version should either major.minor or major.minor.patch format\n";
+	}
     } else {
 	# Unknown argument
         usage();
@@ -477,29 +501,37 @@ sub findprog($)
 sub get_sphinx_version()
 {
 	my $ver;
-	my $major = 1;
 
 	my $cmd = "sphinx-build";
 	if (!findprog($cmd)) {
 		my $cmd = "sphinx-build3";
-		return $major if (!findprog($cmd));
+		if (!findprog($cmd)) {
+			$sphinx_major = 1;
+			$sphinx_minor = 2;
+			$sphinx_patch = 0;
+			printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n",
+			       $sphinx_major, $sphinx_minor, $sphinx_patch;
+			return;
+		}
 	}
 
 	open IN, "$cmd --version 2>&1 |";
 	while (<IN>) {
 		if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
-			$major=$1;
+			$sphinx_major = $1;
+			$sphinx_minor = $2;
+			$sphinx_patch = $3;
 			last;
 		}
 		# Sphinx 1.2.x uses a different format
 		if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
-			$major=$1;
+			$sphinx_major = $1;
+			$sphinx_minor = $2;
+			$sphinx_patch = $3;
 			last;
 		}
 	}
 	close IN;
-
-	return $major;
 }
 
 # get kernel version from env
@@ -2333,7 +2365,10 @@ sub process_file($) {
 }
 
 
-$sphinx_major = get_sphinx_version();
+if ($output_mode eq "rst") {
+	get_sphinx_version() if (!$sphinx_major);
+}
+
 $kernelversion = get_kernel_version();
 
 # generate a sequence of code that will splice in highlighting information
-- 
2.26.2

[PATCH v6 09/80] scripts: kernel-doc: fix line number handling

[Mauro Carvalho Chehab]

Address several issues related to pointing to the wrong line
number:

1) ensure that line numbers will always be initialized

   When section is the default (Description), the line number
   is not initializing, producing this:

	$ ./scripts/kernel-doc --enable-lineno ./drivers/media/v4l2-core/v4l2-mem2mem.c|less

	**Description**

	#define LINENO 0
	In case of streamoff or release called on any context,
	1] If the context is currently running, then abort job will be called
	2] If the context is queued, then the context will be removed from
	   the job_queue

  Which is not right. Ensure that the line number will always
  be there. After applied, the result now points to the right location:

	**Description**

	#define LINENO 410
	In case of streamoff or release called on any context,
	1] If the context is currently running, then abort job will be called
	2] If the context is queued, then the context will be removed from
	   the job_queue

2) The line numbers for function prototypes are always + 1,
   because it is taken at the line after handling the prototype.
   Change the logic to point to the next line after the /** */
   block;

3) The "DOC:" line number should point to the same line as this
   markup is found, and not to the next one.

Probably part of the issues were due to a but that was causing
the line number offset to be incremented by one, if --export
were used.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index ed32883c3221..9496abba9538 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1705,7 +1705,7 @@ sub dump_function($$) {
     my $file = shift;
     my $noret = 0;
 
-    print_lineno($.);
+    print_lineno($new_start_line);
 
     $prototype =~ s/^static +//;
     $prototype =~ s/^extern +//;
@@ -2033,7 +2033,7 @@ sub process_name($$) {
     if (/$doc_block/o) {
 	$state = STATE_DOCBLOCK;
 	$contents = "";
-	$new_start_line = $. + 1;
+	$new_start_line = $.;
 
 	if ( $1 eq "" ) {
 	    $section = $section_intro;
@@ -2116,6 +2116,7 @@ sub process_body($$) {
     if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
 	dump_section($file, $section, $contents);
 	$section = $section_default;
+	$new_start_line = $.;
 	$contents = "";
     }
 
@@ -2171,6 +2172,7 @@ sub process_body($$) {
 	$prototype = "";
 	$state = STATE_PROTO;
 	$brcount = 0;
+        $new_start_line = $. + 1;
     } elsif (/$doc_content/) {
 	if ($1 eq "") {
 	    if ($section eq $section_context) {
-- 
2.26.2

[PATCH v6 10/80] scripts: kernel-doc: try to use c:function if possible

[Mauro Carvalho Chehab]

There are a few namespace clashes by using c:macro everywhere:

basically, when using it, we can't have something like:

	.. c:struct:: pwm_capture

	.. c:macro:: pwm_capture

So, we need to use, instead:

	.. c:function:: int pwm_capture (struct pwm_device * pwm, struct pwm_capture * result, unsigned long timeout)

for the function declaration.

The kernel-doc change was proposed by Jakob Lykke Andersen here:

	https://github.com/jakobandersen/linux_docs/commit/6fd2076ec001cca7466857493cd678df4dfe4a65

Although I did a different implementation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9496abba9538..c8f6b11d5da1 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -917,6 +917,7 @@ sub output_function_rst(%) {
     my ($parameter, $section);
     my $oldprefix = $lineprefix;
     my $start = "";
+    my $is_macro = 0;
 
     if ($sphinx_major < 3) {
 	if ($args{'typedef'}) {
@@ -926,11 +927,17 @@ sub output_function_rst(%) {
 	    $lineprefix = "";
 	    output_highlight_rst($args{'purpose'});
 	    $start = "\n\n**Syntax**\n\n  ``";
+	    $is_macro = 1;
 	} else {
 	    print ".. c:function:: ";
 	}
     } else {
-	print ".. c:macro:: ". $args{'function'} . "\n\n";
+	if ($args{'typedef'} || $args{'functiontype'} eq "") {
+	    $is_macro = 1;
+	    print ".. c:macro:: ". $args{'function'} . "\n\n";
+	} else {
+	    print ".. c:function:: ";
+	}
 
 	if ($args{'typedef'}) {
 	    print_lineno($declaration_start_line);
@@ -939,7 +946,7 @@ sub output_function_rst(%) {
 	    output_highlight_rst($args{'purpose'});
 	    $start = "\n\n**Syntax**\n\n  ``";
 	} else {
-	    print "``";
+	    print "``" if ($is_macro);
 	}
     }
     if ($args{'functiontype'} ne "") {
@@ -964,14 +971,12 @@ sub output_function_rst(%) {
 	    print $type;
 	}
     }
-    if ($args{'typedef'}) {
-	print ");``\n\n";
+    if ($is_macro) {
+	print ")``\n\n";
     } else {
-	if ($sphinx_major < 3) {
-	    print ")\n\n";
-	} else {
-	    print ")``\n";
-	}
+	print ")\n\n";
+    }
+    if (!$args{'typedef'}) {
 	print_lineno($declaration_start_line);
 	$lineprefix = "   ";
 	output_highlight_rst($args{'purpose'});
-- 
2.26.2

[PATCH v6 11/80] docs: cdomain.py: add support for a new Sphinx 3.1+ tag

[Mauro Carvalho Chehab]

Since Sphinx 3.0, the C domain code was rewritten, but only
after version 3.1 it got support for setting namespaces on
C domains, with is something that it is required, in order to
document system calls, like ioctl() and others.

As part of changing the documentation subsystem to properly
build with Sphinx 3.1+, add support for such new tag:

	.. c:namespace::"

Such tag optionally replaces the optional "name" tag for functions,
setting a single namespace domain for all C references found
at the file.

With that, it should be possible to convert existing
documentation to be compatible with both Sphinx 1.x/2.x and
3.1+.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/cdomain.py | 55 ++++++++++++++++++++++++++++++++-
 1 file changed, 54 insertions(+), 1 deletion(-)

diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index cbac8e608dc4..35805c44a4fc 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -40,14 +40,56 @@ from sphinx import addnodes
 from sphinx.domains.c import c_funcptr_sig_re, c_sig_re
 from sphinx.domains.c import CObject as Base_CObject
 from sphinx.domains.c import CDomain as Base_CDomain
+from itertools import chain
+import re
 
-__version__  = '1.0'
+__version__  = '1.1'
 
 # Get Sphinx version
 major, minor, patch = sphinx.version_info[:3]
 
+# Namespace to be prepended to the full name
+namespace = None
+
+#
+# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags
+# - Store the namespace if ".. c:namespace::" tag is found
+
+RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
+
+def markup_namespace(match):
+    global namespace
+
+    namespace = match.group(1)
+
+    return ""
+
+def c_markups(app, docname, source):
+    result = ""
+    markup_func = {
+        RE_namespace: markup_namespace,
+    }
+
+    lines = iter(source[0].splitlines(True))
+    for n in lines:
+        match_iterators = [regex.finditer(n) for regex in markup_func]
+        matches = sorted(chain(*match_iterators), key=lambda m: m.start())
+        for m in matches:
+            n = n[:m.start()] + markup_func[m.re](m) + n[m.end():]
+
+        result = result + n
+
+    source[0] = result
+
+#
+# Now implements support for the cdomain namespacing logic
+#
+
 def setup(app):
 
+    # Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace::
+    app.connect('source-read', c_markups)
+
     if (major == 1 and minor < 8):
         app.override_domain(CDomain)
     else:
@@ -75,6 +117,8 @@ class CObject(Base_CObject):
         function-like macro, the name of the macro is returned. Otherwise
         ``False`` is returned.  """
 
+        global namespace
+
         if not self.objtype == 'function':
             return False
 
@@ -107,11 +151,16 @@ class CObject(Base_CObject):
             param += nodes.emphasis(argname, argname)
             paramlist += param
 
+        if namespace:
+            fullname = namespace + "." + fullname
+
         return fullname
 
     def handle_signature(self, sig, signode):
         """Transform a C signature into RST nodes."""
 
+        global namespace
+
         fullname = self.handle_func_like_macro(sig, signode)
         if not fullname:
             fullname = super(CObject, self).handle_signature(sig, signode)
@@ -122,6 +171,10 @@ class CObject(Base_CObject):
             else:
                 # FIXME: handle :name: value of other declaration types?
                 pass
+        else:
+            if namespace:
+                fullname = namespace + "." + fullname
+
         return fullname
 
     def add_target_and_index(self, name, sig, signode):
-- 
2.26.2

[PATCH v6 12/80] docs: cdomain.py: extend it to handle new Sphinx 3.x tags

[Mauro Carvalho Chehab]

While most of the C domain parsing is done via kernel-doc,
some RST files use C domain tags directly.

While several of them can be removed for Sphinx < 3.0, due
to automarkup.py, and several others that could be
converted into kernel-doc markups, changes like that are
time-consuming, and may not fit all cases.

As we already have the cdomain.py for handing backward
compatibility with Sphinx versions below 3.0, let's
make it more complete, in order to cover any usage of the
newer tags outside kernel-doc.

This way, it should be feasible to use the new tags inside
the Kernel tree, without losing backward compatibility.

This should allow fixing the remaining warnings with
the Kernel tags.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/cdomain.py | 40 ++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index 35805c44a4fc..014a5229e57a 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -54,7 +54,7 @@ namespace = None
 #
 # Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags
 # - Store the namespace if ".. c:namespace::" tag is found
-
+#
 RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
 
 def markup_namespace(match):
@@ -64,10 +64,48 @@ def markup_namespace(match):
 
     return ""
 
+#
+# Handle c:macro for function-style declaration
+#
+RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(\S+)\s+(\S.*)\s*$')
+def markup_macro(match):
+    return ".. c:function:: " + match.group(1) + ' ' + match.group(2)
+
+#
+# Handle newer c domain tags that are evaluated as .. c:type: for
+# backward-compatibility with Sphinx < 3.0
+#
+RE_ctype = re.compile(r'^\s*..\s*c:(struct|union|enum|enumerator|alias)::\s*(.*)$')
+
+def markup_ctype(match):
+    return ".. c:type:: " + match.group(2)
+
+#
+# Handle newer c domain tags that are evaluated as :c:type: for
+# backward-compatibility with Sphinx < 3.0
+#
+RE_ctype_refs = re.compile(r':c:(var|struct|union|enum|enumerator)::`([^\`]+)`')
+def markup_ctype_refs(match):
+    return ":c:type:`" + match.group(2) + '`'
+
+#
+# Simply convert :c:expr: and :c:texpr: into a literal block.
+#
+RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`')
+def markup_c_expr(match):
+    return '\ ``' + match.group(2) + '``\ '
+
+#
+# Parse Sphinx 3.x C markups, replacing them by backward-compatible ones
+#
 def c_markups(app, docname, source):
     result = ""
     markup_func = {
         RE_namespace: markup_namespace,
+        RE_expr: markup_c_expr,
+        RE_macro: markup_macro,
+        RE_ctype: markup_ctype,
+        RE_ctype_refs: markup_ctype_refs,
     }
 
     lines = iter(source[0].splitlines(True))
-- 
2.26.2

[PATCH v6 13/80] docs: automarkup.py: make it ready for Sphinx 3.1+

[Mauro Carvalho Chehab]

From: Nícolas F. R. A. Prado <nfraprado@protonmail.com>

While Sphinx 2 used a single c:type role for struct, union, enum and
typedef, Sphinx 3 uses a specific role for each one.
To keep backward compatibility, detect the Sphinx version and use the
correct roles for that version.

Also, Sphinx 3 is more strict with its C domain and generated warnings,
exposing issues in the parsing.
To fix the warnings, make the C regexes use ASCII, ensure the
expressions only match the beginning of words and skip trying to
cross-reference C reserved words.

Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/automarkup.py | 69 ++++++++++++++++++++++++++----
 1 file changed, 60 insertions(+), 9 deletions(-)

diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index a1b0f554cd82..fd1e927408ad 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -22,13 +22,34 @@ from itertools import chain
 # :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last
 # bit tries to restrict matches to things that won't create trouble.
 #
-RE_function = re.compile(r'(([\w_][\w\d_]+)\(\))')
-RE_type = re.compile(r'(struct|union|enum|typedef)\s+([\w_][\w\d_]+)')
+RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=re.ASCII)
+
+#
+# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef
+#
+RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)',
+                             flags=re.ASCII)
+
+#
+# Sphinx 3 uses a different C role for each one of struct, union, enum and
+# typedef
+#
+RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
+RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
+RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
+RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
+
 #
 # Detects a reference to a documentation page of the form Documentation/... with
 # an optional extension
 #
-RE_doc = re.compile(r'Documentation(/[\w\-_/]+)(\.\w+)*')
+RE_doc = re.compile(r'\bDocumentation(/[\w\-_/]+)(\.\w+)*')
+
+#
+# Reserved C words that we should skip when cross-referencing
+#
+Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ]
+
 
 #
 # Many places in the docs refer to common system calls.  It is
@@ -48,9 +69,22 @@ def markup_refs(docname, app, node):
     #
     # Associate each regex with the function that will markup its matches
     #
-    markup_func = {RE_type: markup_c_ref,
-                   RE_function: markup_c_ref,
-                   RE_doc: markup_doc_ref}
+    markup_func_sphinx2 = {RE_doc: markup_doc_ref,
+                           RE_function: markup_c_ref,
+                           RE_generic_type: markup_c_ref}
+
+    markup_func_sphinx3 = {RE_doc: markup_doc_ref,
+                           RE_function: markup_c_ref,
+                           RE_struct: markup_c_ref,
+                           RE_union: markup_c_ref,
+                           RE_enum: markup_c_ref,
+                           RE_typedef: markup_c_ref}
+
+    if sphinx.__version__[0] == '3':
+        markup_func = markup_func_sphinx3
+    else:
+        markup_func = markup_func_sphinx2
+
     match_iterators = [regex.finditer(t) for regex in markup_func]
     #
     # Sort all references by the starting position in text
@@ -79,8 +113,24 @@ def markup_refs(docname, app, node):
 # type_name) with an appropriate cross reference.
 #
 def markup_c_ref(docname, app, match):
-    class_str = {RE_function: 'c-func', RE_type: 'c-type'}
-    reftype_str = {RE_function: 'function', RE_type: 'type'}
+    class_str = {RE_function: 'c-func',
+                 # Sphinx 2 only
+                 RE_generic_type: 'c-type',
+                 # Sphinx 3+ only
+                 RE_struct: 'c-struct',
+                 RE_union: 'c-union',
+                 RE_enum: 'c-enum',
+                 RE_typedef: 'c-type',
+                 }
+    reftype_str = {RE_function: 'function',
+                   # Sphinx 2 only
+                   RE_generic_type: 'type',
+                   # Sphinx 3+ only
+                   RE_struct: 'struct',
+                   RE_union: 'union',
+                   RE_enum: 'enum',
+                   RE_typedef: 'type',
+                   }
 
     cdom = app.env.domains['c']
     #
@@ -89,7 +139,8 @@ def markup_c_ref(docname, app, match):
     target = match.group(2)
     target_text = nodes.Text(match.group(0))
     xref = None
-    if not (match.re == RE_function and target in Skipfuncs):
+    if not ((match.re == RE_function and target in Skipfuncs)
+            or (target in Skipnames)):
         lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]])
         lit_text += target_text
         pxref = addnodes.pending_xref('', refdomain = 'c',
-- 
2.26.2

[PATCH v6 14/80] docs: kerneldoc.py: append the name of the parsed doc file

[Mauro Carvalho Chehab]

Finding where an error like this was generated:
	../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'.

Can take some time, as there's no glue about what kernel-doc
tag generated it. It is a way better to display it as:

	.../Documentation/core-api/kernel-api:171: ../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'.
	Declaration is 'div_s64_rem'.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/kerneldoc.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index 1a1b12242a45..a3a5427130da 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -141,7 +141,8 @@ class KernelDocDirective(Directive):
                     lineoffset = int(match.group(1)) - 1
                     # we must eat our comments since the upset the markup
                 else:
-                    result.append(line, filename, lineoffset)
+                    doc = env.srcdir + "/" + env.docname + ":" + str(self.lineno)
+                    result.append(line, doc + ": " + filename, lineoffset)
                     lineoffset += 1
 
             node = nodes.section()
-- 
2.26.2

[PATCH v6 15/80] docs: kerneldoc.py: add support for kerneldoc -nosymbol

[Mauro Carvalho Chehab]

Currently, there's no way to exclude identifiers from
a kernel-doc markup. Add support for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/doc-guide/kernel-doc.rst | 8 ++++++++
 Documentation/sphinx/kerneldoc.py      | 7 +++++++
 2 files changed, 15 insertions(+)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 4fd86c21397b..52a87ab4c99f 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -490,6 +490,14 @@ identifiers: *[ function/type ...]*
     .. kernel-doc:: lib/idr.c
        :identifiers:
 
+no-identifiers: *[ function/type ...]*
+  Exclude documentation for each *function* and *type* in *source*.
+
+  Example::
+
+    .. kernel-doc:: lib/bitmap.c
+       :no-identifiers: bitmap_parselist
+
 functions: *[ function/type ...]*
   This is an alias of the 'identifiers' directive and deprecated.
 
diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index a3a5427130da..e9857ab904f1 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -62,6 +62,7 @@ class KernelDocDirective(Directive):
         'export': directives.unchanged,
         'internal': directives.unchanged,
         'identifiers': directives.unchanged,
+        'no-identifiers': directives.unchanged,
         'functions': directives.unchanged,
     }
     has_content = False
@@ -104,6 +105,12 @@ class KernelDocDirective(Directive):
             else:
                 cmd += ['-no-doc-sections']
 
+        if 'no-identifiers' in self.options:
+            no_identifiers = self.options.get('no-identifiers').split()
+            if no_identifiers:
+                for i in no_identifiers:
+                    cmd += ['-nosymbol', i]
+
         for pattern in export_file_patterns:
             for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
                 env.note_dependency(os.path.abspath(f))
-- 
2.26.2

[PATCH v6 16/80] media: docs: make CEC documents compatible with Sphinx 3.1+

[Mauro Carvalho Chehab]

Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../media/cec/cec-func-close.rst              | 10 +++-------
 .../media/cec/cec-func-ioctl.rst              | 11 ++++------
 .../userspace-api/media/cec/cec-func-open.rst | 10 +++-------
 .../userspace-api/media/cec/cec-func-poll.rst | 14 +++++--------
 .../media/cec/cec-ioc-adap-g-caps.rst         | 10 +++++-----
 .../media/cec/cec-ioc-adap-g-conn-info.rst    | 11 +++++-----
 .../media/cec/cec-ioc-adap-g-log-addrs.rst    | 20 ++++++++-----------
 .../media/cec/cec-ioc-adap-g-phys-addr.rst    | 15 +++++++-------
 .../media/cec/cec-ioc-dqevent.rst             | 15 +++++---------
 .../media/cec/cec-ioc-g-mode.rst              | 16 +++++++--------
 .../media/cec/cec-ioc-receive.rst             | 18 ++++++++---------
 11 files changed, 63 insertions(+), 87 deletions(-)

diff --git a/Documentation/userspace-api/media/cec/cec-func-close.rst b/Documentation/userspace-api/media/cec/cec-func-close.rst
index 33c563f414a8..409e70a5f80f 100644
--- a/Documentation/userspace-api/media/cec/cec-func-close.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-close.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _cec-func-close:
 
@@ -11,7 +12,6 @@ Name
 
 cec-close - Close a cec device
 
-
 Synopsis
 ========
 
@@ -19,16 +19,13 @@ Synopsis
 
     #include <unistd.h>
 
-
 .. c:function:: int close( int fd )
-    :name: cec-close
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
-
+    File descriptor returned by :c:func:`open()`.
 
 Description
 ===========
@@ -36,11 +33,10 @@ Description
 Closes the cec device. Resources associated with the file descriptor are
 freed. The device configuration remain unchanged.
 
-
 Return Value
 ============
 
-:c:func:`close() <cec-close>` returns 0 on success. On error, -1 is returned, and
+:c:func:`close()` returns 0 on success. On error, -1 is returned, and
 ``errno`` is set appropriately. Possible error codes are:
 
 ``EBADF``
diff --git a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst
index 3b88230fad80..7c93f86de6cc 100644
--- a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _cec-func-ioctl:
 
@@ -18,15 +19,13 @@ Synopsis
 
     #include <sys/ioctl.h>
 
-
-.. c:function:: int ioctl( int fd, int request, void *argp )
-   :name: cec-ioctl
+``int ioctl(int fd, int request, void *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``request``
     CEC ioctl request code as defined in the cec.h header file, for
@@ -35,11 +34,10 @@ Arguments
 ``argp``
     Pointer to a request-specific structure.
 
-
 Description
 ===========
 
-The :c:func:`ioctl() <cec-ioctl>` function manipulates cec device parameters. The
+The :c:func:`ioctl()` function manipulates cec device parameters. The
 argument ``fd`` must be an open file descriptor.
 
 The ioctl ``request`` code specifies the cec function to be called. It
@@ -51,7 +49,6 @@ their parameters are located in the cec.h header file. All cec ioctl
 requests, their respective function and parameters are specified in
 :ref:`cec-user-func`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/cec/cec-func-open.rst b/Documentation/userspace-api/media/cec/cec-func-open.rst
index 887bfd2a755e..d86563a34b9e 100644
--- a/Documentation/userspace-api/media/cec/cec-func-open.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-open.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _cec-func-open:
 
@@ -18,10 +19,7 @@ Synopsis
 
     #include <fcntl.h>
 
-
 .. c:function:: int open( const char *device_name, int flags )
-   :name: cec-open
-
 
 Arguments
 =========
@@ -42,11 +40,10 @@ Arguments
 
     Other flags have no effect.
 
-
 Description
 ===========
 
-To open a cec device applications call :c:func:`open() <cec-open>` with the
+To open a cec device applications call :c:func:`open()` with the
 desired device name. The function has no side effects; the device
 configuration remain unchanged.
 
@@ -54,11 +51,10 @@ When the device is opened in read-only mode, attempts to modify its
 configuration will result in an error, and ``errno`` will be set to
 EBADF.
 
-
 Return Value
 ============
 
-:c:func:`open() <cec-open>` returns the new file descriptor on success. On error,
+:c:func:`open()` returns the new file descriptor on success. On error,
 -1 is returned, and ``errno`` is set appropriately. Possible error codes
 include:
 
diff --git a/Documentation/userspace-api/media/cec/cec-func-poll.rst b/Documentation/userspace-api/media/cec/cec-func-poll.rst
index 2d87136e9a3f..980bbfc0bcce 100644
--- a/Documentation/userspace-api/media/cec/cec-func-poll.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-poll.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _cec-func-poll:
 
@@ -11,7 +12,6 @@ Name
 
 cec-poll - Wait for some event on a file descriptor
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <sys/poll.h>
 
-
 .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
-   :name: cec-poll
 
 Arguments
 =========
@@ -35,14 +33,13 @@ Arguments
 ``timeout``
    Timeout to wait for events
 
-
 Description
 ===========
 
-With the :c:func:`poll() <cec-poll>` function applications can wait for CEC
+With the :c:func:`poll()` function applications can wait for CEC
 events.
 
-On success :c:func:`poll() <cec-poll>` returns the number of file descriptors
+On success :c:func:`poll()` returns the number of file descriptors
 that have been selected (that is, file descriptors for which the
 ``revents`` field of the respective struct :c:type:`pollfd`
 is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
@@ -53,13 +50,12 @@ then the ``POLLPRI`` flag is set. When the function times out it returns
 a value of zero, on failure it returns -1 and the ``errno`` variable is
 set appropriately.
 
-For more details see the :c:func:`poll() <cec-poll>` manual page.
-
+For more details see the :c:func:`poll()` manual page.
 
 Return Value
 ============
 
-On success, :c:func:`poll() <cec-poll>` returns the number structures which have
+On success, :c:func:`poll()` returns the number structures which have
 non-zero ``revents`` fields, or zero if the call timed out. On error -1
 is returned, and the ``errno`` variable is set appropriately:
 
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
index 7f25365ce0fb..c7309a2fcbce 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_ADAP_G_CAPS:
 
@@ -14,18 +15,18 @@ CEC_ADAP_G_CAPS - Query device capabilities
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp )
-    :name: CEC_ADAP_G_CAPS
+.. c:macro:: CEC_ADAP_G_CAPS
+
+``int ioctl(int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
 
-
 Description
 ===========
 
@@ -62,7 +63,6 @@ returns the information to the application. The ioctl never fails.
       - CEC Framework API version, formatted with the ``KERNEL_VERSION()``
 	macro.
 
-
 .. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}|
 
 .. _cec-capabilities:
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst
index 6818ddf1495c..13116b0b5c17 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst
@@ -2,6 +2,8 @@
 ..
 .. Copyright 2019 Google LLC
 ..
+.. c:namespace:: CEC
+
 .. _CEC_ADAP_G_CONNECTOR_INFO:
 
 *******************************
@@ -16,18 +18,18 @@ CEC_ADAP_G_CONNECTOR_INFO - Query HDMI connector information
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp )
-    :name: CEC_ADAP_G_CONNECTOR_INFO
+.. c:macro:: CEC_ADAP_G_CONNECTOR_INFO
+
+``int ioctl(int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
 
-
 Description
 ===========
 
@@ -57,7 +59,6 @@ is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set.
     * - }
       -
 
-
 .. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}|
 
 .. _connector-type:
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
index 1ca893270ae9..c760c07b6b3f 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_ADAP_LOG_ADDRS:
 .. _CEC_ADAP_G_LOG_ADDRS:
@@ -13,21 +14,22 @@ Name
 
 CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp )
-   :name: CEC_ADAP_G_LOG_ADDRS
+.. c:macro:: CEC_ADAP_G_LOG_ADDRS
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp )
-   :name: CEC_ADAP_S_LOG_ADDRS
+``int ioctl(int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp)``
+
+.. c:macro:: CEC_ADAP_S_LOG_ADDRS
+
+``int ioctl(int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`cec_log_addrs`.
@@ -148,7 +150,6 @@ logical address types are already defined will return with error ``EBUSY``.
         give the CEC framework more information about the device type, even
         though the framework won't use it directly in the CEC message.
 
-
 .. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}|
 
 .. _cec-log-addrs-flags:
@@ -185,7 +186,6 @@ logical address types are already defined will return with error ``EBUSY``.
 
 	All other messages are ignored.
 
-
 .. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}|
 
 .. _cec-versions:
@@ -211,7 +211,6 @@ logical address types are already defined will return with error ``EBUSY``.
       - 6
       - CEC version according to the HDMI 2.0 standard.
 
-
 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 
 .. _cec-prim-dev-types:
@@ -257,7 +256,6 @@ logical address types are already defined will return with error ``EBUSY``.
       - 7
       - Use for a video processor device.
 
-
 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 
 .. _cec-log-addr-types:
@@ -306,7 +304,6 @@ logical address types are already defined will return with error ``EBUSY``.
 	Control).
 
 
-
 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 
 .. _cec-all-dev-types-flags:
@@ -348,7 +345,6 @@ logical address types are already defined will return with error ``EBUSY``.
       - This supports the CEC Switch or Video Processing type.
 
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst
index a10443be1b26..fb22f6894f26 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_ADAP_PHYS_ADDR:
 .. _CEC_ADAP_G_PHYS_ADDR:
@@ -13,21 +14,22 @@ Name
 
 CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp )
-    :name: CEC_ADAP_G_PHYS_ADDR
+.. c:macro:: CEC_ADAP_G_PHYS_ADDR
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp )
-    :name: CEC_ADAP_S_PHYS_ADDR
+``int ioctl(int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp)``
+
+.. c:macro:: CEC_ADAP_S_PHYS_ADDR
+
+``int ioctl(int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to the CEC address.
@@ -71,7 +73,6 @@ For example, the EDID for each HDMI input of the TV will have a
 different physical address of the form a.0.0.0 that the sources will
 read out and use as their physical address.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
index 3bc81fc5a73f..736fda5ad73d 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_DQEVENT:
 
@@ -11,22 +12,21 @@ Name
 
 CEC_DQEVENT - Dequeue a CEC event
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp )
-    :name: CEC_DQEVENT
+.. c:macro:: CEC_DQEVENT
+
+``int ioctl(int fd, CEC_DQEVENT, struct cec_event *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
 
-
 Description
 ===========
 
@@ -72,7 +72,6 @@ it is guaranteed that the state did change in between the two events.
         the HDMI driver is still configuring the device or because the HDMI
         device was unbound.
 
-
 .. c:type:: cec_event_lost_msgs
 
 .. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}|
@@ -94,7 +93,6 @@ it is guaranteed that the state did change in between the two events.
 	replied to within a second according to the CEC specification,
 	this is more than enough.
 
-
 .. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}|
 
 .. c:type:: cec_event
@@ -130,7 +128,6 @@ it is guaranteed that the state did change in between the two events.
     * - }
       -
 
-
 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 
 .. _cec-events:
@@ -204,7 +201,6 @@ it is guaranteed that the state did change in between the two events.
 	if the 5V is high, then an initial event will be generated for that
 	filehandle.
 
-
 .. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}|
 
 .. _cec-event-flags:
@@ -230,7 +226,6 @@ it is guaranteed that the state did change in between the two events.
         This is an indication that the application cannot keep up.
 
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst
index 2093e373c93c..d3387b1fa7c5 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_MODE:
 .. _CEC_G_MODE:
@@ -13,17 +14,19 @@ CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_G_MODE, __u32 *argp )
-   :name: CEC_G_MODE
+.. c:macro:: CEC_G_MODE
 
-.. c:function:: int ioctl( int fd, CEC_S_MODE, __u32 *argp )
-   :name: CEC_S_MODE
+``int ioctl(int fd, CEC_G_MODE, __u32 *argp)``
+
+.. c:macro:: CEC_S_MODE
+
+``int ioctl(int fd, CEC_S_MODE, __u32 *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to CEC mode.
@@ -101,7 +104,6 @@ Available initiator modes are:
 	then an attempt to become one will return the ``EBUSY`` error code
 	error.
 
-
 Available follower modes are:
 
 .. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}|
@@ -193,7 +195,6 @@ Available follower modes are:
 	the process has the ``CAP_NET_ADMIN`` capability. If that is not
 	set, then the ``EPERM`` error code is returned.
 
-
 Core message processing details:
 
 .. tabularcolumns:: |p{6.6cm}|p{10.9cm}|
@@ -272,7 +273,6 @@ Core message processing details:
 	and then just pass the message on to the follower(s).
 
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
index 9d629d46973c..b2fc051e99f4 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_TRANSMIT:
 .. _CEC_RECEIVE:
@@ -12,21 +13,22 @@ Name
 
 CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg \*argp )
-    :name: CEC_RECEIVE
+.. c:macro:: CEC_RECEIVE
 
-.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp )
-    :name: CEC_TRANSMIT
+``int ioctl(int fd, CEC_RECEIVE, struct cec_msg *argp)``
+
+.. c:macro:: CEC_TRANSMIT
+
+``int ioctl(int fd, CEC_TRANSMIT, struct cec_msg *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct cec_msg.
@@ -194,7 +196,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
 	supports this, otherwise it is always 0. This counter is only
 	valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
 
-
 .. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}|
 
 .. _cec-msg-flags:
@@ -228,7 +229,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
 	capability. If that is not set, then the ``EPERM`` error code is
 	returned.
 
-
 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 
 .. _cec-tx-status:
@@ -298,7 +298,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
       - The transmit timed out. This should not normally happen and this
 	indicates a driver problem.
 
-
 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 
 .. _cec-rx-status:
@@ -335,7 +334,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
 	reply was interrupted.
 
 
-
 Return Value
 ============
 
-- 
2.26.2

[PATCH v6 19/80] media: docs: make MC documents more compatible with Sphinx 3.1+

[Mauro Carvalho Chehab]

Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../media/mediactl/media-func-close.rst            | 10 +++-------
 .../media/mediactl/media-func-ioctl.rst            | 10 +++-------
 .../media/mediactl/media-func-open.rst             | 10 +++-------
 .../media/mediactl/media-ioc-device-info.rst       | 13 ++++---------
 .../media/mediactl/media-ioc-enum-entities.rst     | 11 ++++-------
 .../media/mediactl/media-ioc-enum-links.rst        | 13 ++++---------
 .../media/mediactl/media-ioc-g-topology.rst        | 14 ++++----------
 .../media/mediactl/media-ioc-request-alloc.rst     | 11 +++++------
 .../media/mediactl/media-ioc-setup-link.rst        | 10 ++++------
 .../media/mediactl/media-request-ioc-queue.rst     |  7 +++----
 .../media/mediactl/media-request-ioc-reinit.rst    |  8 ++++----
 .../userspace-api/media/mediactl/request-api.rst   |  5 +++--
 .../media/mediactl/request-func-close.rst          |  8 ++------
 .../media/mediactl/request-func-ioctl.rst          |  8 ++------
 .../media/mediactl/request-func-poll.rst           | 12 ++++--------
 15 files changed, 52 insertions(+), 98 deletions(-)

diff --git a/Documentation/userspace-api/media/mediactl/media-func-close.rst b/Documentation/userspace-api/media/mediactl/media-func-close.rst
index ec571b34ce69..8ac2443e76c1 100644
--- a/Documentation/userspace-api/media/mediactl/media-func-close.rst
+++ b/Documentation/userspace-api/media/mediactl/media-func-close.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media-func-close:
 
@@ -11,7 +12,6 @@ Name
 
 media-close - Close a media device
 
-
 Synopsis
 ========
 
@@ -19,16 +19,13 @@ Synopsis
 
     #include <unistd.h>
 
-
 .. c:function:: int close( int fd )
-    :name: mc-close
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <mc-open>`.
-
+    File descriptor returned by :c:func:`open()`.
 
 Description
 ===========
@@ -36,11 +33,10 @@ Description
 Closes the media device. Resources associated with the file descriptor
 are freed. The device configuration remain unchanged.
 
-
 Return Value
 ============
 
-:ref:`close() <media-func-close>` returns 0 on success. On error, -1 is returned, and
+:c:func:`close()` returns 0 on success. On error, -1 is returned, and
 ``errno`` is set appropriately. Possible error codes are:
 
 EBADF
diff --git a/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst
index 35ed549bec0e..9e9a838f4795 100644
--- a/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst
+++ b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media-func-ioctl:
 
@@ -11,7 +12,6 @@ Name
 
 media-ioctl - Control a media device
 
-
 Synopsis
 ========
 
@@ -19,15 +19,13 @@ Synopsis
 
     #include <sys/ioctl.h>
 
-
-.. c:function:: int ioctl( int fd, int request, void *argp )
-    :name: mc-ioctl
+``int ioctl(int fd, int request, void *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <mc-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``request``
     Media ioctl request code as defined in the media.h header file, for
@@ -36,7 +34,6 @@ Arguments
 ``argp``
     Pointer to a request-specific structure.
 
-
 Description
 ===========
 
@@ -52,7 +49,6 @@ their parameters are located in the media.h header file. All media ioctl
 requests, their respective function and parameters are specified in
 :ref:`media-user-func`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-func-open.rst b/Documentation/userspace-api/media/mediactl/media-func-open.rst
index 2c2595157ea3..24487cb0a308 100644
--- a/Documentation/userspace-api/media/mediactl/media-func-open.rst
+++ b/Documentation/userspace-api/media/mediactl/media-func-open.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media-func-open:
 
@@ -11,7 +12,6 @@ Name
 
 media-open - Open a media device
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <fcntl.h>
 
-
 .. c:function:: int open( const char *device_name, int flags )
-    :name: mc-open
 
 Arguments
 =========
@@ -33,11 +31,10 @@ Arguments
     Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``.
     Other flags have no effect.
 
-
 Description
 ===========
 
-To open a media device applications call :ref:`open() <media-func-open>` with the
+To open a media device applications call :c:func:`open()` with the
 desired device name. The function has no side effects; the device
 configuration remain unchanged.
 
@@ -45,11 +42,10 @@ When the device is opened in read-only mode, attempts to modify its
 configuration will result in an error, and ``errno`` will be set to
 EBADF.
 
-
 Return Value
 ============
 
-:ref:`open() <func-open>` returns the new file descriptor on success. On error,
+:c:func:`open()` returns the new file descriptor on success. On error,
 -1 is returned, and ``errno`` is set appropriately. Possible error codes
 are:
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst
index cde1ddfc0bfb..0c4c5d2cfcb2 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_device_info:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_DEVICE_INFO - Query device information
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp )
-    :name: MEDIA_IOC_DEVICE_INFO
+.. c:macro:: MEDIA_IOC_DEVICE_INFO
 
+``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`media_device_info`.
 
-
 Description
 ===========
 
@@ -38,7 +37,6 @@ a struct :c:type:`media_device_info`. The driver
 fills the structure and returns the information to the application. The
 ioctl never fails.
 
-
 .. c:type:: media_device_info
 
 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -48,7 +46,6 @@ ioctl never fails.
     :stub-columns: 0
     :widths:       1 1 2
 
-
     *  -  char
        -  ``driver``\ [16]
        -  Name of the driver implementing the media API as a NUL-terminated
@@ -94,7 +91,6 @@ ioctl never fails.
        -  Reserved for future extensions. Drivers and applications must set
 	  this array to zero.
 
-
 The ``serial`` and ``bus_info`` fields can be used to distinguish
 between multiple instances of otherwise identical hardware. The serial
 number takes precedence when provided and can be assumed to be unique.
@@ -102,7 +98,6 @@ If the serial number is an empty string, the ``bus_info`` field can be
 used instead. The ``bus_info`` field is guaranteed to be unique, but can
 vary across reboots or device unplug/replug.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst
index 93e35f198f47..92dd8ecd538c 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_enum_entities:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp )
-    :name: MEDIA_IOC_ENUM_ENTITIES
+.. c:macro:: MEDIA_IOC_ENUM_ENTITIES
 
+``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`media_entity_desc`.
 
-
 Description
 ===========
 
@@ -49,7 +48,6 @@ Entity IDs can be non-contiguous. Applications must *not* try to
 enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing
 id's until they get an error.
 
-
 .. c:type:: media_entity_desc
 
 .. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}|
@@ -136,7 +134,6 @@ id's until they get an error.
     *  - }
        -
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst
index f3e94c7b5dc3..3bc98a6a2ec5 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_enum_links:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp )
-    :name: MEDIA_IOC_ENUM_LINKS
+.. c:macro:: MEDIA_IOC_ENUM_LINKS
 
+``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`media_links_enum`.
 
-
 Description
 ===========
 
@@ -53,7 +52,6 @@ outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
 Only forward links that originate at one of the entity's source pads are
 returned during the enumeration process.
 
-
 .. c:type:: media_links_enum
 
 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -82,7 +80,6 @@ returned during the enumeration process.
        -  Reserved for future extensions. Drivers and applications must set
           the array to zero.
 
-
 .. c:type:: media_pad_desc
 
 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -110,7 +107,6 @@ returned during the enumeration process.
           the array to zero.
 
 
-
 .. c:type:: media_link_desc
 
 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -137,7 +133,6 @@ returned during the enumeration process.
        -  Reserved for future extensions. Drivers and applications must set
           the array to zero.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst
index 9b7d2296b7fd..8f8b3b586edd 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_g_topology:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp )
-    :name: MEDIA_IOC_G_TOPOLOGY
+.. c:macro:: MEDIA_IOC_G_TOPOLOGY
 
+``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`media_v2_topology`.
 
-
 Description
 ===========
 
@@ -120,7 +119,6 @@ desired arrays with the media graph elements.
 	  converted to a 64-bits integer. It can be zero. if zero, the ioctl
 	  won't store the links. It will just update ``num_links``
 
-
 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 
 .. c:type:: media_v2_entity
@@ -158,7 +156,6 @@ desired arrays with the media graph elements.
        -  Reserved for future extensions. Drivers and applications must set
 	  this array to zero.
 
-
 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 
 .. c:type:: media_v2_interface
@@ -192,7 +189,6 @@ desired arrays with the media graph elements.
        -  Used only for device node interfaces. See
 	  :c:type:`media_v2_intf_devnode` for details.
 
-
 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 
 .. c:type:: media_v2_intf_devnode
@@ -245,7 +241,6 @@ desired arrays with the media graph elements.
        -  Reserved for future extensions. Drivers and applications must set
 	  this array to zero.
 
-
 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 
 .. c:type:: media_v2_link
@@ -282,7 +277,6 @@ desired arrays with the media graph elements.
        -  Reserved for future extensions. Drivers and applications must set
 	  this array to zero.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst
index ea05ff0c5382..9195b4b8bf20 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_request_alloc:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_REQUEST_ALLOC - Allocate a request
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp )
-    :name: MEDIA_IOC_REQUEST_ALLOC
+.. c:macro:: MEDIA_IOC_REQUEST_ALLOC
 
+``int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to an integer.
 
-
 Description
 ===========
 
@@ -51,7 +50,7 @@ Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait
 for the request to complete.
 
 The request will remain allocated until all the file descriptors associated
-with it are closed by :ref:`close() <request-func-close>` and the driver no
+with it are closed by :c:func:`close()` and the driver no
 longer uses the request internally. See also
 :ref:`here <media-request-life-time>` for more information.
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst
index e2aa51015783..23208300cb61 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_setup_link:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_SETUP_LINK - Modify the properties of a link
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp )
-    :name: MEDIA_IOC_SETUP_LINK
+.. c:macro:: MEDIA_IOC_SETUP_LINK
 
+``int ioctl(int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`media_link_desc`.
 
-
 Description
 ===========
 
@@ -53,7 +52,6 @@ non-dynamic link will return an ``EBUSY`` error code.
 If the specified link can't be found the driver returns with an ``EINVAL``
 error code.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst
index ca1b33196242..04b33db2bb45 100644
--- a/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst
+++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_request_ioc_queue:
 
@@ -11,13 +12,12 @@ Name
 
 MEDIA_REQUEST_IOC_QUEUE - Queue a request
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE )
-    :name: MEDIA_REQUEST_IOC_QUEUE
+.. c:macro:: MEDIA_REQUEST_IOC_QUEUE
 
+``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)``
 
 Arguments
 =========
@@ -25,7 +25,6 @@ Arguments
 ``request_fd``
     File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
 
-
 Description
 ===========
 
diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst
index cfd503bdef70..57567b87b985 100644
--- a/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst
+++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_request_ioc_reinit:
 
@@ -11,13 +12,12 @@ Name
 
 MEDIA_REQUEST_IOC_REINIT - Re-initialize a request
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_REINIT )
-    :name: MEDIA_REQUEST_IOC_REINIT
+.. c:macro:: MEDIA_REQUEST_IOC_REINIT
 
+``int ioctl(int request_fd, MEDIA_REQUEST_IOC_REINIT)``
 
 Arguments
 =========
@@ -33,7 +33,7 @@ this request ioctl can be used to re-initialize a previously allocated
 request.
 
 Re-initializing a request will clear any existing data from the request.
-This avoids having to :ref:`close() <request-func-close>` a completed
+This avoids having to :c:func:`close()` a completed
 request and allocate a new request. Instead the completed request can just
 be re-initialized and it is ready to be used again.
 
diff --git a/Documentation/userspace-api/media/mediactl/request-api.rst b/Documentation/userspace-api/media/mediactl/request-api.rst
index c0fa4dbb2b28..6c4cbd9f08a5 100644
--- a/Documentation/userspace-api/media/mediactl/request-api.rst
+++ b/Documentation/userspace-api/media/mediactl/request-api.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media-request-api:
 
@@ -93,7 +94,7 @@ regardless of whether a request is in use or not.
    Setting the same control through a request and also directly can lead to
    undefined behavior!
 
-User-space can :ref:`poll() <request-func-poll>` a request file descriptor in
+User-space can :c:func:`poll()` a request file descriptor in
 order to wait until the request completes. A request is considered complete
 once all its associated buffers are available for dequeuing and all the
 associated controls have been updated with the values at the time of completion.
@@ -115,7 +116,7 @@ Recycling and Destruction
 -------------------------
 
 Finally, a completed request can either be discarded or be reused. Calling
-:ref:`close() <request-func-close>` on a request file descriptor will make
+:c:func:`close()` on a request file descriptor will make
 that file descriptor unusable and the request will be freed once it is no
 longer in use by the kernel. That is, if the request is queued and then the
 file descriptor is closed, then it won't be freed until the driver completed
diff --git a/Documentation/userspace-api/media/mediactl/request-func-close.rst b/Documentation/userspace-api/media/mediactl/request-func-close.rst
index 04e00bb9defd..f4b8eb385ad7 100644
--- a/Documentation/userspace-api/media/mediactl/request-func-close.rst
+++ b/Documentation/userspace-api/media/mediactl/request-func-close.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC.request
 
 .. _request-func-close:
 
@@ -11,7 +12,6 @@ Name
 
 request-close - Close a request file descriptor
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <unistd.h>
 
-
 .. c:function:: int close( int fd )
-    :name: req-close
 
 Arguments
 =========
@@ -29,7 +27,6 @@ Arguments
 ``fd``
     File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
 
-
 Description
 ===========
 
@@ -38,11 +35,10 @@ are freed once all file descriptors associated with the request are closed
 and the driver has completed the request.
 See :ref:`here <media-request-life-time>` for more information.
 
-
 Return Value
 ============
 
-:ref:`close() <request-func-close>` returns 0 on success. On error, -1 is
+:c:func:`close()` returns 0 on success. On error, -1 is
 returned, and ``errno`` is set appropriately. Possible error codes are:
 
 EBADF
diff --git a/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst
index 1e1c5edb860c..4fb3d2ef32d1 100644
--- a/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst
+++ b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _request-func-ioctl:
 
@@ -11,7 +12,6 @@ Name
 
 request-ioctl - Control a request file descriptor
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <sys/ioctl.h>
 
-
-.. c:function:: int ioctl( int fd, int cmd, void *argp )
-    :name: req-ioctl
+``int ioctl(int fd, int cmd, void *argp)``
 
 Arguments
 =========
@@ -36,7 +34,6 @@ Arguments
 ``argp``
     Pointer to a request-specific structure.
 
-
 Description
 ===========
 
@@ -52,7 +49,6 @@ their parameters are located in the media.h header file. All request ioctl
 commands, their respective function and parameters are specified in
 :ref:`media-user-func`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/request-func-poll.rst b/Documentation/userspace-api/media/mediactl/request-func-poll.rst
index 92947213d3d5..ce0043dbe7da 100644
--- a/Documentation/userspace-api/media/mediactl/request-func-poll.rst
+++ b/Documentation/userspace-api/media/mediactl/request-func-poll.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _request-func-poll:
 
@@ -11,7 +12,6 @@ Name
 
 request-poll - Wait for some event on a file descriptor
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <sys/poll.h>
 
-
 .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
-   :name: request-poll
 
 Arguments
 =========
@@ -35,14 +33,13 @@ Arguments
 ``timeout``
    Timeout to wait for events
 
-
 Description
 ===========
 
-With the :c:func:`poll() <request-func-poll>` function applications can wait
+With the :c:func:`poll()` function applications can wait
 for a request to complete.
 
-On success :c:func:`poll() <request-func-poll>` returns the number of file
+On success :c:func:`poll()` returns the number of file
 descriptors that have been selected (that is, file descriptors for which the
 ``revents`` field of the respective struct :c:type:`pollfd`
 is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents``
@@ -53,11 +50,10 @@ set appropriately.
 Attempting to poll for a request that is not yet queued will
 set the ``POLLERR`` flag in ``revents``.
 
-
 Return Value
 ============
 
-On success, :c:func:`poll() <request-func-poll>` returns the number of
+On success, :c:func:`poll()` returns the number of
 structures which have non-zero ``revents`` fields, or zero if the call
 timed out. On error -1 is returned, and the ``errno`` variable is set
 appropriately:
-- 
2.26.2

[PATCH v6 20/80] media: docs: make RC documents more compatible with Sphinx 3.1+

[Mauro Carvalho Chehab]

Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../userspace-api/media/rc/lirc-get-features.rst   |  9 ++++-----
 .../userspace-api/media/rc/lirc-get-rec-mode.rst   | 12 +++++++-----
 .../media/rc/lirc-get-rec-resolution.rst           |  8 ++++----
 .../userspace-api/media/rc/lirc-get-send-mode.rst  | 14 +++++++-------
 .../userspace-api/media/rc/lirc-get-timeout.rst    | 13 +++++++------
 Documentation/userspace-api/media/rc/lirc-read.rst | 10 +++-------
 .../media/rc/lirc-set-measure-carrier-mode.rst     |  8 ++++----
 .../media/rc/lirc-set-rec-carrier-range.rst        |  6 ++++--
 .../media/rc/lirc-set-rec-carrier.rst              |  8 ++++----
 .../media/rc/lirc-set-rec-timeout-reports.rst      |  8 ++++----
 .../media/rc/lirc-set-rec-timeout.rst              | 13 +++++++------
 .../media/rc/lirc-set-send-carrier.rst             |  8 ++++----
 .../media/rc/lirc-set-send-duty-cycle.rst          |  8 ++++----
 .../media/rc/lirc-set-transmitter-mask.rst         |  8 ++++----
 .../media/rc/lirc-set-wideband-receiver.rst        |  8 ++++----
 .../userspace-api/media/rc/lirc-write.rst          |  7 ++-----
 16 files changed, 73 insertions(+), 75 deletions(-)

diff --git a/Documentation/userspace-api/media/rc/lirc-get-features.rst b/Documentation/userspace-api/media/rc/lirc-get-features.rst
index 6846ae99848c..66a243dbd437 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-features.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-features.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_get_features:
 
@@ -14,8 +15,9 @@ LIRC_GET_FEATURES - Get the underlying hardware device's features
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_FEATURES, __u32 *features)
-    :name: LIRC_GET_FEATURES
+.. c:macro:: LIRC_GET_FEATURES
+
+``int ioctl(int fd, LIRC_GET_FEATURES, __u32 *features)``
 
 Arguments
 =========
@@ -26,11 +28,9 @@ Arguments
 ``features``
     Bitmask with the LIRC features.
 
-
 Description
 ===========
 
-
 Get the underlying hardware device's features. If a driver does not
 announce support of certain features, calling of the corresponding ioctls
 is undefined.
@@ -184,7 +184,6 @@ LIRC features
 
     Unused. Kept just to avoid breaking uAPI.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst
index e8f397a87331..188478ed1233 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_get_rec_mode:
 .. _lirc_set_rec_mode:
@@ -15,11 +16,13 @@ LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set current receive mode.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 *mode)
-	:name: LIRC_GET_REC_MODE
+.. c:macro:: LIRC_GET_REC_MODE
 
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 *mode)
-	:name: LIRC_SET_REC_MODE
+``int ioctl(int fd, LIRC_GET_REC_MODE, __u32 *mode)``
+
+.. c:macro:: LIRC_SET_REC_MODE
+
+``int ioctl(int fd, LIRC_SET_REC_MODE, __u32 *mode)``
 
 Arguments
 =========
@@ -47,7 +50,6 @@ Return Value
     :header-rows:  0
     :stub-columns: 0
 
-
     -  .. row 1
 
        -  ``ENODEV``
diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst
index 3f08aa7c24a9..e29445c5ce16 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_get_rec_resolution:
 
@@ -14,8 +15,9 @@ LIRC_GET_REC_RESOLUTION - Obtain the value of receive resolution, in microsecond
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds)
-    :name: LIRC_GET_REC_RESOLUTION
+.. c:macro:: LIRC_GET_REC_RESOLUTION
+
+``int ioctl(int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds)``
 
 Arguments
 =========
@@ -26,7 +28,6 @@ Arguments
 ``microseconds``
     Resolution, in microseconds.
 
-
 Description
 ===========
 
@@ -38,7 +39,6 @@ This ioctl returns the integer value with such resolution, with can be
 used by userspace applications like lircd to automatically adjust the
 tolerance value.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst
index f93b30c92193..77472fb5608a 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_get_send_mode:
 .. _lirc_set_send_mode:
@@ -15,11 +16,13 @@ LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set current transmit mode.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *mode )
-    :name: LIRC_GET_SEND_MODE
+.. c:macro:: LIRC_GET_SEND_MODE
 
-.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *mode )
-    :name: LIRC_SET_SEND_MODE
+``int ioctl(int fd, LIRC_GET_SEND_MODE, __u32 *mode)``
+
+.. c:macro:: LIRC_SET_SEND_MODE
+
+``int ioctl(int fd, LIRC_SET_SEND_MODE, __u32 *mode)``
 
 Arguments
 =========
@@ -30,7 +33,6 @@ Arguments
 ``mode``
     The mode used for transmitting.
 
-
 Description
 ===========
 
@@ -44,14 +46,12 @@ modes the driver supports.
 Return Value
 ============
 
-
 .. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
 
 .. flat-table::
     :header-rows:  0
     :stub-columns: 0
 
-
     -  .. row 1
 
        -  ``ENODEV``
diff --git a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst
index ec191a383d75..f5f3e06d6206 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_get_min_timeout:
 .. _lirc_get_max_timeout:
@@ -16,11 +17,13 @@ range for IR receive.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout)
-    :name: LIRC_GET_MIN_TIMEOUT
+.. c:macro:: LIRC_GET_MIN_TIMEOUT
 
-.. c:function:: int ioctl( int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout)
-    :name: LIRC_GET_MAX_TIMEOUT
+``int ioctl(int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout)``
+
+.. c:macro:: LIRC_GET_MAX_TIMEOUT
+
+``int ioctl(int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout)``
 
 Arguments
 =========
@@ -31,7 +34,6 @@ Arguments
 ``timeout``
     Timeout, in microseconds.
 
-
 Description
 ===========
 
@@ -47,7 +49,6 @@ that can be set.
    both ioctls will return the same value even though the timeout
    cannot be changed via :ref:`LIRC_SET_REC_TIMEOUT`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-read.rst b/Documentation/userspace-api/media/rc/lirc-read.rst
index b94a349bd99e..d589560214f4 100644
--- a/Documentation/userspace-api/media/rc/lirc-read.rst
+++ b/Documentation/userspace-api/media/rc/lirc-read.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc-read:
 
@@ -11,7 +12,6 @@ Name
 
 lirc-read - Read from a LIRC device
 
-
 Synopsis
 ========
 
@@ -19,10 +19,7 @@ Synopsis
 
     #include <unistd.h>
 
-
 .. c:function:: ssize_t read( int fd, void *buf, size_t count )
-    :name: lirc-read
-
 
 Arguments
 =========
@@ -39,9 +36,9 @@ Arguments
 Description
 ===========
 
-:ref:`read() <lirc-read>` attempts to read up to ``count`` bytes from file
+:c:func:`read()` attempts to read up to ``count`` bytes from file
 descriptor ``fd`` into the buffer starting at ``buf``.  If ``count`` is zero,
-:ref:`read() <lirc-read>` returns zero and has no other results. If ``count``
+:c:func:`read()` returns zero and has no other results. If ``count``
 is greater than ``SSIZE_MAX``, the result is unspecified.
 
 The exact format of the data depends on what :ref:`lirc_modes` a driver
@@ -59,7 +56,6 @@ by hardware decoders. The :c:type:`rc_proto` member is set to the
 used for transmission, and ``scancode`` to the decoded scancode,
 and the ``keycode`` set to the keycode or ``KEY_RESERVED``.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst
index 820d6bf28c1c..9bf9811a905a 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_measure_carrier_mode:
 
@@ -14,8 +15,9 @@ LIRC_SET_MEASURE_CARRIER_MODE - enable or disable measure mode
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable )
-    :name: LIRC_SET_MEASURE_CARRIER_MODE
+.. c:macro:: LIRC_SET_MEASURE_CARRIER_MODE
+
+``int ioctl(int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable)``
 
 Arguments
 =========
@@ -27,7 +29,6 @@ Arguments
     enable = 1 means enable measure mode, enable = 0 means disable measure
     mode.
 
-
 Description
 ===========
 
@@ -37,7 +38,6 @@ Enable or disable measure mode. If enabled, from the next key
 press on, the driver will send ``LIRC_MODE2_FREQUENCY`` packets. By
 default this should be turned off.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst
index e33e6a320b7a..530bc223930a 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_rec_carrier_range:
 
@@ -15,8 +16,9 @@ IR receive.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency )
-    :name: LIRC_SET_REC_CARRIER_RANGE
+.. c:macro:: LIRC_SET_REC_CARRIER_RANGE
+
+``int ioctl(int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency)``
 
 Arguments
 =========
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst
index a6784d5e59c8..28c928f1cc14 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_rec_carrier:
 
@@ -11,12 +12,12 @@ Name
 
 LIRC_SET_REC_CARRIER - Set carrier used to modulate IR receive.
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER, __u32 *frequency )
-    :name: LIRC_SET_REC_CARRIER
+.. c:macro:: LIRC_SET_REC_CARRIER
+
+``int ioctl(int fd, LIRC_SET_REC_CARRIER, __u32 *frequency)``
 
 Arguments
 =========
@@ -37,7 +38,6 @@ Set receive carrier used to modulate IR PWM pulses and spaces.
    If called together with :ref:`LIRC_SET_REC_CARRIER_RANGE`, this ioctl
    sets the upper bound frequency that will be recognized by the device.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst
index 55be65df7d5a..83e7155c5796 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_rec_timeout_reports:
 
@@ -14,8 +15,9 @@ LIRC_SET_REC_TIMEOUT_REPORTS - enable or disable timeout reports for IR receive
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable )
-    :name: LIRC_SET_REC_TIMEOUT_REPORTS
+.. c:macro:: LIRC_SET_REC_TIMEOUT_REPORTS
+
+``int ioctl(int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable)``
 
 Arguments
 =========
@@ -27,7 +29,6 @@ Arguments
     enable = 1 means enable timeout report, enable = 0 means disable timeout
     reports.
 
-
 Description
 ===========
 
@@ -40,7 +41,6 @@ should be turned off.
 
    This ioctl is only valid for :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst
index e91a0daecde6..8f3f9adf54ab 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_rec_timeout:
 .. _lirc_get_rec_timeout:
@@ -15,11 +16,13 @@ LIRC_GET_REC_TIMEOUT/LIRC_SET_REC_TIMEOUT - Get/set the integer value for IR ina
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout )
-    :name: LIRC_GET_REC_TIMEOUT
+.. c:macro:: LIRC_GET_REC_TIMEOUT
 
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout )
-    :name: LIRC_SET_REC_TIMEOUT
+``int ioctl(int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout)``
+
+.. c:macro:: LIRC_SET_REC_TIMEOUT
+
+``int ioctl(int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout)``
 
 Arguments
 =========
@@ -30,7 +33,6 @@ Arguments
 ``timeout``
     Timeout, in microseconds.
 
-
 Description
 ===========
 
@@ -45,7 +47,6 @@ given value should be set.
 
    The range of supported timeout is given by :ref:`LIRC_GET_MIN_TIMEOUT`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst
index e199aac7d8e0..e3810ba58746 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_send_carrier:
 
@@ -11,12 +12,12 @@ Name
 
 LIRC_SET_SEND_CARRIER - Set send carrier used to modulate IR TX.
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency )
-    :name: LIRC_SET_SEND_CARRIER
+.. c:macro:: LIRC_SET_SEND_CARRIER
+
+``int ioctl(int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency)``
 
 Arguments
 =========
@@ -32,7 +33,6 @@ Description
 
 Set send carrier used to modulate IR PWM pulses and spaces.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst
index a9074f4fb058..52a072529af9 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_send_duty_cycle:
 
@@ -15,8 +16,9 @@ IR transmit.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle)
-    :name: LIRC_SET_SEND_DUTY_CYCLE
+.. c:macro:: LIRC_SET_SEND_DUTY_CYCLE
+
+``int ioctl(int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle)``
 
 Arguments
 =========
@@ -28,7 +30,6 @@ Arguments
     Duty cicle, describing the pulse width in percent (from 1 to 99) of
     the total cycle. Values 0 and 100 are reserved.
 
-
 Description
 ===========
 
@@ -38,7 +39,6 @@ Currently, no special meaning is defined for 0 or 100, but this
 could be used to switch off carrier generation in the future, so
 these values should be reserved.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst
index 1f5527427281..68f4cc2e3ae3 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_transmitter_mask:
 
@@ -14,8 +15,9 @@ LIRC_SET_TRANSMITTER_MASK - Enables send codes on a given set of transmitters
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask )
-    :name: LIRC_SET_TRANSMITTER_MASK
+.. c:macro:: LIRC_SET_TRANSMITTER_MASK
+
+``int ioctl(int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask)``
 
 Arguments
 =========
@@ -26,7 +28,6 @@ Arguments
 ``mask``
     Mask with channels to enable tx. Channel 0 is the least significant bit.
 
-
 Description
 ===========
 
@@ -42,7 +43,6 @@ When an invalid bit mask is given, i.e. a bit is set, even though the device
 does not have so many transitters, then this ioctl returns the number of
 available transitters and does nothing otherwise.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst
index 2c43b620b3f3..be5321c4a91f 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_wideband_receiver:
 
@@ -14,8 +15,9 @@ LIRC_SET_WIDEBAND_RECEIVER - enable wide band receiver.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable )
-    :name: LIRC_SET_WIDEBAND_RECEIVER
+.. c:macro:: LIRC_SET_WIDEBAND_RECEIVER
+
+``int ioctl(int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable)``
 
 Arguments
 =========
@@ -27,7 +29,6 @@ Arguments
     enable = 1 means enable wideband receiver, enable = 0 means disable
     wideband receiver.
 
-
 Description
 ===========
 
@@ -47,7 +48,6 @@ reduced range of reception.
     carrier reports. Trying to disable wide band receiver while carrier
     reports are active will do nothing.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-write.rst b/Documentation/userspace-api/media/rc/lirc-write.rst
index 421de2cfa4ca..c1c3230d4fd6 100644
--- a/Documentation/userspace-api/media/rc/lirc-write.rst
+++ b/Documentation/userspace-api/media/rc/lirc-write.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc-write:
 
@@ -11,7 +12,6 @@ Name
 
 lirc-write - Write to a LIRC device
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <unistd.h>
 
-
 .. c:function:: ssize_t write( int fd, void *buf, size_t count )
-    :name: lirc-write
 
 Arguments
 =========
@@ -38,7 +36,7 @@ Arguments
 Description
 ===========
 
-:ref:`write() <lirc-write>` writes up to ``count`` bytes to the device
+:c:func:`write()` writes up to ``count`` bytes to the device
 referenced by the file descriptor ``fd`` from the buffer starting at
 ``buf``.
 
@@ -64,7 +62,6 @@ for the protocol or the scancode is not valid for the specified protocol,
 ``EINVAL`` is returned. The write function blocks until the scancode
 is transmitted by the hardware.
 
-
 Return Value
 ============
 
-- 
2.26.2

[PATCH v6 21/80] media: cec-core.rst: don't use c:type for structs

[Mauro Carvalho Chehab]

The new C domain code on Sphinx 3 doesn't allow anymore
to use c:type:: for structs.

Now that cdomain.py has backward support, let's use
c:struct:: instead.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/media/cec-core.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst
index 03016eeaf8f4..bc42982ac21e 100644
--- a/Documentation/driver-api/media/cec-core.rst
+++ b/Documentation/driver-api/media/cec-core.rst
@@ -98,7 +98,7 @@ Implementing the Low-Level CEC Adapter
 The following low-level adapter operations have to be implemented in
 your driver:
 
-.. c:type:: struct cec_adap_ops
+.. c:struct:: cec_adap_ops
 
 .. code-block:: none
 
-- 
2.26.2

[PATCH v6 22/80] docs: remove some replace macros like |struct foo|

[Mauro Carvalho Chehab]

There are three files with replace macros for structs,
mapping them into Sphinx 2.x C domain references.

Well, this is broken on Sphinx 3.x. Also, for Sphinx 2.x,
the automarkup macro should be able to take care of them.

So, let's just drop those.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/pm/cpufreq.rst | 11 ++--
 Documentation/driver-api/device_link.rst | 10 ++--
 Documentation/driver-api/pm/cpuidle.rst  | 65 +++++++++++-------------
 3 files changed, 38 insertions(+), 48 deletions(-)

diff --git a/Documentation/admin-guide/pm/cpufreq.rst b/Documentation/admin-guide/pm/cpufreq.rst
index 368e612145d2..6adb7988e0eb 100644
--- a/Documentation/admin-guide/pm/cpufreq.rst
+++ b/Documentation/admin-guide/pm/cpufreq.rst
@@ -1,7 +1,6 @@
 .. SPDX-License-Identifier: GPL-2.0
 .. include:: <isonum.txt>
 
-.. |struct cpufreq_policy| replace:: :c:type:`struct cpufreq_policy <cpufreq_policy>`
 .. |intel_pstate| replace:: :doc:`intel_pstate <intel_pstate>`
 
 =======================
@@ -92,16 +91,16 @@ control the P-state of multiple CPUs at the same time and writing to it affects
 all of those CPUs simultaneously.
 
 Sets of CPUs sharing hardware P-state control interfaces are represented by
-``CPUFreq`` as |struct cpufreq_policy| objects.  For consistency,
-|struct cpufreq_policy| is also used when there is only one CPU in the given
+``CPUFreq`` as struct cpufreq_policy objects.  For consistency,
+struct cpufreq_policy is also used when there is only one CPU in the given
 set.
 
-The ``CPUFreq`` core maintains a pointer to a |struct cpufreq_policy| object for
+The ``CPUFreq`` core maintains a pointer to a struct cpufreq_policy object for
 every CPU in the system, including CPUs that are currently offline.  If multiple
 CPUs share the same hardware P-state control interface, all of the pointers
-corresponding to them point to the same |struct cpufreq_policy| object.
+corresponding to them point to the same struct cpufreq_policy object.
 
-``CPUFreq`` uses |struct cpufreq_policy| as its basic data type and the design
+``CPUFreq`` uses struct cpufreq_policy as its basic data type and the design
 of its user space interface is based on the policy concept.
 
 
diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst
index bc2d89af88ce..76950d061632 100644
--- a/Documentation/driver-api/device_link.rst
+++ b/Documentation/driver-api/device_link.rst
@@ -1,7 +1,3 @@
-.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>`
-.. |struct generic_pm_domain| replace:: :c:type:`struct generic_pm_domain <generic_pm_domain>`
-
-
 .. _device_link:
 
 ============
@@ -166,7 +162,7 @@ Examples
   is the same as if the MMU was the parent of the master device.
 
   The fact that both devices share the same power domain would normally
-  suggest usage of a |struct dev_pm_domain| or |struct generic_pm_domain|,
+  suggest usage of a struct dev_pm_domain or struct generic_pm_domain,
   however these are not independent devices that happen to share a power
   switch, but rather the MMU device serves the busmaster device and is
   useless without it.  A device link creates a synthetic hierarchical
@@ -202,7 +198,7 @@ Examples
 Alternatives
 ============
 
-* A |struct dev_pm_domain| can be used to override the bus,
+* A struct dev_pm_domain can be used to override the bus,
   class or device type callbacks.  It is intended for devices sharing
   a single on/off switch, however it does not guarantee a specific
   suspend/resume ordering, this needs to be implemented separately.
@@ -211,7 +207,7 @@ Alternatives
   suspended.  Furthermore it cannot be used to enforce a specific shutdown
   ordering or a driver presence dependency.
 
-* A |struct generic_pm_domain| is a lot more heavyweight than a
+* A struct generic_pm_domain is a lot more heavyweight than a
   device link and does not allow for shutdown ordering or driver presence
   dependencies.  It also cannot be used on ACPI systems.
 
diff --git a/Documentation/driver-api/pm/cpuidle.rst b/Documentation/driver-api/pm/cpuidle.rst
index 3588bf078566..d477208604b8 100644
--- a/Documentation/driver-api/pm/cpuidle.rst
+++ b/Documentation/driver-api/pm/cpuidle.rst
@@ -1,11 +1,6 @@
 .. SPDX-License-Identifier: GPL-2.0
 .. include:: <isonum.txt>
 
-.. |struct cpuidle_governor| replace:: :c:type:`struct cpuidle_governor <cpuidle_governor>`
-.. |struct cpuidle_device| replace:: :c:type:`struct cpuidle_device <cpuidle_device>`
-.. |struct cpuidle_driver| replace:: :c:type:`struct cpuidle_driver <cpuidle_driver>`
-.. |struct cpuidle_state| replace:: :c:type:`struct cpuidle_state <cpuidle_state>`
-
 ========================
 CPU Idle Time Management
 ========================
@@ -54,7 +49,7 @@ platform that the Linux kernel can run on.  For this reason, data structures
 operated on by them cannot depend on any hardware architecture or platform
 design details as well.
 
-The governor itself is represented by a |struct cpuidle_governor| object
+The governor itself is represented by a struct cpuidle_governor object
 containing four callback pointers, :c:member:`enable`, :c:member:`disable`,
 :c:member:`select`, :c:member:`reflect`, a :c:member:`rating` field described
 below, and a name (string) used for identifying it.
@@ -83,11 +78,11 @@ callbacks:
 	  int (*enable) (struct cpuidle_driver *drv, struct cpuidle_device *dev);
 
 	The role of this callback is to prepare the governor for handling the
-	(logical) CPU represented by the |struct cpuidle_device| object	pointed
-	to by the ``dev`` argument.  The |struct cpuidle_driver| object pointed
+	(logical) CPU represented by the struct cpuidle_device object	pointed
+	to by the ``dev`` argument.  The struct cpuidle_driver object pointed
 	to by the ``drv`` argument represents the ``CPUIdle`` driver to be used
 	with that CPU (among other things, it should contain the list of
-	|struct cpuidle_state| objects representing idle states that the
+	struct cpuidle_state objects representing idle states that the
 	processor holding the given CPU can be asked to enter).
 
 	It may fail, in which case it is expected to return a negative error
@@ -102,7 +97,7 @@ callbacks:
 	  void (*disable) (struct cpuidle_driver *drv, struct cpuidle_device *dev);
 
 	Called to make the governor stop handling the (logical) CPU represented
-	by the |struct cpuidle_device| object pointed to by the ``dev``
+	by the struct cpuidle_device object pointed to by the ``dev``
 	argument.
 
 	It is expected to reverse any changes made by the ``->enable()``
@@ -116,12 +111,12 @@ callbacks:
 	                 bool *stop_tick);
 
 	Called to select an idle state for the processor holding the (logical)
-	CPU represented by the |struct cpuidle_device| object pointed to by the
+	CPU represented by the struct cpuidle_device object pointed to by the
 	``dev`` argument.
 
 	The list of idle states to take into consideration is represented by the
-	:c:member:`states` array of |struct cpuidle_state| objects held by the
-	|struct cpuidle_driver| object pointed to by the ``drv`` argument (which
+	:c:member:`states` array of struct cpuidle_state objects held by the
+	struct cpuidle_driver object pointed to by the ``drv`` argument (which
 	represents the ``CPUIdle`` driver to be used with the CPU at hand).  The
 	value returned by this callback is interpreted as an index into that
 	array (unless it is a negative error code).
@@ -136,7 +131,7 @@ callbacks:
 	asking the processor to enter the idle state).
 
 	This callback is mandatory (i.e. the :c:member:`select` callback pointer
-	in |struct cpuidle_governor| must not be ``NULL`` for the registration
+	in struct cpuidle_governor must not be ``NULL`` for the registration
 	of the governor to succeed).
 
 :c:member:`reflect`
@@ -167,21 +162,21 @@ CPU idle time management (``CPUIdle``) drivers provide an interface between the
 other parts of ``CPUIdle`` and the hardware.
 
 First of all, a ``CPUIdle`` driver has to populate the :c:member:`states` array
-of |struct cpuidle_state| objects included in the |struct cpuidle_driver| object
+of struct cpuidle_state objects included in the struct cpuidle_driver object
 representing it.  Going forward this array will represent the list of available
 idle states that the processor hardware can be asked to enter shared by all of
 the logical CPUs handled by the given driver.
 
 The entries in the :c:member:`states` array are expected to be sorted by the
-value of the :c:member:`target_residency` field in |struct cpuidle_state| in
+value of the :c:member:`target_residency` field in struct cpuidle_state in
 the ascending order (that is, index 0 should correspond to the idle state with
 the minimum value of :c:member:`target_residency`).  [Since the
 :c:member:`target_residency` value is expected to reflect the "depth" of the
-idle state represented by the |struct cpuidle_state| object holding it, this
+idle state represented by the struct cpuidle_state object holding it, this
 sorting order should be the same as the ascending sorting order by the idle
 state "depth".]
 
-Three fields in |struct cpuidle_state| are used by the existing ``CPUIdle``
+Three fields in struct cpuidle_state are used by the existing ``CPUIdle``
 governors for computations related to idle state selection:
 
 :c:member:`target_residency`
@@ -203,7 +198,7 @@ governors for computations related to idle state selection:
 	any idle state at all.  [There are other flags used by the ``CPUIdle``
 	core in special situations.]
 
-The :c:member:`enter` callback pointer in |struct cpuidle_state|, which must not
+The :c:member:`enter` callback pointer in struct cpuidle_state, which must not
 be ``NULL``, points to the routine to execute in order to ask the processor to
 enter this particular idle state:
 
@@ -212,14 +207,14 @@ enter this particular idle state:
   void (*enter) (struct cpuidle_device *dev, struct cpuidle_driver *drv,
                  int index);
 
-The first two arguments of it point to the |struct cpuidle_device| object
+The first two arguments of it point to the struct cpuidle_device object
 representing the logical CPU running this callback and the
-|struct cpuidle_driver| object representing the driver itself, respectively,
-and the last one is an index of the |struct cpuidle_state| entry in the driver's
+struct cpuidle_driver object representing the driver itself, respectively,
+and the last one is an index of the struct cpuidle_state entry in the driver's
 :c:member:`states` array representing the idle state to ask the processor to
 enter.
 
-The analogous ``->enter_s2idle()`` callback in |struct cpuidle_state| is used
+The analogous ``->enter_s2idle()`` callback in struct cpuidle_state is used
 only for implementing the suspend-to-idle system-wide power management feature.
 The difference between in and ``->enter()`` is that it must not re-enable
 interrupts at any point (even temporarily) or attempt to change the states of
@@ -227,48 +222,48 @@ clock event devices, which the ``->enter()`` callback may do sometimes.
 
 Once the :c:member:`states` array has been populated, the number of valid
 entries in it has to be stored in the :c:member:`state_count` field of the
-|struct cpuidle_driver| object representing the driver.  Moreover, if any
+struct cpuidle_driver object representing the driver.  Moreover, if any
 entries in the :c:member:`states` array represent "coupled" idle states (that
 is, idle states that can only be asked for if multiple related logical CPUs are
-idle), the :c:member:`safe_state_index` field in |struct cpuidle_driver| needs
+idle), the :c:member:`safe_state_index` field in struct cpuidle_driver needs
 to be the index of an idle state that is not "coupled" (that is, one that can be
 asked for if only one logical CPU is idle).
 
 In addition to that, if the given ``CPUIdle`` driver is only going to handle a
 subset of logical CPUs in the system, the :c:member:`cpumask` field in its
-|struct cpuidle_driver| object must point to the set (mask) of CPUs that will be
+struct cpuidle_driver object must point to the set (mask) of CPUs that will be
 handled by it.
 
 A ``CPUIdle`` driver can only be used after it has been registered.  If there
 are no "coupled" idle state entries in the driver's :c:member:`states` array,
-that can be accomplished by passing the driver's |struct cpuidle_driver| object
+that can be accomplished by passing the driver's struct cpuidle_driver object
 to :c:func:`cpuidle_register_driver()`.  Otherwise, :c:func:`cpuidle_register()`
 should be used for this purpose.
 
-However, it also is necessary to register |struct cpuidle_device| objects for
+However, it also is necessary to register struct cpuidle_device objects for
 all of the logical CPUs to be handled by the given ``CPUIdle`` driver with the
 help of :c:func:`cpuidle_register_device()` after the driver has been registered
 and :c:func:`cpuidle_register_driver()`, unlike :c:func:`cpuidle_register()`,
 does not do that automatically.  For this reason, the drivers that use
 :c:func:`cpuidle_register_driver()` to register themselves must also take care
-of registering the |struct cpuidle_device| objects as needed, so it is generally
+of registering the struct cpuidle_device objects as needed, so it is generally
 recommended to use :c:func:`cpuidle_register()` for ``CPUIdle`` driver
 registration in all cases.
 
-The registration of a |struct cpuidle_device| object causes the ``CPUIdle``
+The registration of a struct cpuidle_device object causes the ``CPUIdle``
 ``sysfs`` interface to be created and the governor's ``->enable()`` callback to
 be invoked for the logical CPU represented by it, so it must take place after
 registering the driver that will handle the CPU in question.
 
-``CPUIdle`` drivers and |struct cpuidle_device| objects can be unregistered
+``CPUIdle`` drivers and struct cpuidle_device objects can be unregistered
 when they are not necessary any more which allows some resources associated with
 them to be released.  Due to dependencies between them, all of the
-|struct cpuidle_device| objects representing CPUs handled by the given
+struct cpuidle_device objects representing CPUs handled by the given
 ``CPUIdle`` driver must be unregistered, with the help of
 :c:func:`cpuidle_unregister_device()`, before calling
 :c:func:`cpuidle_unregister_driver()` to unregister the driver.  Alternatively,
 :c:func:`cpuidle_unregister()` can be called to unregister a ``CPUIdle`` driver
-along with all of the |struct cpuidle_device| objects representing CPUs handled
+along with all of the struct cpuidle_device objects representing CPUs handled
 by it.
 
 ``CPUIdle`` drivers can respond to runtime system configuration changes that
@@ -277,8 +272,8 @@ happen, for example, when the system's power source is switched from AC to
 battery or the other way around).  Upon a notification of such a change,
 a ``CPUIdle`` driver is expected to call :c:func:`cpuidle_pause_and_lock()` to
 turn ``CPUIdle`` off temporarily and then :c:func:`cpuidle_disable_device()` for
-all of the |struct cpuidle_device| objects representing CPUs affected by that
+all of the struct cpuidle_device objects representing CPUs affected by that
 change.  Next, it can update its :c:member:`states` array in accordance with
 the new configuration of the system, call :c:func:`cpuidle_enable_device()` for
-all of the relevant |struct cpuidle_device| objects and invoke
+all of the relevant struct cpuidle_device objects and invoke
 :c:func:`cpuidle_resume_and_unlock()` to allow ``CPUIdle`` to be used again.
-- 
2.26.2

[PATCH v6 23/80] docs: get rid of :c:type explicit declarations for structs

[Mauro Carvalho Chehab]

The :c:type:`foo` only works properly with structs before
Sphinx 3.x.

On Sphinx 3.x, structs should now be declared using the
.. c:struct, and referenced via :c:struct tag.

As we now have the automarkup.py macro, that automatically
convert:
	struct foo

into cross-references, let's get rid of that, solving
several warnings when building docs with Sphinx 3.x.

Reviewed-by: André Almeida <andrealmeid@collabora.com> # blk-mq.rst
Reviewed-by: Takashi Iwai <tiwai@suse.de> # sound
Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/block/blk-mq.rst                |  8 +++----
 Documentation/block/inline-encryption.rst     |  8 +++----
 Documentation/driver-api/fpga/fpga-bridge.rst |  4 ++--
 Documentation/driver-api/fpga/fpga-mgr.rst    |  4 ++--
 Documentation/driver-api/fpga/fpga-region.rst |  2 +-
 Documentation/driver-api/iio/buffers.rst      |  2 +-
 Documentation/driver-api/iio/core.rst         |  6 ++---
 Documentation/driver-api/iio/hw-consumer.rst  |  2 +-
 .../driver-api/iio/triggered-buffers.rst      |  2 +-
 Documentation/driver-api/iio/triggers.rst     |  4 ++--
 .../driver-api/media/dtv-frontend.rst         |  4 ++--
 Documentation/driver-api/media/mc-core.rst    | 24 +++++++++----------
 .../driver-api/media/v4l2-controls.rst        |  2 +-
 Documentation/driver-api/media/v4l2-dev.rst   |  8 +++----
 .../driver-api/media/v4l2-device.rst          |  6 ++---
 Documentation/driver-api/media/v4l2-event.rst | 10 ++++----
 Documentation/driver-api/media/v4l2-fh.rst    | 16 ++++++-------
 .../driver-api/media/v4l2-subdev.rst          |  2 +-
 Documentation/driver-api/regulator.rst        |  4 ++--
 Documentation/driver-api/usb/URB.rst          |  2 +-
 Documentation/driver-api/usb/gadget.rst       | 10 ++++----
 Documentation/driver-api/usb/hotplug.rst      |  2 +-
 Documentation/filesystems/fscrypt.rst         | 14 +++++------
 Documentation/filesystems/fsverity.rst        |  2 +-
 Documentation/sound/designs/tracepoints.rst   | 22 ++++++++---------
 Documentation/sphinx/parse-headers.pl         |  2 +-
 Documentation/vm/ksm.rst                      |  2 +-
 Documentation/vm/memory-model.rst             |  6 ++---
 mm/ksm.c                                      |  2 +-
 mm/memblock.c                                 |  4 ++--
 30 files changed, 93 insertions(+), 93 deletions(-)

diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst
index 88c56afcb070..86a632af02b0 100644
--- a/Documentation/block/blk-mq.rst
+++ b/Documentation/block/blk-mq.rst
@@ -63,10 +63,10 @@ Software staging queues
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 The block IO subsystem adds requests  in the software staging queues
-(represented by struct :c:type:`blk_mq_ctx`) in case that they weren't sent
+(represented by struct blk_mq_ctx) in case that they weren't sent
 directly to the driver. A request is one or more BIOs. They arrived at the
-block layer through the data structure struct :c:type:`bio`. The block layer
-will then build a new structure from it, the struct :c:type:`request` that will
+block layer through the data structure struct bio. The block layer
+will then build a new structure from it, the struct request that will
 be used to communicate with the device driver. Each queue has its own lock and
 the number of queues is defined by a per-CPU or per-node basis.
 
@@ -102,7 +102,7 @@ hardware queue will be drained in sequence according to their mapping.
 Hardware dispatch queues
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-The hardware queue (represented by struct :c:type:`blk_mq_hw_ctx`) is a struct
+The hardware queue (represented by struct blk_mq_hw_ctx) is a struct
 used by device drivers to map the device submission queues (or device DMA ring
 buffer), and are the last step of the block layer submission code before the
 low level device driver taking ownership of the request. To run this queue, the
diff --git a/Documentation/block/inline-encryption.rst b/Documentation/block/inline-encryption.rst
index 354817b80887..e75151e467d3 100644
--- a/Documentation/block/inline-encryption.rst
+++ b/Documentation/block/inline-encryption.rst
@@ -52,7 +52,7 @@ Constraints and notes
 Design
 ======
 
-We add a :c:type:`struct bio_crypt_ctx` to :c:type:`struct bio` that can
+We add a struct bio_crypt_ctx to struct bio that can
 represent an encryption context, because we need to be able to pass this
 encryption context from the upper layers (like the fs layer) to the
 device driver to act upon.
@@ -85,7 +85,7 @@ blk-mq changes, other block layer changes and blk-crypto-fallback
 =================================================================
 
 We add a pointer to a ``bi_crypt_context`` and ``keyslot`` to
-:c:type:`struct request`. These will be referred to as the ``crypto fields``
+struct request. These will be referred to as the ``crypto fields``
 for the request. This ``keyslot`` is the keyslot into which the
 ``bi_crypt_context`` has been programmed in the KSM of the ``request_queue``
 that this request is being sent to.
@@ -118,7 +118,7 @@ of the algorithm being used adheres to spec and functions correctly).
 If a ``request queue``'s inline encryption hardware claimed to support the
 encryption context specified with a bio, then it will not be handled by the
 ``blk-crypto-fallback``. We will eventually reach a point in blk-mq when a
-:c:type:`struct request` needs to be allocated for that bio. At that point,
+struct request needs to be allocated for that bio. At that point,
 blk-mq tries to program the encryption context into the ``request_queue``'s
 keyslot_manager, and obtain a keyslot, which it stores in its newly added
 ``keyslot`` field. This keyslot is released when the request is completed.
@@ -188,7 +188,7 @@ keyslots supported by the hardware.
 The device driver also needs to tell the KSM how to actually manipulate the
 IE hardware in the device to do things like programming the crypto key into
 the IE hardware into a particular keyslot. All this is achieved through the
-:c:type:`struct blk_ksm_ll_ops` field in the KSM that the device driver
+struct blk_ksm_ll_ops field in the KSM that the device driver
 must fill up after initing the ``blk_keyslot_manager``.
 
 The KSM also handles runtime power management for the device when applicable
diff --git a/Documentation/driver-api/fpga/fpga-bridge.rst b/Documentation/driver-api/fpga/fpga-bridge.rst
index ccd677ba7d76..198aadafd3e7 100644
--- a/Documentation/driver-api/fpga/fpga-bridge.rst
+++ b/Documentation/driver-api/fpga/fpga-bridge.rst
@@ -4,8 +4,8 @@ FPGA Bridge
 API to implement a new FPGA bridge
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* struct :c:type:`fpga_bridge` — The FPGA Bridge structure
-* struct :c:type:`fpga_bridge_ops` — Low level Bridge driver ops
+* struct fpga_bridge — The FPGA Bridge structure
+* struct fpga_bridge_ops — Low level Bridge driver ops
 * devm_fpga_bridge_create() — Allocate and init a bridge struct
 * fpga_bridge_register() — Register a bridge
 * fpga_bridge_unregister() — Unregister a bridge
diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
index af5382af1379..22f7885b32c9 100644
--- a/Documentation/driver-api/fpga/fpga-mgr.rst
+++ b/Documentation/driver-api/fpga/fpga-mgr.rst
@@ -102,8 +102,8 @@ API for implementing a new FPGA Manager driver
 ----------------------------------------------
 
 * ``fpga_mgr_states`` —  Values for :c:member:`fpga_manager->state`.
-* struct :c:type:`fpga_manager` —  the FPGA manager struct
-* struct :c:type:`fpga_manager_ops` —  Low level FPGA manager driver ops
+* struct fpga_manager —  the FPGA manager struct
+* struct fpga_manager_ops —  Low level FPGA manager driver ops
 * devm_fpga_mgr_create() —  Allocate and init a manager struct
 * fpga_mgr_register() —  Register an FPGA manager
 * fpga_mgr_unregister() —  Unregister an FPGA manager
diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst
index 31118a8ba218..3e52be7e2968 100644
--- a/Documentation/driver-api/fpga/fpga-region.rst
+++ b/Documentation/driver-api/fpga/fpga-region.rst
@@ -45,7 +45,7 @@ An example of usage can be seen in the probe function of [#f2]_.
 API to add a new FPGA region
 ----------------------------
 
-* struct :c:type:`fpga_region` — The FPGA region struct
+* struct fpga_region — The FPGA region struct
 * devm_fpga_region_create() — Allocate and init a region struct
 * fpga_region_register() —  Register an FPGA region
 * fpga_region_unregister() —  Unregister an FPGA region
diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst
index dd64c9c5fb1e..3ddebddc02ca 100644
--- a/Documentation/driver-api/iio/buffers.rst
+++ b/Documentation/driver-api/iio/buffers.rst
@@ -2,7 +2,7 @@
 Buffers
 =======
 
-* struct :c:type:`iio_buffer` — general buffer structure
+* struct iio_buffer — general buffer structure
 * :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel
   is selected
 * :c:func:`iio_buffer_get` — Grab a reference to the buffer
diff --git a/Documentation/driver-api/iio/core.rst b/Documentation/driver-api/iio/core.rst
index 51b21e002396..715cf29482a1 100644
--- a/Documentation/driver-api/iio/core.rst
+++ b/Documentation/driver-api/iio/core.rst
@@ -10,7 +10,7 @@ applications manipulating sensors. The implementation can be found under
 Industrial I/O Devices
 ----------------------
 
-* struct :c:type:`iio_dev` - industrial I/O device
+* struct iio_dev - industrial I/O device
 * iio_device_alloc() - allocate an :c:type:`iio_dev` from a driver
 * iio_device_free() - free an :c:type:`iio_dev` from a driver
 * iio_device_register() - register a device with the IIO subsystem
@@ -66,7 +66,7 @@ Common attributes are:
 IIO device channels
 ===================
 
-struct :c:type:`iio_chan_spec` - specification of a single channel
+struct iio_chan_spec - specification of a single channel
 
 An IIO device channel is a representation of a data channel. An IIO device can
 have one or multiple channels. For example:
@@ -77,7 +77,7 @@ have one or multiple channels. For example:
 * an accelerometer can have up to 3 channels representing acceleration on X, Y
   and Z axes.
 
-An IIO channel is described by the struct :c:type:`iio_chan_spec`.
+An IIO channel is described by the struct iio_chan_spec.
 A thermometer driver for the temperature sensor in the example above would
 have to describe its channel as follows::
 
diff --git a/Documentation/driver-api/iio/hw-consumer.rst b/Documentation/driver-api/iio/hw-consumer.rst
index 819fb9edc005..76133a3796f2 100644
--- a/Documentation/driver-api/iio/hw-consumer.rst
+++ b/Documentation/driver-api/iio/hw-consumer.rst
@@ -8,7 +8,7 @@ software buffer for data. The implementation can be found under
 :file:`drivers/iio/buffer/hw-consumer.c`
 
 
-* struct :c:type:`iio_hw_consumer` — Hardware consumer structure
+* struct iio_hw_consumer — Hardware consumer structure
 * :c:func:`iio_hw_consumer_alloc` — Allocate IIO hardware consumer
 * :c:func:`iio_hw_consumer_free` — Free IIO hardware consumer
 * :c:func:`iio_hw_consumer_enable` — Enable IIO hardware consumer
diff --git a/Documentation/driver-api/iio/triggered-buffers.rst b/Documentation/driver-api/iio/triggered-buffers.rst
index 0db12660cc90..417555dbbdf4 100644
--- a/Documentation/driver-api/iio/triggered-buffers.rst
+++ b/Documentation/driver-api/iio/triggered-buffers.rst
@@ -10,7 +10,7 @@ IIO triggered buffer setup
 * :c:func:`iio_triggered_buffer_setup` — Setup triggered buffer and pollfunc
 * :c:func:`iio_triggered_buffer_cleanup` — Free resources allocated by
   :c:func:`iio_triggered_buffer_setup`
-* struct :c:type:`iio_buffer_setup_ops` — buffer setup related callbacks
+* struct iio_buffer_setup_ops — buffer setup related callbacks
 
 A typical triggered buffer setup looks like this::
 
diff --git a/Documentation/driver-api/iio/triggers.rst b/Documentation/driver-api/iio/triggers.rst
index dfd7ba3eabde..288625e40672 100644
--- a/Documentation/driver-api/iio/triggers.rst
+++ b/Documentation/driver-api/iio/triggers.rst
@@ -2,7 +2,7 @@
 Triggers
 ========
 
-* struct :c:type:`iio_trigger` — industrial I/O trigger device
+* struct iio_trigger — industrial I/O trigger device
 * :c:func:`devm_iio_trigger_alloc` — Resource-managed iio_trigger_alloc
 * :c:func:`devm_iio_trigger_register` — Resource-managed iio_trigger_register
   iio_trigger_unregister
@@ -63,7 +63,7 @@ Let's see a simple example of how to setup a trigger to be used by a driver::
 IIO trigger ops
 ===============
 
-* struct :c:type:`iio_trigger_ops` — operations structure for an iio_trigger.
+* struct iio_trigger_ops — operations structure for an iio_trigger.
 
 Notice that a trigger has a set of operations attached:
 
diff --git a/Documentation/driver-api/media/dtv-frontend.rst b/Documentation/driver-api/media/dtv-frontend.rst
index b362109bb131..91f77fe58e83 100644
--- a/Documentation/driver-api/media/dtv-frontend.rst
+++ b/Documentation/driver-api/media/dtv-frontend.rst
@@ -125,7 +125,7 @@ responsible for tuning the device. It supports multiple algorithms to
 detect a channel, as defined at enum :c:func:`dvbfe_algo`.
 
 The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver
-doesn't fill its field at struct :c:type:`dvb_frontend_ops`, it will default to
+doesn't fill its field at struct dvb_frontend_ops, it will default to
 ``DVBFE_ALGO_SW``, meaning that the dvb-core will do a zigzag when tuning,
 e. g. it will try first to use the specified center frequency ``f``,
 then, it will do ``f`` + |delta|, ``f`` - |delta|, ``f`` + 2 x |delta|,
@@ -140,7 +140,7 @@ define a ``.get_frontend_algo`` function that would return ``DVBFE_ALGO_HW``.
    a third type (``DVBFE_ALGO_CUSTOM``), in order to allow the driver to
    define its own hardware-assisted algorithm. Very few hardware need to
    use it nowadays. Using ``DVBFE_ALGO_CUSTOM`` require to provide other
-   function callbacks at struct :c:type:`dvb_frontend_ops`.
+   function callbacks at struct dvb_frontend_ops.
 
 Attaching frontend driver to the bridge driver
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Documentation/driver-api/media/mc-core.rst b/Documentation/driver-api/media/mc-core.rst
index 05bba0b61748..57b5bbba944e 100644
--- a/Documentation/driver-api/media/mc-core.rst
+++ b/Documentation/driver-api/media/mc-core.rst
@@ -36,7 +36,7 @@ pad to a sink pad.
 Media device
 ^^^^^^^^^^^^
 
-A media device is represented by a struct :c:type:`media_device`
+A media device is represented by a struct media_device
 instance, defined in ``include/media/media-device.h``.
 Allocation of the structure is handled by the media device driver, usually by
 embedding the :c:type:`media_device` instance in a larger driver-specific
@@ -49,7 +49,7 @@ and unregistered by calling :c:func:`media_device_unregister()`.
 Entities
 ^^^^^^^^
 
-Entities are represented by a struct :c:type:`media_entity`
+Entities are represented by a struct media_entity
 instance, defined in ``include/media/media-entity.h``. The structure is usually
 embedded into a higher-level structure, such as
 :c:type:`v4l2_subdev` or :c:type:`video_device`
@@ -67,10 +67,10 @@ Interfaces
 ^^^^^^^^^^
 
 Interfaces are represented by a
-struct :c:type:`media_interface` instance, defined in
+struct media_interface instance, defined in
 ``include/media/media-entity.h``. Currently, only one type of interface is
 defined: a device node. Such interfaces are represented by a
-struct :c:type:`media_intf_devnode`.
+struct media_intf_devnode.
 
 Drivers initialize and create device node interfaces by calling
 :c:func:`media_devnode_create()`
@@ -79,7 +79,7 @@ and remove them by calling:
 
 Pads
 ^^^^
-Pads are represented by a struct :c:type:`media_pad` instance,
+Pads are represented by a struct media_pad instance,
 defined in ``include/media/media-entity.h``. Each entity stores its pads in
 a pads array managed by the entity driver. Drivers usually embed the array in
 a driver-specific structure.
@@ -87,8 +87,8 @@ a driver-specific structure.
 Pads are identified by their entity and their 0-based index in the pads
 array.
 
-Both information are stored in the struct :c:type:`media_pad`,
-making the struct :c:type:`media_pad` pointer the canonical way
+Both information are stored in the struct media_pad,
+making the struct media_pad pointer the canonical way
 to store and pass link references.
 
 Pads have flags that describe the pad capabilities and state.
@@ -104,7 +104,7 @@ Pads have flags that describe the pad capabilities and state.
 Links
 ^^^^^
 
-Links are represented by a struct :c:type:`media_link` instance,
+Links are represented by a struct media_link instance,
 defined in ``include/media/media-entity.h``. There are two types of links:
 
 **1. pad to pad links**:
@@ -187,7 +187,7 @@ Use count and power handling
 
 Due to the wide differences between drivers regarding power management
 needs, the media controller does not implement power management. However,
-the struct :c:type:`media_entity` includes a ``use_count``
+the struct media_entity includes a ``use_count``
 field that media drivers
 can use to track the number of users of every entity for power management
 needs.
@@ -213,11 +213,11 @@ prevent link states from being modified during streaming by calling
 The function will mark all entities connected to the given entity through
 enabled links, either directly or indirectly, as streaming.
 
-The struct :c:type:`media_pipeline` instance pointed to by
+The struct media_pipeline instance pointed to by
 the pipe argument will be stored in every entity in the pipeline.
-Drivers should embed the struct :c:type:`media_pipeline`
+Drivers should embed the struct media_pipeline
 in higher-level pipeline structures and can then access the
-pipeline through the struct :c:type:`media_entity`
+pipeline through the struct media_entity
 pipe field.
 
 Calls to :c:func:`media_pipeline_start()` can be nested.
diff --git a/Documentation/driver-api/media/v4l2-controls.rst b/Documentation/driver-api/media/v4l2-controls.rst
index 5129019afb49..77f42ea3bac7 100644
--- a/Documentation/driver-api/media/v4l2-controls.rst
+++ b/Documentation/driver-api/media/v4l2-controls.rst
@@ -27,7 +27,7 @@ V4L2 specification with respect to controls in a central place. And to make
 life as easy as possible for the driver developer.
 
 Note that the control framework relies on the presence of a struct
-:c:type:`v4l2_device` for V4L2 drivers and struct :c:type:`v4l2_subdev` for
+:c:type:`v4l2_device` for V4L2 drivers and struct v4l2_subdev for
 sub-device drivers.
 
 
diff --git a/Documentation/driver-api/media/v4l2-dev.rst b/Documentation/driver-api/media/v4l2-dev.rst
index 63c064837c00..666330af31ed 100644
--- a/Documentation/driver-api/media/v4l2-dev.rst
+++ b/Documentation/driver-api/media/v4l2-dev.rst
@@ -67,7 +67,7 @@ You should also set these fields of :c:type:`video_device`:
   file operation is called this lock will be taken by the core and released
   afterwards. See the next section for more details.
 
-- :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue`
+- :c:type:`video_device`->queue: a pointer to the struct vb2_queue
   associated with this device node.
   If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock
   is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``,
@@ -81,7 +81,7 @@ You should also set these fields of :c:type:`video_device`:
 
 - :c:type:`video_device`->prio: keeps track of the priorities. Used to
   implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``.
-  If left to ``NULL``, then it will use the struct :c:type:`v4l2_prio_state`
+  If left to ``NULL``, then it will use the struct v4l2_prio_state
   in :c:type:`v4l2_device`. If you want to have a separate priority state per
   (group of) device node(s),   then you can point it to your own struct
   :c:type:`v4l2_prio_state`.
@@ -95,7 +95,7 @@ You should also set these fields of :c:type:`video_device`:
   but   it is used by both a raw video PCI device (cx8800) and a MPEG PCI device
   (cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI
   devices at the same time it is setup without a parent device. But when the
-  struct :c:type:`video_device` is initialized you **do** know which parent
+  struct video_device is initialized you **do** know which parent
   PCI device to use and so you set ``dev_device`` to the correct PCI device.
 
 If you use :c:type:`v4l2_ioctl_ops`, then you should set
@@ -138,7 +138,7 @@ ioctls and locking
 ------------------
 
 The V4L core provides optional locking services. The main service is the
-lock field in struct :c:type:`video_device`, which is a pointer to a mutex.
+lock field in struct video_device, which is a pointer to a mutex.
 If you set this pointer, then that will be used by unlocked_ioctl to
 serialize all ioctls.
 
diff --git a/Documentation/driver-api/media/v4l2-device.rst b/Documentation/driver-api/media/v4l2-device.rst
index 5e25bf182c18..7bd9c45f551b 100644
--- a/Documentation/driver-api/media/v4l2-device.rst
+++ b/Documentation/driver-api/media/v4l2-device.rst
@@ -3,7 +3,7 @@
 V4L2 device instance
 --------------------
 
-Each device instance is represented by a struct :c:type:`v4l2_device`.
+Each device instance is represented by a struct v4l2_device.
 Very simple devices can just allocate this struct, but most of the time you
 would embed this struct inside a larger struct.
 
@@ -18,9 +18,9 @@ dev->driver_data field is ``NULL``, it will be linked to
 
 Drivers that want integration with the media device framework need to set
 dev->driver_data manually to point to the driver-specific device structure
-that embed the struct :c:type:`v4l2_device` instance. This is achieved by a
+that embed the struct v4l2_device instance. This is achieved by a
 ``dev_set_drvdata()`` call before registering the V4L2 device instance.
-They must also set the struct :c:type:`v4l2_device` mdev field to point to a
+They must also set the struct v4l2_device mdev field to point to a
 properly initialized and registered :c:type:`media_device` instance.
 
 If :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a
diff --git a/Documentation/driver-api/media/v4l2-event.rst b/Documentation/driver-api/media/v4l2-event.rst
index a4b7ae2b94d8..5b8254eba7da 100644
--- a/Documentation/driver-api/media/v4l2-event.rst
+++ b/Documentation/driver-api/media/v4l2-event.rst
@@ -44,18 +44,18 @@ such objects.
 
 So to summarize:
 
-- struct :c:type:`v4l2_fh` has two lists: one of the ``subscribed`` events,
+- struct v4l2_fh has two lists: one of the ``subscribed`` events,
   and one of the ``available`` events.
 
-- struct :c:type:`v4l2_subscribed_event` has a ringbuffer of raised
+- struct v4l2_subscribed_event has a ringbuffer of raised
   (pending) events of that particular type.
 
-- If struct :c:type:`v4l2_subscribed_event` is associated with a specific
+- If struct v4l2_subscribed_event is associated with a specific
   object, then that object will have an internal list of
-  struct :c:type:`v4l2_subscribed_event` so it knows who subscribed an
+  struct v4l2_subscribed_event so it knows who subscribed an
   event to that object.
 
-Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has
+Furthermore, the internal struct v4l2_subscribed_event has
 ``merge()`` and ``replace()`` callbacks which drivers can set. These
 callbacks are called when a new event is raised and there is no more room.
 
diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst
index 4c62b19af744..3eeaa8da0c9e 100644
--- a/Documentation/driver-api/media/v4l2-fh.rst
+++ b/Documentation/driver-api/media/v4l2-fh.rst
@@ -3,11 +3,11 @@
 V4L2 File handlers
 ------------------
 
-struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific
+struct v4l2_fh provides a way to easily keep file handle specific
 data that is used by the V4L2 framework.
 
 .. attention::
-	New drivers must use struct :c:type:`v4l2_fh`
+	New drivers must use struct v4l2_fh
 	since it is also used to implement priority handling
 	(:ref:`VIDIOC_G_PRIORITY`).
 
@@ -16,11 +16,11 @@ whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer
 by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags.
 This bit is set whenever :c:func:`v4l2_fh_init` is called.
 
-struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle
+struct v4l2_fh is allocated as a part of the driver's own file handle
 structure and ``file->private_data`` is set to it in the driver's ``open()``
 function by the driver.
 
-In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger
+In many cases the struct v4l2_fh will be embedded in a larger
 structure. In that case you should call:
 
 #) :c:func:`v4l2_fh_init` and :c:func:`v4l2_fh_add` in ``open()``
@@ -102,18 +102,18 @@ Below is a short description of the :c:type:`v4l2_fh` functions used:
   memory can be freed.
 
 
-If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions:
+If struct v4l2_fh is not embedded, then you can use these helper functions:
 
 :c:func:`v4l2_fh_open <v4l2_fh_open>`
 (struct file \*filp)
 
-- This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to
-  the struct :c:type:`video_device` associated with the file struct.
+- This allocates a struct v4l2_fh, initializes it and adds it to
+  the struct video_device associated with the file struct.
 
 :c:func:`v4l2_fh_release <v4l2_fh_release>`
 (struct file \*filp)
 
-- This deletes it from the struct :c:type:`video_device` associated with the
+- This deletes it from the struct video_device associated with the
   file struct, uninitialised the :c:type:`v4l2_fh` and frees it.
 
 These two functions can be plugged into the v4l2_file_operation's ``open()``
diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst
index 6248ea99e979..bb5b1a7cdfd9 100644
--- a/Documentation/driver-api/media/v4l2-subdev.rst
+++ b/Documentation/driver-api/media/v4l2-subdev.rst
@@ -110,7 +110,7 @@ pads:
 	err = media_entity_pads_init(&sd->entity, npads, pads);
 
 The pads array must have been previously initialized. There is no need to
-manually set the struct :c:type:`media_entity` function and name fields, but the
+manually set the struct media_entity function and name fields, but the
 revision field must be initialized if needed.
 
 A reference to the entity will be automatically acquired/released when the
diff --git a/Documentation/driver-api/regulator.rst b/Documentation/driver-api/regulator.rst
index 520da0a5251d..b43c78eb24d8 100644
--- a/Documentation/driver-api/regulator.rst
+++ b/Documentation/driver-api/regulator.rst
@@ -116,7 +116,7 @@ core, providing operations structures to the core. A notifier interface
 allows error conditions to be reported to the core.
 
 Registration should be triggered by explicit setup done by the platform,
-supplying a struct :c:type:`regulator_init_data` for the regulator
+supplying a struct regulator_init_data for the regulator
 containing constraint and supply information.
 
 Machine interface
@@ -144,7 +144,7 @@ a given system, for example supporting higher supply voltages than the
 consumers are rated for.
 
 This is done at driver registration time` by providing a
-struct :c:type:`regulation_constraints`.
+struct regulation_constraints.
 
 The constraints may also specify an initial configuration for the
 regulator in the constraints, which is particularly useful for use with
diff --git a/Documentation/driver-api/usb/URB.rst b/Documentation/driver-api/usb/URB.rst
index 1e4abc896a0d..a182c0f5e38a 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -47,7 +47,7 @@ called USB Request Block, or URB for short.
 The URB structure
 =================
 
-Some of the fields in struct :c:type:`urb` are::
+Some of the fields in struct urb are::
 
   struct urb
   {
diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst
index 3e8a3809c0b8..09396edd6131 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -176,9 +176,9 @@ Kernel Mode Gadget API
 
 Gadget drivers declare themselves through a struct
 :c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
-for a struct :c:type:`usb_gadget`. The response to a set_configuration usually
-involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by
-the gadget, and submitting one or more struct :c:type:`usb_request` buffers to
+for a struct usb_gadget. The response to a set_configuration usually
+involves enabling one or more of the struct usb_ep objects exposed by
+the gadget, and submitting one or more struct usb_request buffers to
 transfer data. Understand those four data types, and their operations,
 and you will understand how this API works.
 
@@ -339,8 +339,8 @@ multi-configuration devices (also more than one function, but not
 necessarily sharing a given configuration). There is however an optional
 framework which makes it easier to reuse and combine functions.
 
-Devices using this framework provide a struct :c:type:`usb_composite_driver`,
-which in turn provides one or more struct :c:type:`usb_configuration`
+Devices using this framework provide a struct usb_composite_driver,
+which in turn provides one or more struct usb_configuration
 instances. Each such configuration includes at least one struct
 :c:type:`usb_function`, which packages a user visible role such as "network
 link" or "mass storage device". Management functions may also exist,
diff --git a/Documentation/driver-api/usb/hotplug.rst b/Documentation/driver-api/usb/hotplug.rst
index 79663e653ca1..c1e13107c50e 100644
--- a/Documentation/driver-api/usb/hotplug.rst
+++ b/Documentation/driver-api/usb/hotplug.rst
@@ -122,7 +122,7 @@ and their quirks, might have a MODULE_DEVICE_TABLE like this::
 Most USB device drivers should pass these tables to the USB subsystem as
 well as to the module management subsystem.  Not all, though: some driver
 frameworks connect using interfaces layered over USB, and so they won't
-need such a struct :c:type:`usb_driver`.
+need such a struct usb_driver.
 
 Drivers that connect directly to the USB subsystem should be declared
 something like this::
diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst
index 423c5a0daf45..4f858b38a412 100644
--- a/Documentation/filesystems/fscrypt.rst
+++ b/Documentation/filesystems/fscrypt.rst
@@ -437,7 +437,7 @@ FS_IOC_SET_ENCRYPTION_POLICY
 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
 empty directory or verifies that a directory or regular file already
 has the specified encryption policy.  It takes in a pointer to a
-:c:type:`struct fscrypt_policy_v1` or a :c:type:`struct
+struct fscrypt_policy_v1 or a :c:type:`struct
 fscrypt_policy_v2`, defined as follows::
 
     #define FSCRYPT_POLICY_V1               0
@@ -508,7 +508,7 @@ This structure must be initialized as follows:
   replaced with ``master_key_identifier``, which is longer and cannot
   be arbitrarily chosen.  Instead, the key must first be added using
   `FS_IOC_ADD_ENCRYPTION_KEY`_.  Then, the ``key_spec.u.identifier``
-  the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must
+  the kernel returned in the struct fscrypt_add_key_arg must
   be used as the ``master_key_identifier`` in the :c:type:`struct
   fscrypt_policy_v2`.
 
@@ -590,7 +590,7 @@ FS_IOC_GET_ENCRYPTION_POLICY_EX
 The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
 policy, if any, for a directory or regular file.  No additional
 permissions are required beyond the ability to open the file.  It
-takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`,
+takes in a pointer to a struct fscrypt_get_policy_ex_arg,
 defined as follows::
 
     struct fscrypt_get_policy_ex_arg {
@@ -680,7 +680,7 @@ the filesystem, making all files on the filesystem which were
 encrypted using that key appear "unlocked", i.e. in plaintext form.
 It can be executed on any file or directory on the target filesystem,
 but using the filesystem's root directory is recommended.  It takes in
-a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as
+a pointer to a struct fscrypt_add_key_arg, defined as
 follows::
 
     struct fscrypt_add_key_arg {
@@ -710,7 +710,7 @@ follows::
             __u8 raw[];
     };
 
-:c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized
+struct fscrypt_add_key_arg must be zeroed, then initialized
 as follows:
 
 - If the key is being added for use by v1 encryption policies, then
@@ -860,7 +860,7 @@ The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
 encryption key from the filesystem, and possibly removes the key
 itself.  It can be executed on any file or directory on the target
 filesystem, but using the filesystem's root directory is recommended.
-It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`,
+It takes in a pointer to a struct fscrypt_remove_key_arg,
 defined as follows::
 
     struct fscrypt_remove_key_arg {
@@ -1149,7 +1149,7 @@ Encryption context
 ------------------
 
 An encryption policy is represented on-disk by a :c:type:`struct
-fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`.  It is
+fscrypt_context_v1` or a struct fscrypt_context_v2.  It is
 up to individual filesystems to decide where to store it, but normally
 it would be stored in a hidden extended attribute.  It should *not* be
 exposed by the xattr-related system calls such as getxattr() and
diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst
index 6c8944f6f0f7..895e9711ed88 100644
--- a/Documentation/filesystems/fsverity.rst
+++ b/Documentation/filesystems/fsverity.rst
@@ -84,7 +84,7 @@ FS_IOC_ENABLE_VERITY
 --------------------
 
 The FS_IOC_ENABLE_VERITY ioctl enables fs-verity on a file.  It takes
-in a pointer to a :c:type:`struct fsverity_enable_arg`, defined as
+in a pointer to a struct fsverity_enable_arg, defined as
 follows::
 
     struct fsverity_enable_arg {
diff --git a/Documentation/sound/designs/tracepoints.rst b/Documentation/sound/designs/tracepoints.rst
index 78bc5572f829..b0a7e3010187 100644
--- a/Documentation/sound/designs/tracepoints.rst
+++ b/Documentation/sound/designs/tracepoints.rst
@@ -34,20 +34,20 @@ substream. In this procedure, PCM hardware parameters are decided by
 interaction between applications and ALSA PCM core. Once decided, runtime of
 the PCM substream keeps the parameters.
 
-The parameters are described in :c:type:`struct snd_pcm_hw_params`. This
+The parameters are described in struct snd_pcm_hw_params. This
 structure includes several types of parameters. Applications set preferable
 value to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINE
 or SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining available
 set of parameters. The latter is used for an actual decision of the parameters.
 
-The :c:type:`struct snd_pcm_hw_params` structure has below members:
+The struct snd_pcm_hw_params structure has below members:
 
 ``flags``
         Configurable. ALSA PCM core and some drivers handle this flag to select
         convenient parameters or change their behaviour.
 ``masks``
         Configurable. This type of parameter is described in
-        :c:type:`struct snd_mask` and represent mask values. As of PCM protocol
+        struct snd_mask and represent mask values. As of PCM protocol
         v2.0.13, three types are defined.
 
         - SNDRV_PCM_HW_PARAM_ACCESS
@@ -55,7 +55,7 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members:
         - SNDRV_PCM_HW_PARAM_SUBFORMAT
 ``intervals``
         Configurable. This type of parameter is described in
-        :c:type:`struct snd_interval` and represent values with a range. As of
+        struct snd_interval and represent values with a range. As of
         PCM protocol v2.0.13, twelve types are defined.
 
         - SNDRV_PCM_HW_PARAM_SAMPLE_BITS
@@ -78,7 +78,7 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members:
         are going to be changed.
 ``cmask``
         Read-only. After returning from ioctl(2), buffer in user space for
-        :c:type:`struct snd_pcm_hw_params` includes result of each operation.
+        struct snd_pcm_hw_params includes result of each operation.
         This mask represents which mask/interval parameter is actually changed.
 ``info``
         Read-only. This represents hardware/driver capabilities as bit flags
@@ -110,10 +110,10 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members:
         value to this parameter but some drivers intentionally set zero with
         a care of hardware design or data transmission protocol.
 
-ALSA PCM core handles buffer of :c:type:`struct snd_pcm_hw_params` when
+ALSA PCM core handles buffer of struct snd_pcm_hw_params when
 applications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS.
 Parameters in the buffer are changed according to
-:c:type:`struct snd_pcm_hardware` and rules of constraints in the runtime. The
+struct snd_pcm_hardware and rules of constraints in the runtime. The
 structure describes capabilities of handled hardware. The rules describes
 dependencies on which a parameter is decided according to several parameters.
 A rule has a callback function, and drivers can register arbitrary functions
@@ -121,17 +121,17 @@ to compute the target parameter. ALSA PCM core registers some rules to the
 runtime as a default.
 
 Each driver can join in the interaction as long as it prepared for two stuffs
-in a callback of :c:type:`struct snd_pcm_ops.open`.
+in a callback of struct snd_pcm_ops.open.
 
 1. In the callback, drivers are expected to change a member of
-   :c:type:`struct snd_pcm_hardware` type in the runtime, according to
+   struct snd_pcm_hardware type in the runtime, according to
    capacities of corresponding hardware.
 2. In the same callback, drivers are also expected to register additional rules
    of constraints into the runtime when several parameters have dependencies
    due to hardware design.
 
 The driver can refers to result of the interaction in a callback of
-:c:type:`struct snd_pcm_ops.hw_params`, however it should not change the
+struct snd_pcm_ops.hw_params, however it should not change the
 content.
 
 Tracepoints in this category are designed to trace changes of the
@@ -163,7 +163,7 @@ fields are different according to type of the parameter. For parameters of mask
 type, the fields represent hexadecimal dump of content of the parameter. For
 parameters of interval type, the fields represent values of each member of
 ``empty``, ``integer``, ``openmin``, ``min``, ``max``, ``openmax`` in
-:c:type:`struct snd_interval` in this order.
+struct snd_interval in this order.
 
 Tracepoints in drivers
 ======================
diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl
index 00a69aceff44..1910079f984f 100755
--- a/Documentation/sphinx/parse-headers.pl
+++ b/Documentation/sphinx/parse-headers.pl
@@ -110,7 +110,7 @@ while (<IN>) {
 	    ) {
 		my $s = $1;
 
-		$structs{$s} = "struct :c:type:`$s`\\ ";
+		$structs{$s} = "struct $s\\ ";
 		next;
 	}
 }
diff --git a/Documentation/vm/ksm.rst b/Documentation/vm/ksm.rst
index d1b7270ad55c..9e37add068e6 100644
--- a/Documentation/vm/ksm.rst
+++ b/Documentation/vm/ksm.rst
@@ -26,7 +26,7 @@ tree.
 
 If a KSM page is shared between less than ``max_page_sharing`` VMAs,
 the node of the stable tree that represents such KSM page points to a
-list of :c:type:`struct rmap_item` and the ``page->mapping`` of the
+list of struct rmap_item and the ``page->mapping`` of the
 KSM page points to the stable tree node.
 
 When the sharing passes this threshold, KSM adds a second dimension to
diff --git a/Documentation/vm/memory-model.rst b/Documentation/vm/memory-model.rst
index 769449734573..9daadf9faba1 100644
--- a/Documentation/vm/memory-model.rst
+++ b/Documentation/vm/memory-model.rst
@@ -24,7 +24,7 @@ whether it is possible to manually override that default.
    although it is still in use by several architectures.
 
 All the memory models track the status of physical page frames using
-:c:type:`struct page` arranged in one or more arrays.
+struct page arranged in one or more arrays.
 
 Regardless of the selected memory model, there exists one-to-one
 mapping between the physical page frame number (PFN) and the
@@ -111,7 +111,7 @@ maps for non-volatile memory devices and deferred initialization of
 the memory map for larger systems.
 
 The SPARSEMEM model presents the physical memory as a collection of
-sections. A section is represented with :c:type:`struct mem_section`
+sections. A section is represented with struct mem_section
 that contains `section_mem_map` that is, logically, a pointer to an
 array of struct pages. However, it is stored with some other magic
 that aids the sections management. The section size and maximal number
@@ -172,7 +172,7 @@ management.
 
 The virtually mapped memory map allows storing `struct page` objects
 for persistent memory devices in pre-allocated storage on those
-devices. This storage is represented with :c:type:`struct vmem_altmap`
+devices. This storage is represented with struct vmem_altmap
 that is eventually passed to vmemmap_populate() through a long chain
 of function calls. The vmemmap_populate() implementation may use the
 `vmem_altmap` along with :c:func:`vmemmap_alloc_block_buf` helper to
diff --git a/mm/ksm.c b/mm/ksm.c
index 9afccc36dbd2..0960750bb316 100644
--- a/mm/ksm.c
+++ b/mm/ksm.c
@@ -81,7 +81,7 @@
  *   different KSM page copy of that content
  *
  * Internally, the regular nodes, "dups" and "chains" are represented
- * using the same :c:type:`struct stable_node` structure.
+ * using the same struct stable_node structure.
  *
  * In addition to the stable tree, KSM uses a second data structure called the
  * unstable tree: this tree holds pointers to pages which have been found to
diff --git a/mm/memblock.c b/mm/memblock.c
index 45f198750be9..670216826940 100644
--- a/mm/memblock.c
+++ b/mm/memblock.c
@@ -48,12 +48,12 @@
  *   boot regardless of the possible restrictions and memory hot(un)plug;
  *   the ``physmem`` type is only available on some architectures.
  *
- * Each region is represented by :c:type:`struct memblock_region` that
+ * Each region is represented by struct memblock_region that
  * defines the region extents, its attributes and NUMA node id on NUMA
  * systems. Every memory type is described by the :c:type:`struct
  * memblock_type` which contains an array of memory regions along with
  * the allocator metadata. The "memory" and "reserved" types are nicely
- * wrapped with :c:type:`struct memblock`. This structure is statically
+ * wrapped with struct memblock. This structure is statically
  * initialized at build time. The region arrays are initially sized to
  * %INIT_MEMBLOCK_REGIONS for "memory" and %INIT_MEMBLOCK_RESERVED_REGIONS
  * for "reserved". The region array for "physmem" is initially sized to
-- 
2.26.2

[PATCH v6 24/80] docs: trace-uses.rst: remove bogus c-domain tags

[Mauro Carvalho Chehab]

There are some c-domain tags that are wrong. While this won't
cause problems with Sphinx < 3.0, this cause troubles with
newer versions, as the C parser won't recognize the contents
of the tag, and will drop it from the output.

Let's just place them at literal blocks.

Reviewed-by: Kamalesh Babulal <kamalesh@linux.vnet.ibm.com>
Acked-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/trace/ftrace-uses.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/trace/ftrace-uses.rst b/Documentation/trace/ftrace-uses.rst
index 2a05e770618a..a4955f7e3d19 100644
--- a/Documentation/trace/ftrace-uses.rst
+++ b/Documentation/trace/ftrace-uses.rst
@@ -55,17 +55,17 @@ an ftrace_ops with ftrace:
 
 Both .flags and .private are optional. Only .func is required.
 
-To enable tracing call:
+To enable tracing call::
 
-.. c:function::  register_ftrace_function(&ops);
+    register_ftrace_function(&ops);
 
-To disable tracing call:
+To disable tracing call::
 
-.. c:function::  unregister_ftrace_function(&ops);
+    unregister_ftrace_function(&ops);
 
-The above is defined by including the header:
+The above is defined by including the header::
 
-.. c:function:: #include <linux/ftrace.h>
+    #include <linux/ftrace.h>
 
 The registered callback will start being called some time after the
 register_ftrace_function() is called and before it returns. The exact time
-- 
2.26.2

[PATCH v6 25/80] docs: it_IT: fix namespace collisions at locking.rst

[Mauro Carvalho Chehab]

The C domain functions there collide with the English ones,
due to namespace collision, generating lots of warnings with
Sphinx 3.x:

	./include/linux/mutex.h:121: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
	Declaration is 'mutex_init'.
	./include/linux/mutex.h:152: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
	Declaration is 'mutex_is_locked'.
	./include/linux/mutex.h:226: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
	Declaration is 'mutex_trylock_recursive'.
	./kernel/locking/mutex.c:281: WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
	Declaration is 'mutex_lock'.
	...

Add a namespace tag there, in order to prevent that.

Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/translations/it_IT/kernel-hacking/locking.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst
index 4615df5723fb..bf1acd6204ef 100644
--- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
@@ -1,5 +1,7 @@
 .. include:: ../disclaimer-ita.rst
 
+.. c:namespace:: it_IT
+
 :Original: :ref:`Documentation/kernel-hacking/locking.rst <kernel_hacking_lock>`
 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
 
-- 
2.26.2

[PATCH v6 26/80] docs: net: ieee802154.rst: fix C expressions

[Mauro Carvalho Chehab]

There are some warnings produced with Sphinx 3.x:

	Documentation/networking/ieee802154.rst:29: WARNING: Error in declarator or parameters
	Invalid C declaration: Expecting "(" in parameters. [error at 7]
	  int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
	  -------^
	Documentation/networking/ieee802154.rst:134: WARNING: Invalid C declaration: Expected end of definition. [error at 81]
	  void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi):
	  ---------------------------------------------------------------------------------^
	Documentation/networking/ieee802154.rst:139: WARNING: Invalid C declaration: Expected end of definition. [error at 95]
	  void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling):
	  -----------------------------------------------------------------------------------------------^
	Documentation/networking/ieee802154.rst:158: WARNING: Invalid C declaration: Expected end of definition. [error at 35]
	  int start(struct ieee802154_hw *hw):
	  -----------------------------------^
	Documentation/networking/ieee802154.rst:162: WARNING: Invalid C declaration: Expected end of definition. [error at 35]
	  void stop(struct ieee802154_hw *hw):
	  -----------------------------------^
	Documentation/networking/ieee802154.rst:166: WARNING: Invalid C declaration: Expected end of definition. [error at 61]
	  int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb):
	  -------------------------------------------------------------^
	Documentation/networking/ieee802154.rst:171: WARNING: Invalid C declaration: Expected end of definition. [error at 43]
	  int ed(struct ieee802154_hw *hw, u8 *level):
	  -------------------------------------------^
	Documentation/networking/ieee802154.rst:176: WARNING: Invalid C declaration: Expected end of definition. [error at 62]
	  int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel):
	  --------------------------------------------------------------^

Caused by some bad c:function: prototypes. Fix them.

Acked-by: David S. Miller <davem@davemloft.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/networking/ieee802154.rst | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/Documentation/networking/ieee802154.rst b/Documentation/networking/ieee802154.rst
index 6f4bf8447a21..f27856d77c8b 100644
--- a/Documentation/networking/ieee802154.rst
+++ b/Documentation/networking/ieee802154.rst
@@ -26,7 +26,9 @@ The stack is composed of three main parts:
 Socket API
 ==========
 
-.. c:function:: int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
+::
+
+    int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
 
 The address family, socket addresses etc. are defined in the
 include/net/af_ieee802154.h header or in the special header
@@ -131,12 +133,12 @@ Register PHY in the system.
 
 Freeing registered PHY.
 
-.. c:function:: void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi):
+.. c:function:: void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi)
 
 Telling 802.15.4 module there is a new received frame in the skb with
 the RF Link Quality Indicator (LQI) from the hardware device.
 
-.. c:function:: void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling):
+.. c:function:: void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling)
 
 Telling 802.15.4 module the frame in the skb is or going to be
 transmitted through the hardware device
@@ -155,25 +157,25 @@ operations structure at least::
         ...
    };
 
-.. c:function:: int start(struct ieee802154_hw *hw):
+.. c:function:: int start(struct ieee802154_hw *hw)
 
 Handler that 802.15.4 module calls for the hardware device initialization.
 
-.. c:function:: void stop(struct ieee802154_hw *hw):
+.. c:function:: void stop(struct ieee802154_hw *hw)
 
 Handler that 802.15.4 module calls for the hardware device cleanup.
 
-.. c:function:: int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb):
+.. c:function:: int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb)
 
 Handler that 802.15.4 module calls for each frame in the skb going to be
 transmitted through the hardware device.
 
-.. c:function:: int ed(struct ieee802154_hw *hw, u8 *level):
+.. c:function:: int ed(struct ieee802154_hw *hw, u8 *level)
 
 Handler that 802.15.4 module calls for Energy Detection from the hardware
 device.
 
-.. c:function:: int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel):
+.. c:function:: int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel)
 
 Set radio for listening on specific channel of the hardware device.
 
-- 
2.26.2

[PATCH v6 27/80] docs: genericirq.rst: don't document chip.c functions twice

[Mauro Carvalho Chehab]

Currently, kernel/irq/chip.c is included twice, one for
export functions, and then for internal ones. However, as
the :export:  and :internal: tags are missing, they ended
being included twice.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/core-api/genericirq.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst
index 8f06d885c310..f959c9b53f61 100644
--- a/Documentation/core-api/genericirq.rst
+++ b/Documentation/core-api/genericirq.rst
@@ -419,6 +419,7 @@ functions which are exported.
 .. kernel-doc:: kernel/irq/manage.c
 
 .. kernel-doc:: kernel/irq/chip.c
+   :export:
 
 Internal Functions Provided
 ===========================
@@ -431,6 +432,7 @@ functions.
 .. kernel-doc:: kernel/irq/handle.c
 
 .. kernel-doc:: kernel/irq/chip.c
+   :internal:
 
 Credits
 =======
-- 
2.26.2

[PATCH v6 28/80] docs: kernel-api.rst: drop kernel/irq/manage.c kernel-doc tag

[Mauro Carvalho Chehab]

This is already included at genericirq.rst. Adding it twice
causes C namespace duplication:

	.../Documentation/core-api/kernel-api:237: ../kernel/irq/manage.c:100: WARNING: Duplicate C declaration, also defined in 'genericirq'.
	Declaration is 'synchronize_hardirq'.
	.../Documentation/core-api/kernel-api:237: ../kernel/irq/manage.c:128: WARNING: Duplicate C declaration, also defined in 'genericirq'.
	Declaration is 'synchronize_irq'.
	.../Documentation/core-api/kernel-api:237: ../kernel/irq/manage.c:443: WARNING: Duplicate C declaration, also defined in 'genericirq'.
	Declaration is 'irq_set_affinity_notifier'.
	...

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/core-api/kernel-api.rst | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 4ac53a1363f6..741aa37dc181 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -231,12 +231,6 @@ Refer to the file kernel/module.c for more information.
 Hardware Interfaces
 ===================
 
-Interrupt Handling
-------------------
-
-.. kernel-doc:: kernel/irq/manage.c
-   :export:
-
 DMA Channels
 ------------
 
-- 
2.26.2

[PATCH v6 29/80] docs: remove sound API duplication

[Mauro Carvalho Chehab]

The sound API is documented on two different parts:
under Documentation/driver-api/sound.rst and under
Documentation/sound/kernel-api/alsa-driver-api.rst.

The alsa-driver-api.rst seems more complete, and APIs
are split per type. There's just one missing kernel-doc
markup there.

Add it and drop the duplicated one.

Reviewed-by: Takashi Iwai <tiwai@suse.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/index.rst            |  1 -
 Documentation/driver-api/sound.rst            | 54 -------------------
 .../sound/kernel-api/alsa-driver-api.rst      |  1 +
 3 files changed, 1 insertion(+), 55 deletions(-)
 delete mode 100644 Documentation/driver-api/sound.rst

diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 5ef2cfe3a16b..90d02c5fb155 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -28,7 +28,6 @@ available subsections can be seen below.
    component
    message-based
    infiniband
-   sound
    frame-buffer
    regulator
    iio/index
diff --git a/Documentation/driver-api/sound.rst b/Documentation/driver-api/sound.rst
deleted file mode 100644
index afef6eabc073..000000000000
--- a/Documentation/driver-api/sound.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-Sound Devices
-=============
-
-.. kernel-doc:: include/sound/core.h
-   :internal:
-
-.. kernel-doc:: sound/sound_core.c
-   :export:
-
-.. kernel-doc:: include/sound/pcm.h
-   :internal:
-
-.. kernel-doc:: sound/core/pcm.c
-   :export:
-
-.. kernel-doc:: sound/core/device.c
-   :export:
-
-.. kernel-doc:: sound/core/info.c
-   :export:
-
-.. kernel-doc:: sound/core/rawmidi.c
-   :export:
-
-.. kernel-doc:: sound/core/sound.c
-   :export:
-
-.. kernel-doc:: sound/core/memory.c
-   :export:
-
-.. kernel-doc:: sound/core/pcm_memory.c
-   :export:
-
-.. kernel-doc:: sound/core/init.c
-   :export:
-
-.. kernel-doc:: sound/core/isadma.c
-   :export:
-
-.. kernel-doc:: sound/core/control.c
-   :export:
-
-.. kernel-doc:: sound/core/pcm_lib.c
-   :export:
-
-.. kernel-doc:: sound/core/hwdep.c
-   :export:
-
-.. kernel-doc:: sound/core/pcm_native.c
-   :export:
-
-.. kernel-doc:: sound/core/memalloc.c
-   :export:
-
diff --git a/Documentation/sound/kernel-api/alsa-driver-api.rst b/Documentation/sound/kernel-api/alsa-driver-api.rst
index c8cc651eccf7..d24c64df7069 100644
--- a/Documentation/sound/kernel-api/alsa-driver-api.rst
+++ b/Documentation/sound/kernel-api/alsa-driver-api.rst
@@ -132,3 +132,4 @@ ISA DMA Helpers
 Other Helper Macros
 -------------------
 .. kernel-doc:: include/sound/core.h
+.. kernel-doc:: sound/sound_core.c
-- 
2.26.2

[PATCH v6 30/80] docs: basics.rst: move kernel-doc workqueue markups to workqueue.rst

[Mauro Carvalho Chehab]

As there's already a rst file with workqueue markups, containing
part of them, move the other definitions, in order to avoid
warnings with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/core-api/workqueue.rst | 2 ++
 Documentation/driver-api/basics.rst  | 9 ---------
 2 files changed, 2 insertions(+), 9 deletions(-)

diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst
index 00a5ba51e63f..541d31de8926 100644
--- a/Documentation/core-api/workqueue.rst
+++ b/Documentation/core-api/workqueue.rst
@@ -396,3 +396,5 @@ Kernel Inline Documentations Reference
 ======================================
 
 .. kernel-doc:: include/linux/workqueue.h
+
+.. kernel-doc:: kernel/workqueue.c
diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 1ba88c7b3984..54f8d5ca7475 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -55,15 +55,6 @@ High-resolution timers
 .. kernel-doc:: kernel/time/hrtimer.c
    :export:
 
-Workqueues and Kevents
-----------------------
-
-.. kernel-doc:: include/linux/workqueue.h
-   :internal:
-
-.. kernel-doc:: kernel/workqueue.c
-   :export:
-
 Internal Functions
 ------------------
 
-- 
2.26.2

[PATCH v6 31/80] docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup

[Mauro Carvalho Chehab]

This is already included at scsi.rst. So, remove the duplication,
in order to avoid Sphinx warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/target.rst | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/Documentation/driver-api/target.rst b/Documentation/driver-api/target.rst
index 620ec6173a93..c70ca25171c0 100644
--- a/Documentation/driver-api/target.rst
+++ b/Documentation/driver-api/target.rst
@@ -41,18 +41,6 @@ iSCSI boot information
 .. kernel-doc:: drivers/scsi/iscsi_boot_sysfs.c
    :export:
 
-
-iSCSI transport class
-=====================
-
-The file drivers/scsi/scsi_transport_iscsi.c defines transport
-attributes for the iSCSI class, which sends SCSI packets over TCP/IP
-connections.
-
-.. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c
-   :export:
-
-
 iSCSI TCP interfaces
 ====================
 
-- 
2.26.2

[PATCH v6 32/80] docs: device_link.rst: remove duplicated kernel-doc include

[Mauro Carvalho Chehab]

The infrastructure.rst file already includes the external
symbols from drivers/base/core.c.

Duplicating 3 functions there causes namespace collisions:

	Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
	Declaration is 'device_link_state'.
	Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
	Declaration is 'device_link_add'.
	Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
	Declaration is 'device_link_del'.
	Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
	Declaration is 'device_link_remove'.

So, drop the reference, adding just a mention to the functions
associated with device_link.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/device_link.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst
index 76950d061632..ee913ae16371 100644
--- a/Documentation/driver-api/device_link.rst
+++ b/Documentation/driver-api/device_link.rst
@@ -317,5 +317,4 @@ State machine
 API
 ===
 
-.. kernel-doc:: drivers/base/core.c
-   :functions: device_link_add device_link_del device_link_remove
+See device_link_add(), device_link_del() and device_link_remove().
-- 
2.26.2

[PATCH v6 33/80] docs: basics.rst: get rid of rcu kernel-doc macros

[Mauro Carvalho Chehab]

Those are already defined at kernel-api.rst, as part of the
synchronization primitives chapter.

This solves several Sphinx 3 warnings, like:

	.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
	Declaration is 'rcu_idle_enter'.
	.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
	Declaration is 'rcu_idle_exit'.
	.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
	Declaration is 'rcu_is_watching'.
	.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
	Declaration is 'call_rcu'.
	.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
	Declaration is 'synchronize_rcu'.
	...

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/basics.rst | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 54f8d5ca7475..63bbe3ed5e76 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -103,12 +103,6 @@ Kernel utility functions
 .. kernel-doc:: kernel/panic.c
    :export:
 
-.. kernel-doc:: kernel/rcu/tree.c
-   :export:
-
-.. kernel-doc:: kernel/rcu/update.c
-   :export:
-
 .. kernel-doc:: include/linux/overflow.h
    :internal:
 
-- 
2.26.2

[PATCH v6 34/80] docs: pstore-blk.rst: fix kernel-doc tags

[Mauro Carvalho Chehab]

There is currently a problem with kernel-doc tags from blk.c:

	.../Documentation/admin-guide/pstore-blk:239: ./fs/pstore/blk.c:175: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
	Declaration is 'register_pstore_device'.
	.../Documentation/admin-guide/pstore-blk:239: ./fs/pstore/blk.c:432: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
	Declaration is 'register_pstore_blk'.
	.../Documentation/admin-guide/pstore-blk:242: ./include/linux/pstore_blk.h:43: WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
	Declaration is 'pstore_device_info'.

Basically, the internal parts is shown with :export:, instead
of :internal:. Yet, there are some other exported docs that
aren't at the document, because they lack :identifiers:.

So, instead, let's just use :export: at the kAPI part of
the documentation.

Acked-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/pstore-blk.rst | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/Documentation/admin-guide/pstore-blk.rst b/Documentation/admin-guide/pstore-blk.rst
index 296d5027787a..6898aba9fb5c 100644
--- a/Documentation/admin-guide/pstore-blk.rst
+++ b/Documentation/admin-guide/pstore-blk.rst
@@ -154,17 +154,11 @@ Configurations for driver
 Only a block device driver cares about these configurations. A block device
 driver uses ``register_pstore_blk`` to register to pstore/blk.
 
-.. kernel-doc:: fs/pstore/blk.c
-   :identifiers: register_pstore_blk
-
 A non-block device driver uses ``register_pstore_device`` with
 ``struct pstore_device_info`` to register to pstore/blk.
 
 .. kernel-doc:: fs/pstore/blk.c
-   :identifiers: register_pstore_device
-
-.. kernel-doc:: include/linux/pstore_blk.h
-   :identifiers: pstore_device_info
+   :export:
 
 Compression and header
 ----------------------
@@ -237,7 +231,7 @@ For developer reference, here are all the important structures and APIs:
    :internal:
 
 .. kernel-doc:: fs/pstore/blk.c
-   :export:
+   :internal:
 
 .. kernel-doc:: include/linux/pstore_blk.h
    :internal:
-- 
2.26.2

[PATCH v6 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags

[Mauro Carvalho Chehab]

The :c:type: tag has problems with Sphinx 3.x, as structs
there should be declared with c:struct.

So, remove them, relying at automarkup.py extension to
convert them into cross-references.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/filesystems/fscrypt.rst | 51 ++++++++++++---------------
 1 file changed, 23 insertions(+), 28 deletions(-)

diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst
index 4f858b38a412..46a9d1bd2ab5 100644
--- a/Documentation/filesystems/fscrypt.rst
+++ b/Documentation/filesystems/fscrypt.rst
@@ -437,8 +437,7 @@ FS_IOC_SET_ENCRYPTION_POLICY
 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
 empty directory or verifies that a directory or regular file already
 has the specified encryption policy.  It takes in a pointer to a
-struct fscrypt_policy_v1 or a :c:type:`struct
-fscrypt_policy_v2`, defined as follows::
+struct fscrypt_policy_v1 or a struct fscrypt_policy_v2, defined as follows::
 
     #define FSCRYPT_POLICY_V1               0
     #define FSCRYPT_KEY_DESCRIPTOR_SIZE     8
@@ -464,11 +463,10 @@ fscrypt_policy_v2`, defined as follows::
 
 This structure must be initialized as follows:
 
-- ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is
-  :c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct
-  is :c:type:`fscrypt_policy_v2`.  (Note: we refer to the original
-  policy version as "v1", though its version code is really 0.)  For
-  new encrypted directories, use v2 policies.
+- ``version`` must be FSCRYPT_POLICY_V1 (0) if struct fscrypt_policy_v1
+  is used or FSCRYPT_POLICY_V2 (2) if struct fscrypt_policy_v2 is used.
+  (Note: we refer to the original policy version as "v1", though its
+  version code is really 0.)  For new encrypted directories, use v2 policies.
 
 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
   be set to constants from ``<linux/fscrypt.h>`` which identify the
@@ -509,8 +507,7 @@ This structure must be initialized as follows:
   be arbitrarily chosen.  Instead, the key must first be added using
   `FS_IOC_ADD_ENCRYPTION_KEY`_.  Then, the ``key_spec.u.identifier``
   the kernel returned in the struct fscrypt_add_key_arg must
-  be used as the ``master_key_identifier`` in the :c:type:`struct
-  fscrypt_policy_v2`.
+  be used as the ``master_key_identifier`` in struct fscrypt_policy_v2.
 
 If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
 verifies that the file is an empty directory.  If so, the specified
@@ -637,9 +634,8 @@ The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the
 encryption policy, if any, for a directory or regular file.  However,
 unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
 FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
-version.  It takes in a pointer directly to a :c:type:`struct
-fscrypt_policy_v1` rather than a :c:type:`struct
-fscrypt_get_policy_ex_arg`.
+version.  It takes in a pointer directly to struct fscrypt_policy_v1
+rather than struct fscrypt_get_policy_ex_arg.
 
 The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
 for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
@@ -717,10 +713,9 @@ as follows:
   ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and
   ``key_spec.u.descriptor`` must contain the descriptor of the key
   being added, corresponding to the value in the
-  ``master_key_descriptor`` field of :c:type:`struct
-  fscrypt_policy_v1`.  To add this type of key, the calling process
-  must have the CAP_SYS_ADMIN capability in the initial user
-  namespace.
+  ``master_key_descriptor`` field of struct fscrypt_policy_v1.
+  To add this type of key, the calling process must have the
+  CAP_SYS_ADMIN capability in the initial user namespace.
 
   Alternatively, if the key is being added for use by v2 encryption
   policies, then ``key_spec.type`` must contain
@@ -737,8 +732,8 @@ as follows:
 
 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
   field.  Otherwise ``key_id`` is the ID of a Linux keyring key of
-  type "fscrypt-provisioning" whose payload is a :c:type:`struct
-  fscrypt_provisioning_key_payload` whose ``raw`` field contains the
+  type "fscrypt-provisioning" whose payload is
+  struct fscrypt_provisioning_key_payload whose ``raw`` field contains the
   raw key and whose ``type`` field matches ``key_spec.type``.  Since
   ``raw`` is variable-length, the total size of this key's payload
   must be ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the
@@ -956,8 +951,8 @@ FS_IOC_GET_ENCRYPTION_KEY_STATUS
 The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
 master encryption key.  It can be executed on any file or directory on
 the target filesystem, but using the filesystem's root directory is
-recommended.  It takes in a pointer to a :c:type:`struct
-fscrypt_get_key_status_arg`, defined as follows::
+recommended.  It takes in a pointer to struct fscrypt_get_key_status_arg,
+defined as follows::
 
     struct fscrypt_get_key_status_arg {
             /* input */
@@ -1148,12 +1143,12 @@ Implementation details
 Encryption context
 ------------------
 
-An encryption policy is represented on-disk by a :c:type:`struct
-fscrypt_context_v1` or a struct fscrypt_context_v2.  It is
-up to individual filesystems to decide where to store it, but normally
-it would be stored in a hidden extended attribute.  It should *not* be
-exposed by the xattr-related system calls such as getxattr() and
-setxattr() because of the special semantics of the encryption xattr.
+An encryption policy is represented on-disk by struct fscrypt_context_v1
+or struct fscrypt_context_v2.  It is up to individual filesystems to decide
+where to store it, but normally it would be stored in a hidden extended
+attribute.  It should *not* be exposed by the xattr-related system calls
+such as getxattr() and setxattr() because of the special semantics of the
+encryption xattr.
 (In particular, there would be much confusion if an encryption policy
 were to be added to or removed from anything other than an empty
 directory.)  These structs are defined as follows::
@@ -1249,8 +1244,8 @@ a strong "hash" of the ciphertext filename, along with the optional
 filesystem-specific hash(es) needed for directory lookups.  This
 allows the filesystem to still, with a high degree of confidence, map
 the filename given in ->lookup() back to a particular directory entry
-that was previously listed by readdir().  See :c:type:`struct
-fscrypt_nokey_name` in the source for more details.
+that was previously listed by readdir().  See struct fscrypt_nokey_name
+in the source for more details.
 
 Note that the precise way that filenames are presented to userspace
 without the key is subject to change in the future.  It is only meant
-- 
2.26.2

[PATCH v6 36/80] docs: devices.rst: get rid of :c:type macros

[Mauro Carvalho Chehab]

There's no need to use macros to use :c:type on this file,
as automarkup.py should do this automatically.

Also, this breaks compatibility with Sphinx 3.x, as there,
structs should be declared using .. c:struct.

So, get rid of them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/pm/devices.rst | 24 ++++++++----------------
 1 file changed, 8 insertions(+), 16 deletions(-)

diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst
index 946ad0b94e31..4bda8a21f5d1 100644
--- a/Documentation/driver-api/pm/devices.rst
+++ b/Documentation/driver-api/pm/devices.rst
@@ -1,14 +1,6 @@
 .. SPDX-License-Identifier: GPL-2.0
 .. include:: <isonum.txt>
 
-.. |struct dev_pm_ops| replace:: :c:type:`struct dev_pm_ops <dev_pm_ops>`
-.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>`
-.. |struct bus_type| replace:: :c:type:`struct bus_type <bus_type>`
-.. |struct device_type| replace:: :c:type:`struct device_type <device_type>`
-.. |struct class| replace:: :c:type:`struct class <class>`
-.. |struct wakeup_source| replace:: :c:type:`struct wakeup_source <wakeup_source>`
-.. |struct device| replace:: :c:type:`struct device <device>`
-
 .. _driverapi_pm_devices:
 
 ==============================
@@ -107,7 +99,7 @@ Device Power Management Operations
 
 Device power management operations, at the subsystem level as well as at the
 device driver level, are implemented by defining and populating objects of type
-|struct dev_pm_ops| defined in :file:`include/linux/pm.h`.  The roles of the
+struct dev_pm_ops defined in :file:`include/linux/pm.h`.  The roles of the
 methods included in it will be explained in what follows.  For now, it should be
 sufficient to remember that the last three methods are specific to runtime power
 management while the remaining ones are used during system-wide power
@@ -115,7 +107,7 @@ transitions.
 
 There also is a deprecated "old" or "legacy" interface for power management
 operations available at least for some subsystems.  This approach does not use
-|struct dev_pm_ops| objects and it is suitable only for implementing system
+struct dev_pm_ops objects and it is suitable only for implementing system
 sleep power management methods in a limited way.  Therefore it is not described
 in this document, so please refer directly to the source code for more
 information about it.
@@ -125,9 +117,9 @@ Subsystem-Level Methods
 -----------------------
 
 The core methods to suspend and resume devices reside in
-|struct dev_pm_ops| pointed to by the :c:member:`ops` member of
-|struct dev_pm_domain|, or by the :c:member:`pm` member of |struct bus_type|,
-|struct device_type| and |struct class|.  They are mostly of interest to the
+struct dev_pm_ops pointed to by the :c:member:`ops` member of
+struct dev_pm_domain, or by the :c:member:`pm` member of struct bus_type,
+struct device_type and struct class.  They are mostly of interest to the
 people writing infrastructure for platforms and buses, like PCI or USB, or
 device type and device class drivers.  They also are relevant to the writers of
 device drivers whose subsystems (PM domains, device types, device classes and
@@ -156,7 +148,7 @@ The :c:member:`power.can_wakeup` flag just records whether the device (and its
 driver) can physically support wakeup events.  The
 :c:func:`device_set_wakeup_capable()` routine affects this flag.  The
 :c:member:`power.wakeup` field is a pointer to an object of type
-|struct wakeup_source| used for controlling whether or not the device should use
+struct wakeup_source used for controlling whether or not the device should use
 its system wakeup mechanism and for notifying the PM core of system wakeup
 events signaled by the device.  This object is only present for wakeup-capable
 devices (i.e. devices whose :c:member:`can_wakeup` flags are set) and is created
@@ -713,8 +705,8 @@ nested inside another power domain. The nested domain is referred to as the
 sub-domain of the parent domain.
 
 Support for power domains is provided through the :c:member:`pm_domain` field of
-|struct device|.  This field is a pointer to an object of type
-|struct dev_pm_domain|, defined in :file:`include/linux/pm.h`, providing a set
+struct device.  This field is a pointer to an object of type
+struct dev_pm_domain, defined in :file:`include/linux/pm.h`, providing a set
 of power management callbacks analogous to the subsystem-level and device driver
 callbacks that are executed for the given device during all power transitions,
 instead of the respective subsystem-level callbacks.  Specifically, if a
-- 
2.26.2

[PATCH v6 37/80] docs: sound: writing-an-alsa-driver.rst: get rid of :c:type

[Mauro Carvalho Chehab]

the :c:type shouldn't be used with structs with Sphinx 3,
as the C domain there uses .. c:struct for structs.

As we have the automarkup extension, let's just get rid of
all :c:type as a whole, as those will be automagically
marked as such.

This solves a bunch of warnings with Sphinx 3, like those:

	.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:490: WARNING: Unparseable C cross-reference: 'calling snd_card_free'
	Invalid C declaration: Expected end of definition. [error at 8]
	  calling snd_card_free
	  --------^
	.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3328: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
	Invalid C declaration: Expected end of definition. [error at 20]
	  snd_rawmidi_transmit*
	  --------------------^
	.../Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3928: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
	Invalid C declaration: Expected end of definition. [error at 9]
	  copy_from/to_user
	  ---------^

Reviewed-by: Takashi Iwai <tiwai@suse.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../kernel-api/writing-an-alsa-driver.rst     | 105 ++++++++----------
 1 file changed, 47 insertions(+), 58 deletions(-)

diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index aa9d5ab183d2..85d6e9c643ef 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -194,7 +194,7 @@ The minimum flow for PCI soundcards is as follows:
 
 -  create ``remove`` callback.
 
--  create a :c:type:`struct pci_driver <pci_driver>` structure
+-  create a struct pci_driver structure
    containing the three pointers above.
 
 -  create an ``init`` function just calling the
@@ -487,7 +487,7 @@ The destructor, remove callback, simply releases the card instance. Then
 the ALSA middle layer will release all the attached components
 automatically.
 
-It would be typically just :c:func:`calling snd_card_free()`:
+It would be typically just calling :c:func:`snd_card_free()`:
 
 ::
 
@@ -560,16 +560,15 @@ return the card instance. The extra_size argument is used to allocate
 card->private_data for the chip-specific data. Note that these data are
 allocated by :c:func:`snd_card_new()`.
 
-The first argument, the pointer of struct :c:type:`struct device
-<device>`, specifies the parent device. For PCI devices, typically
-``&pci->`` is passed there.
+The first argument, the pointer of struct device, specifies the parent
+device. For PCI devices, typically ``&pci->`` is passed there.
 
 Components
 ----------
 
 After the card is created, you can attach the components (devices) to
 the card instance. In an ALSA driver, a component is represented as a
-:c:type:`struct snd_device <snd_device>` object. A component
+struct snd_device object. A component
 can be a PCM instance, a control interface, a raw MIDI interface, etc.
 Each such instance has one component entry.
 
@@ -628,7 +627,7 @@ argument of :c:func:`snd_card_new()`, i.e.
   err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
                      sizeof(struct mychip), &card);
 
-:c:type:`struct mychip <mychip>` is the type of the chip record.
+struct mychip is the type of the chip record.
 
 In return, the allocated record can be accessed as
 
@@ -890,7 +889,7 @@ functions.  These resources must be released in the destructor
 function (see below).
 
 Now assume that the PCI device has an I/O port with 8 bytes and an
-interrupt. Then :c:type:`struct mychip <mychip>` will have the
+interrupt. Then struct mychip will have the
 following fields:
 
 ::
@@ -1094,7 +1093,7 @@ PCI Entries
 -----------
 
 So far, so good. Let's finish the missing PCI stuff. At first, we need a
-:c:type:`struct pci_device_id <pci_device_id>` table for
+struct pci_device_id table for
 this chipset. It's a table of PCI vendor/device ID number, and some
 masks.
 
@@ -1110,19 +1109,17 @@ For example,
   };
   MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
 
-The first and second fields of the :c:type:`struct pci_device_id
-<pci_device_id>` structure are the vendor and device IDs. If you
-have no reason to filter the matching devices, you can leave the
-remaining fields as above. The last field of the :c:type:`struct
-pci_device_id <pci_device_id>` struct contains private data
-for this entry. You can specify any value here, for example, to define
-specific operations for supported device IDs. Such an example is found
-in the intel8x0 driver.
+The first and second fields of the struct pci_device_id are the vendor
+and device IDs. If you have no reason to filter the matching devices, you can
+leave the remaining fields as above. The last field of the
+struct pci_device_id contains private data for this entry. You can specify
+any value here, for example, to define specific operations for supported
+device IDs. Such an example is found in the intel8x0 driver.
 
 The last entry of this list is the terminator. You must specify this
 all-zero entry.
 
-Then, prepare the :c:type:`struct pci_driver <pci_driver>`
+Then, prepare the struct pci_driver
 record:
 
 ::
@@ -1439,8 +1436,8 @@ corresponding argument.
 If a chip supports multiple playbacks or captures, you can specify more
 numbers, but they must be handled properly in open/close, etc.
 callbacks. When you need to know which substream you are referring to,
-then it can be obtained from :c:type:`struct snd_pcm_substream
-<snd_pcm_substream>` data passed to each callback as follows:
+then it can be obtained from struct snd_pcm_substream data passed to each
+callback as follows:
 
 ::
 
@@ -1639,10 +1636,9 @@ In the sections below, important records are explained.
 Hardware Description
 ~~~~~~~~~~~~~~~~~~~~
 
-The hardware descriptor (:c:type:`struct snd_pcm_hardware
-<snd_pcm_hardware>`) contains the definitions of the fundamental
-hardware configuration. Above all, you'll need to define this in the
-`PCM open callback`_. Note that the runtime instance holds the copy of
+The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
+the fundamental hardware configuration. Above all, you'll need to define this
+in the `PCM open callback`_. Note that the runtime instance holds the copy of
 the descriptor, not the pointer to the existing descriptor. That is,
 in the open callback, you can modify the copied descriptor
 (``runtime->hw``) as you need. For example, if the maximum number of
@@ -1800,14 +1796,13 @@ Running Status
 ~~~~~~~~~~~~~~
 
 The running status can be referred via ``runtime->status``. This is
-the pointer to the :c:type:`struct snd_pcm_mmap_status
-<snd_pcm_mmap_status>` record. For example, you can get the current
+the pointer to the struct snd_pcm_mmap_status record.
+For example, you can get the current
 DMA hardware pointer via ``runtime->status->hw_ptr``.
 
 The DMA application pointer can be referred via ``runtime->control``,
-which points to the :c:type:`struct snd_pcm_mmap_control
-<snd_pcm_mmap_control>` record. However, accessing directly to
-this value is not recommended.
+which points to the struct snd_pcm_mmap_control record.
+However, accessing directly to this value is not recommended.
 
 Private Data
 ~~~~~~~~~~~~
@@ -1843,8 +1838,8 @@ error number such as ``-EINVAL``. To choose an appropriate error
 number, it is advised to check what value other parts of the kernel
 return when the same kind of request fails.
 
-The callback function takes at least the argument with :c:type:`struct
-snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip
+The callback function takes at least the argument with
+struct snd_pcm_substream pointer. To retrieve the chip
 record from the given substream instance, you can use the following
 macro.
 
@@ -2313,10 +2308,10 @@ non-atomic contexts. For example, the function
 :c:func:`snd_pcm_period_elapsed()` is called typically from the
 interrupt handler. But, if you set up the driver to use a threaded
 interrupt handler, this call can be in non-atomic context, too. In such
-a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm
-<snd_pcm>` object after creating it. When this flag is set, mutex
-and rwsem are used internally in the PCM core instead of spin and
-rwlocks, so that you can call all PCM functions safely in a non-atomic
+a case, you can set ``nonatomic`` filed of struct snd_pcm object
+after creating it. When this flag is set, mutex and rwsem are used internally
+in the PCM core instead of spin and rwlocks, so that you can call all PCM
+functions safely in a non-atomic
 context.
 
 Constraints
@@ -2357,8 +2352,7 @@ There are many different constraints. Look at ``sound/pcm.h`` for a
 complete list. You can even define your own constraint rules. For
 example, let's suppose my_chip can manage a substream of 1 channel if
 and only if the format is ``S16_LE``, otherwise it supports any format
-specified in the :c:type:`struct snd_pcm_hardware
-<snd_pcm_hardware>` structure (or in any other
+specified in struct snd_pcm_hardware> (or in any other
 constraint_list). You can build a rule like this:
 
 ::
@@ -2467,7 +2461,7 @@ Definition of Controls
 
 To create a new control, you need to define the following three
 callbacks: ``info``, ``get`` and ``put``. Then, define a
-:c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as:
+struct snd_kcontrol_new record, such as:
 
 ::
 
@@ -2602,8 +2596,8 @@ info callback
 ~~~~~~~~~~~~~
 
 The ``info`` callback is used to get detailed information on this
-control. This must store the values of the given :c:type:`struct
-snd_ctl_elem_info <snd_ctl_elem_info>` object. For example,
+control. This must store the values of the given
+struct snd_ctl_elem_info object. For example,
 for a boolean control with a single element:
 
 ::
@@ -2774,13 +2768,11 @@ In the simplest way, you can do like this:
   if (err < 0)
           return err;
 
-where ``my_control`` is the :c:type:`struct snd_kcontrol_new
-<snd_kcontrol_new>` object defined above, and chip is the object
-pointer to be passed to kcontrol->private_data which can be referred
-to in callbacks.
+where ``my_control`` is the struct snd_kcontrol_new object defined above,
+and chip is the object pointer to be passed to kcontrol->private_data which
+can be referred to in callbacks.
 
-:c:func:`snd_ctl_new1()` allocates a new :c:type:`struct
-snd_kcontrol <snd_kcontrol>` instance, and
+:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
 :c:func:`snd_ctl_add()` assigns the given control component to the
 card.
 
@@ -2797,10 +2789,9 @@ can call :c:func:`snd_ctl_notify()`. For example,
 This function takes the card pointer, the event-mask, and the control id
 pointer for the notification. The event-mask specifies the types of
 notification, for example, in the above example, the change of control
-values is notified. The id pointer is the pointer of :c:type:`struct
-snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can
-find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
-interrupts.
+values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
+to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
+for hardware volume interrupts.
 
 Metadata
 --------
@@ -2915,9 +2906,8 @@ with an ``ac97_bus_ops_t`` record with callback functions.
 
 The bus record is shared among all belonging ac97 instances.
 
-And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct
-snd_ac97_template <snd_ac97_template>` record together with
-the bus pointer created above.
+And then call :c:func:`snd_ac97_mixer()` with an struct snd_ac97_template
+record together with the bus pointer created above.
 
 ::
 
@@ -3118,11 +3108,10 @@ devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
 
 Usually, the port address corresponds to the command port and port + 1
 corresponds to the data port. If not, you may change the ``cport``
-field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward.
-However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is
+field of struct snd_mpu401 manually afterward.
+However, struct snd_mpu401 pointer is
 not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
-need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401
-<snd_mpu401>` explicitly,
+need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly,
 
 ::
 
@@ -3772,7 +3761,7 @@ For creating the SG-buffer handler, call
 :c:func:`snd_pcm_set_managed_buffer_all()` with
 ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
 pre-allocator. You need to pass ``&pci->dev``, where pci is
-the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as
+the struct pci_dev pointer of the chip as
 well.
 
 ::
-- 
2.26.2

[PATCH v6 38/80] docs: block: blk-mq.rst: get rid of :c:type

[Mauro Carvalho Chehab]

The :c:type macros are not used properly there, as reported
by Sphinx 3:

	./Documentation/block/blk-mq.rst:112: WARNING: Unparseable C cross-reference: 'hctx->dispatch'
	Invalid C declaration: Expected end of definition. [error at 4]
	  hctx->dispatch
	  ----^

Also, they won't be generating any cross references.

So, replace them by a literal markup.

Reviewed-by: André Almeida <andrealmeid@collabora.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/block/blk-mq.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst
index 86a632af02b0..a980d23af48c 100644
--- a/Documentation/block/blk-mq.rst
+++ b/Documentation/block/blk-mq.rst
@@ -110,9 +110,9 @@ block layer removes requests from the associated software queues and tries to
 dispatch to the hardware.
 
 If it's not possible to send the requests directly to hardware, they will be
-added to a linked list (:c:type:`hctx->dispatch`) of requests. Then,
+added to a linked list (``hctx->dispatch``) of requests. Then,
 next time the block layer runs a queue, it will send the requests laying at the
-:c:type:`dispatch` list first, to ensure a fairness dispatch with those
+``dispatch`` list first, to ensure a fairness dispatch with those
 requests that were ready to be sent first. The number of hardware queues
 depends on the number of hardware contexts supported by the hardware and its
 device driver, but it will not be more than the number of cores of the system.
-- 
2.26.2

[PATCH v6 39/80] docs: writing-an-alsa-driver.rst: fix some bad c:func: markups

[Mauro Carvalho Chehab]

Some such markups are invalid, as reported by Sphinx:

	./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3317: WARNING: Unparseable C cross-reference: 'snd_rawmidi_transmit*'
	Invalid C declaration: Expected end of definition. [error at 20]
	  snd_rawmidi_transmit*
	  --------------------^
	./Documentation/sound/kernel-api/writing-an-alsa-driver.rst:3917: WARNING: Unparseable C cross-reference: 'copy_from/to_user'
	Invalid C declaration: Expected end of definition. [error at 9]
	  copy_from/to_user
	  ---------^

The first case seems to be better replaced by a literal.

For the second one, let's generate cross-references, by
spliting it in two.

Reviewed-by: Takashi Iwai <tiwai@suse.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sound/kernel-api/writing-an-alsa-driver.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 85d6e9c643ef..73bbd59afc33 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -3315,8 +3315,7 @@ data and removes them from the buffer at once:
   }
 
 If you know beforehand how many bytes you can accept, you can use a
-buffer size greater than one with the
-:c:func:`snd_rawmidi_transmit\*()` functions.
+buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
 
 The ``trigger`` callback must not sleep. If the hardware FIFO is full
 before the substream buffer has been emptied, you have to continue
@@ -3916,7 +3915,7 @@ the maximum size of the proc file access.
 
 The read/write callbacks of raw mode are more direct than the text mode.
 You need to use a low-level I/O functions such as
-:c:func:`copy_from/to_user()` to transfer the data.
+:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the data.
 
 ::
 
-- 
2.26.2

[PATCH v6 40/80] docs: fpga: replace :c:member: macros

[Mauro Carvalho Chehab]

Those macros are not doing the right thing with Sphinx 3,
causing parse errors:

	./Documentation/driver-api/fpga/fpga-mgr.rst:104: WARNING: Unparseable C cross-reference: 'fpga_manager->state'
	Invalid C declaration: Expected end of definition. [error at 12]
	  fpga_manager->state
	  ------------^
	./Documentation/driver-api/fpga/fpga-programming.rst:18: WARNING: Unparseable C cross-reference: 'fpga_region->info'
	Invalid C declaration: Expected end of definition. [error at 11]
	  fpga_region->info
	  -----------^
	./Documentation/driver-api/fpga/fpga-region.rst:62: WARNING: Unparseable C cross-reference: 'fpga_region->bridge_list'
	Invalid C declaration: Expected end of definition. [error at 11]
	  fpga_region->bridge_list
	  -----------^
	./Documentation/driver-api/fpga/fpga-region.rst:62: WARNING: Unparseable C cross-reference: 'fpga_region->get_bridges'
	Invalid C declaration: Expected end of definition. [error at 11]
	  fpga_region->get_bridges
	  -----------^

Replace them by :c:expr:, with does what's desired.

Reviewed-by: Moritz Fischer <mdf@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/fpga/fpga-mgr.rst         | 2 +-
 Documentation/driver-api/fpga/fpga-programming.rst | 2 +-
 Documentation/driver-api/fpga/fpga-region.rst      | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
index 22f7885b32c9..917ee22db429 100644
--- a/Documentation/driver-api/fpga/fpga-mgr.rst
+++ b/Documentation/driver-api/fpga/fpga-mgr.rst
@@ -101,7 +101,7 @@ in state.
 API for implementing a new FPGA Manager driver
 ----------------------------------------------
 
-* ``fpga_mgr_states`` —  Values for :c:member:`fpga_manager->state`.
+* ``fpga_mgr_states`` —  Values for :c:expr:`fpga_manager->state`.
 * struct fpga_manager —  the FPGA manager struct
 * struct fpga_manager_ops —  Low level FPGA manager driver ops
 * devm_fpga_mgr_create() —  Allocate and init a manager struct
diff --git a/Documentation/driver-api/fpga/fpga-programming.rst b/Documentation/driver-api/fpga/fpga-programming.rst
index f487ad64dfb9..002392dab04f 100644
--- a/Documentation/driver-api/fpga/fpga-programming.rst
+++ b/Documentation/driver-api/fpga/fpga-programming.rst
@@ -15,7 +15,7 @@ the FPGA manager and bridges.  It will:
  * lock the mutex of the region's FPGA manager
  * build a list of FPGA bridges if a method has been specified to do so
  * disable the bridges
- * program the FPGA using info passed in :c:member:`fpga_region->info`.
+ * program the FPGA using info passed in :c:expr:`fpga_region->info`.
  * re-enable the bridges
  * release the locks
 
diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst
index 3e52be7e2968..363a8171ab0a 100644
--- a/Documentation/driver-api/fpga/fpga-region.rst
+++ b/Documentation/driver-api/fpga/fpga-region.rst
@@ -61,9 +61,9 @@ during the region's probe function.
 
 The FPGA region will need to specify which bridges to control while programming
 the FPGA.  The region driver can build a list of bridges during probe time
-(:c:member:`fpga_region->bridge_list`) or it can have a function that creates
+(:c:expr:`fpga_region->bridge_list`) or it can have a function that creates
 the list of bridges to program just before programming
-(:c:member:`fpga_region->get_bridges`).  The FPGA bridge framework supplies the
+(:c:expr:`fpga_region->get_bridges`).  The FPGA bridge framework supplies the
 following APIs to handle building or tearing down that list.
 
 * fpga_bridge_get_to_list() — Get a ref of an FPGA bridge, add it to a
-- 
2.26.2

[PATCH v6 41/80] docs: kgdb.rst: fix :c:type: usages

[Mauro Carvalho Chehab]

Which Sphinx 3, :c:type:  can't be used anymore for structs,
as this should be used only for typedefs.

Rely on automarkup.py for struct references.

This file has an special case, though: it uses the tag also
to point to an array. Let's use, instead, :c:expr: for such
purpose, as it should do the right thing.

This should fix this warning:

	./Documentation/dev-tools/kgdb.rst:875: WARNING: Unparseable C cross-reference: 'kdb_poll_funcs[]'
	Invalid C declaration: Expected end of definition. [error at 14]
	  kdb_poll_funcs[]
	  --------------^

Acked-by: Daniel Thompson <daniel.thompson@linaro.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/dev-tools/kgdb.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst
index c908ef4d3f04..77b688e6a254 100644
--- a/Documentation/dev-tools/kgdb.rst
+++ b/Documentation/dev-tools/kgdb.rst
@@ -726,7 +726,7 @@ The kernel debugger is organized into a number of components:
    -  contains an arch-specific trap catcher which invokes
       kgdb_handle_exception() to start kgdb about doing its work
 
-   -  translation to and from gdb specific packet format to :c:type:`pt_regs`
+   -  translation to and from gdb specific packet format to struct pt_regs
 
    -  Registration and unregistration of architecture specific trap
       hooks
@@ -846,7 +846,7 @@ invokes a callback in the serial core which in turn uses the callback in
 the UART driver.
 
 When using kgdboc with a UART, the UART driver must implement two
-callbacks in the :c:type:`struct uart_ops <uart_ops>`.
+callbacks in the struct uart_ops.
 Example from ``drivers/8250.c``::
 
 
@@ -875,7 +875,7 @@ kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
 The core polled keyboard driver for PS/2 type keyboards is in
 ``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
 when kgdboc populates the callback in the array called
-:c:type:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level
+:c:expr:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level
 function which polls hardware for single character input.
 
 kgdboc and kms
-- 
2.26.2

[PATCH v6 42/80] docs: libata.rst: fix a wrong usage of :c:type: tag

[Mauro Carvalho Chehab]

The usage of :c:type: to reference to a struct member is wrong,
as pointed by Sphinx 3:

	./Documentation/driver-api/libata.rst:511: WARNING: Unparseable C cross-reference: 'qc->complete_fn'
	Invalid C declaration: Expected end of definition. [error at 2]
	  qc->complete_fn
	  --^

Instead, let's use :c:expr: for such purpose.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/libata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/libata.rst b/Documentation/driver-api/libata.rst
index e2f87b82b074..d477e296bda5 100644
--- a/Documentation/driver-api/libata.rst
+++ b/Documentation/driver-api/libata.rst
@@ -508,7 +508,7 @@ also complete commands.
 
 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags.
 
-3. :c:func:`qc->complete_fn` callback is invoked. If the return value of the
+3. :c:expr:`qc->complete_fn` callback is invoked. If the return value of the
    callback is not zero. Completion is short circuited and
    :c:func:`ata_qc_complete` returns.
 
-- 
2.26.2

[PATCH v6 43/80] docs: infrastructure.rst: don't include firmware kernel-doc

[Mauro Carvalho Chehab]

Those are already documented at:

	Documentation/driver-api/firmware/request_firmware.rst

Including it twice is causing lots of warnings:

	./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
	Declaration is 'request_firmware'.
	./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
	Declaration is 'firmware_request_nowarn'.
	./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
	Declaration is 'request_firmware_direct'.
	./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
	Declaration is 'firmware_request_platform'.
	./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
	Declaration is 'firmware_request_cache'.
	./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
	Declaration is 'request_firmware_into_buf'.
	./Documentation/driver-api/infrastructure.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
	Declaration is 'request_firmware_nowait'.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/infrastructure.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst
index 06d98c4526df..e38d79be4e16 100644
--- a/Documentation/driver-api/infrastructure.rst
+++ b/Documentation/driver-api/infrastructure.rst
@@ -28,9 +28,6 @@ Device Drivers Base
 .. kernel-doc:: drivers/base/node.c
    :internal:
 
-.. kernel-doc:: drivers/base/firmware_loader/main.c
-   :export:
-
 .. kernel-doc:: drivers/base/transport_class.c
    :export:
 
-- 
2.26.2

[PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings

[Mauro Carvalho Chehab]

As reported by Sphinx:

	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_oa_wait_unlocked'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_oa_poll_wait'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_oa_read'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_oa_stream_enable'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_oa_stream_disable'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_oa_stream_init'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_read'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_poll_locked'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_poll'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_enable_locked'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_disable_locked'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_ioctl'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_destroy_locked'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_release'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_open_ioctl_locked'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'read_properties_unlocked'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_open_ioctl'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_register'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_unregister'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_add_config_ioctl'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_remove_config_ioctl'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_init'.
	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
	Declaration is 'i915_perf_fini'.

With Sphinx 3, C declarations can't be duplicated anymore,
so let's exclude those from the other internals found on
i915_perf.c file.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 33cc6ddf8f64..cff1f154b473 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
    :functions: i915_oa_poll_wait
 
-All i915 Perf Internals
------------------------
+Other i915 Perf Internals
+-------------------------
 
-This section simply includes all currently documented i915 perf internals, in
-no particular order, but may include some more minor utilities or platform
+This section simply includes all other currently documented i915 perf internals,
+in no particular order, but may include some more minor utilities or platform
 specific details than found in the more high-level sections.
 
 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
    :internal:
+   :no-identifiers:
+       i915_perf_init
+       i915_perf_fini
+       i915_perf_register
+       i915_perf_unregister
+       i915_perf_open_ioctl
+       i915_perf_release
+       i915_perf_add_config_ioctl
+       i915_perf_remove_config_ioctl
+       read_properties_unlocked
+       i915_perf_open_ioctl_locked
+       i915_perf_destroy_locked
+       i915_perf_read i915_perf_ioctl
+       i915_perf_enable_locked
+       i915_perf_disable_locked
+       i915_perf_poll i915_perf_poll_locked
+       i915_oa_stream_init i915_oa_read
+       i915_oa_stream_enable
+       i915_oa_stream_disable
+       i915_oa_wait_unlocked
+       i915_oa_poll_wait
 
 Style
 =====
-- 
2.26.2

[PATCH v6 45/80] docs: devices.rst: fix a C reference markup

[Mauro Carvalho Chehab]

The C domain parser of Sphinx3 expects just function names
for :c:func: markups:

	./Documentation/driver-api/pm/devices.rst:413: WARNING: Unparseable C cross-reference: 'device_may_wakeup(dev)'
	Invalid C declaration: Expected end of definition. [error at 17]
	  device_may_wakeup(dev)
	  -----------------^

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/pm/devices.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst
index 4bda8a21f5d1..6b3bfd29fd84 100644
--- a/Documentation/driver-api/pm/devices.rst
+++ b/Documentation/driver-api/pm/devices.rst
@@ -410,7 +410,7 @@ On many platforms they will gate off one or more clock sources; sometimes they
 will also switch off power supplies or reduce voltages.  [Drivers supporting
 runtime PM may already have performed some or all of these steps.]
 
-If :c:func:`device_may_wakeup(dev)` returns ``true``, the device should be
+If :c:func:`device_may_wakeup()` returns ``true``, the device should be
 prepared for generating hardware wakeup signals to trigger a system wakeup event
 when the system is in the sleep state.  For example, :c:func:`enable_irq_wake()`
 might identify GPIO signals hooked up to a switch or other external hardware,
-- 
2.26.2

[PATCH v6 46/80] docs: it_IT: hacking.rst: fix a typo on a markup

[Mauro Carvalho Chehab]

There's a missing "`", causing this warning:
	./Documentation/translations/it_IT/kernel-hacking/hacking.rst:404: WARNING: Unparseable C cross-reference: 'cpu_to_be32p(), che prende un puntatore\nad un tipo, e ritorna il valore convertito. L\'altra variante per\nla famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s'
	Invalid C declaration: Expected end of definition. [error at 14]
	  cpu_to_be32p(), che prende un puntatore
	ad un tipo, e ritorna il valore convertito. L'altra variante per
	la famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s
	  --------------^

Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/translations/it_IT/kernel-hacking/hacking.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
index 6aab27a8d323..3d30b69f1ec1 100644
--- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
@@ -402,7 +402,7 @@ il valore convertito. Tutte le varianti supportano anche il processo inverso:
 :c:func:`be32_to_cpu()`, eccetera.
 
 Queste funzioni hanno principalmente due varianti: la variante per
-puntatori, come :c:func:`cpu_to_be32p(), che prende un puntatore
+puntatori, come :c:func:`cpu_to_be32p()`, che prende un puntatore
 ad un tipo, e ritorna il valore convertito. L'altra variante per
 la famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s()`,
 che convertono il valore puntato da un puntatore, e ritornano void.
-- 
2.26.2

[PATCH v6 47/80] docs: mei.rst: fix a C expression markup

[Mauro Carvalho Chehab]

Sphinx 3.x doesn't allow expressions using :c:func markup:

	./Documentation/driver-api/mei/mei.rst:41: WARNING: Unparseable C cross-reference: 'close(int fd)'
	Invalid C declaration: Expected end of definition. [error at 5]
	  close(int fd)
	  -----^

So, convert it into a :c:expr.

Acked-by: Tomas Winkler <tomas.winkler@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/mei/mei.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/mei/mei.rst b/Documentation/driver-api/mei/mei.rst
index c800d8e5f422..71edf022a7fe 100644
--- a/Documentation/driver-api/mei/mei.rst
+++ b/Documentation/driver-api/mei/mei.rst
@@ -38,7 +38,7 @@ Because some of the Intel ME features can change the system
 configuration, the driver by default allows only a privileged
 user to access it.
 
-The session is terminated calling :c:func:`close(int fd)`.
+The session is terminated calling :c:expr:`close(fd)`.
 
 A code snippet for an application communicating with Intel AMTHI client:
 
-- 
2.26.2

[PATCH v6 48/80] docs: basics.rst: avoid duplicated C function declaration

[Mauro Carvalho Chehab]

pci_device_id is already documented at pci.rst:

	./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'PCI/pci'.
	Declaration is 'pci_device_id'.

The kstrtol and kstrtoul are already at kernel-api:

	./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
	Declaration is 'kstrtoul'.
	./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
	Declaration is 'kstrtol'.

And the printk is already defined at printk-basics:

	./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/printk-basics'.
	Declaration is 'printk'.

So, exclude those identifiers from basirs.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/basics.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 63bbe3ed5e76..3e2dae954898 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -12,6 +12,8 @@ Driver device table
 
 .. kernel-doc:: include/linux/mod_devicetable.h
    :internal:
+   :no-identifiers: pci_device_id
+
 
 Delaying, scheduling, and timer routines
 ----------------------------------------
@@ -96,9 +98,11 @@ Kernel utility functions
 
 .. kernel-doc:: include/linux/kernel.h
    :internal:
+   :no-identifiers: kstrtol kstrtoul
 
 .. kernel-doc:: kernel/printk/printk.c
    :export:
+   :no-identifiers: printk
 
 .. kernel-doc:: kernel/panic.c
    :export:
-- 
2.26.2

[PATCH v6 49/80] docs: conf.py: fix c:function support with Sphinx 3.x

[Mauro Carvalho Chehab]

Sphinx C parser for the C domain is now more pedantic when
trying to identify the function types. That prevents scope
macros to be used as type defines.

Yet, since 3.0.2, it is possible to provide it a list of
such macros. Add them, in order to solve several Sphinx 3.x
warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 65 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 62 insertions(+), 3 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 0a102d57437d..e1b16556e378 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -47,9 +47,68 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
 #
 if major >= 3:
     sys.stderr.write('''WARNING: The kernel documentation build process
-	does not work correctly with Sphinx v3.0 and above.  Expect errors
-	in the generated output.
-	''')
+        does not work correctly with Sphinx v3.0 and above.  Expect errors
+        in the generated output.
+        ''')
+    if minor > 0 or patch >= 2:
+        # Sphinx c function parser is more pedantic with regards to type
+        # checking. Due to that, having macros at c:function cause problems.
+        # Those needed to be scaped by using c_id_attributes[] array
+        c_id_attributes = [
+            # GCC Compiler types not parsed by Sphinx:
+            "__restrict__",
+
+            # include/linux/compiler_types.h:
+            "__iomem",
+            "__kernel",
+            "noinstr",
+            "notrace",
+            "__percpu",
+            "__rcu",
+            "__user",
+
+            # include/linux/compiler_attributes.h:
+            "__alias",
+            "__aligned",
+            "__aligned_largest",
+            "__always_inline",
+            "__assume_aligned",
+            "__cold",
+            "__attribute_const__",
+            "__copy",
+            "__pure",
+            "__designated_init",
+            "__visible",
+            "__printf",
+            "__scanf",
+            "__gnu_inline",
+            "__malloc",
+            "__mode",
+            "__no_caller_saved_registers",
+            "__noclone",
+            "__nonstring",
+            "__noreturn",
+            "__packed",
+            "__pure",
+            "__section",
+            "__always_unused",
+            "__maybe_unused",
+            "__used",
+            "__weak",
+            "noinline",
+
+            # include/linux/memblock.h:
+            "__init_memblock",
+            "__meminit",
+
+            # include/linux/init.h:
+            "__init",
+            "__ref",
+
+            # include/linux/linkage.h:
+            "asmlinkage",
+        ]
+
 else:
     extensions.append('cdomain')
 
-- 
2.26.2

[PATCH v6 50/80] docs: conf.py: change the Sphinx 3.x+ text

[Mauro Carvalho Chehab]

After the build fix patches, it is believed that the output
with Sphinx 3.x won't be a problem. Still, the C domain
support was re-written, and this can have caused hidden
issues.

So, let's keep the warning, changing it to a lighter
warning text.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index e1b16556e378..376dd0ddf39c 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -47,8 +47,8 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
 #
 if major >= 3:
     sys.stderr.write('''WARNING: The kernel documentation build process
-        does not work correctly with Sphinx v3.0 and above.  Expect errors
-        in the generated output.
+        support for Sphinx v3.0 and above is brand new. Be prepared for
+        possible issues in the generated output.
         ''')
     if minor > 0 or patch >= 2:
         # Sphinx c function parser is more pedantic with regards to type
-- 
2.26.2

[PATCH v6 51/80] docs: infrastructure.rst: exclude device_link_state from device.h

[Mauro Carvalho Chehab]

This is already documented at device_link.rst, causing this
warning, due to a broken cross-reference:

	.../Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
	Declaration is 'device_link_state'.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/infrastructure.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst
index e38d79be4e16..683bd460e222 100644
--- a/Documentation/driver-api/infrastructure.rst
+++ b/Documentation/driver-api/infrastructure.rst
@@ -6,6 +6,7 @@ The Basic Device Driver-Model Structures
 
 .. kernel-doc:: include/linux/device.h
    :internal:
+   :no-identifiers: device_link_state
 
 Device Drivers Base
 -------------------
-- 
2.26.2

[PATCH v6 52/80] docs: zh_CN: amu.rst: fix document title markup

[Mauro Carvalho Chehab]

As warned by Sphinx 2.4.4:
	.../Documentation/translations/zh_CN/arm64/amu.rst:7: WARNING: Title overline too short.

Increase its size.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/translations/zh_CN/arm64/amu.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/translations/zh_CN/arm64/amu.rst b/Documentation/translations/zh_CN/arm64/amu.rst
index bd875f221330..ab7180f91394 100644
--- a/Documentation/translations/zh_CN/arm64/amu.rst
+++ b/Documentation/translations/zh_CN/arm64/amu.rst
@@ -4,9 +4,9 @@
 
 Translator: Bailu Lin <bailu.lin@vivo.com>
 
-=================================
+==================================
 AArch64 Linux 中扩展的活动监控单元
-=================================
+==================================
 
 作者: Ionela Voinescu <ionela.voinescu@arm.com>
 
-- 
2.26.2

[PATCH v6 53/80] media: uAPI: buffer.rst: remove a left-over documentation

[Mauro Carvalho Chehab]

Changeset 129134e5415d ("media: media/v4l2: remove V4L2_FLAG_MEMORY_NON_CONSISTENT flag")
reverted an uAPI flag, but it kept some left-overs at the documentation.

Drop them too. This should solve this warning:

	Documentation/userspace-api/media/v4l/buffer.rst:692: WARNING: The "flat-table" directive is empty; content required.

	.. flat-table::
	    :header-rows:  0
	    :stub-columns: 0
	    :widths:       3 1 4

Fixes: 129134e5415d ("media: media/v4l2: remove V4L2_FLAG_MEMORY_NON_CONSISTENT flag")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/userspace-api/media/v4l/buffer.rst | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst
index 8be62dcffbb2..7dbdfbb4a0a9 100644
--- a/Documentation/userspace-api/media/v4l/buffer.rst
+++ b/Documentation/userspace-api/media/v4l/buffer.rst
@@ -678,20 +678,6 @@ Buffer Flags
 
 .. _memory-flags:
 
-Memory Consistency Flags
-========================
-
-.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}|
-
-.. cssclass:: longtable
-
-.. flat-table::
-    :header-rows:  0
-    :stub-columns: 0
-    :widths:       3 1 4
-
-.. c:type:: v4l2_memory
-
 enum v4l2_memory
 ================
 
-- 
2.26.2

[PATCH v6 54/80] math64.h: kernel-docs: Convert some markups into normal comments

[Mauro Carvalho Chehab]

There are several functions at math64.h that are also
defined at div64.c. As both are included at kernel-api.rst,
Sphinx 3.x complains about symbol duplication:

	./lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
	Declaration is 'div_s64_rem'.
	./lib/math/div64.c:104: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
	Declaration is 'div64_u64_rem'.
	./lib/math/div64.c:144: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
	Declaration is 'div64_u64'.
	./lib/math/div64.c:172: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
	Declaration is 'div64_s64'.

In order to avoid Sphinx warnings about duplication, change the kernel-doc
markups to just comments at math64.h.

Reviewed-by: Vincenzo Frascino <vincenzo.frascino@arm.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/math64.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/include/linux/math64.h b/include/linux/math64.h
index 3381d9e33c4e..66deb1fdc2ef 100644
--- a/include/linux/math64.h
+++ b/include/linux/math64.h
@@ -28,7 +28,7 @@ static inline u64 div_u64_rem(u64 dividend, u32 divisor, u32 *remainder)
 	return dividend / divisor;
 }
 
-/**
+/*
  * div_s64_rem - signed 64bit divide with 32bit divisor with remainder
  * @dividend: signed 64bit dividend
  * @divisor: signed 32bit divisor
@@ -42,7 +42,7 @@ static inline s64 div_s64_rem(s64 dividend, s32 divisor, s32 *remainder)
 	return dividend / divisor;
 }
 
-/**
+/*
  * div64_u64_rem - unsigned 64bit divide with 64bit divisor and remainder
  * @dividend: unsigned 64bit dividend
  * @divisor: unsigned 64bit divisor
@@ -56,7 +56,7 @@ static inline u64 div64_u64_rem(u64 dividend, u64 divisor, u64 *remainder)
 	return dividend / divisor;
 }
 
-/**
+/*
  * div64_u64 - unsigned 64bit divide with 64bit divisor
  * @dividend: unsigned 64bit dividend
  * @divisor: unsigned 64bit divisor
@@ -68,7 +68,7 @@ static inline u64 div64_u64(u64 dividend, u64 divisor)
 	return dividend / divisor;
 }
 
-/**
+/*
  * div64_s64 - signed 64bit divide with 64bit divisor
  * @dividend: signed 64bit dividend
  * @divisor: signed 64bit divisor
-- 
2.26.2

[PATCH v6 55/80] memblock: get rid of a :c:type leftover

[Mauro Carvalho Chehab]

chanseset b3a7bb1851c8 ("docs: get rid of :c:type explicit declarations for structs")
removed several :c:type: markups, except by one.

Now, Sphinx 3.x complains about it:

	.../Documentation/core-api/boot-time-mm:26: ../mm/memblock.c:51: WARNING: Unparseable C cross-reference: 'struct\nmemblock_type'
	Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
	  struct
	memblock_type
	  ------^

As, on Sphinx 3.x, the right markup is c:struct:`foo`.

So, let's remove it, relying on automarkup.py to convert it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 mm/memblock.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/mm/memblock.c b/mm/memblock.c
index 670216826940..a06e68b1e5a0 100644
--- a/mm/memblock.c
+++ b/mm/memblock.c
@@ -50,8 +50,8 @@
  *
  * Each region is represented by struct memblock_region that
  * defines the region extents, its attributes and NUMA node id on NUMA
- * systems. Every memory type is described by the :c:type:`struct
- * memblock_type` which contains an array of memory regions along with
+ * systems. Every memory type is described by the struct memblock_type
+ * which contains an array of memory regions along with
  * the allocator metadata. The "memory" and "reserved" types are nicely
  * wrapped with struct memblock. This structure is statically
  * initialized at build time. The region arrays are initially sized to
-- 
2.26.2

[PATCH v6 56/80] dt-bindings: fix references to files converted to yaml

[Mauro Carvalho Chehab]

There were several files converted to yaml, but the .txt file
is still referenced somewhere else.

Update the references for them to point to the right file.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../bindings/display/tilcdc/tilcdc.txt           |  2 +-
 .../devicetree/bindings/mailbox/omap-mailbox.txt |  2 +-
 .../devicetree/bindings/media/i2c/tvp5150.txt    |  2 +-
 .../bindings/pwm/google,cros-ec-pwm.yaml         |  2 +-
 .../bindings/soc/qcom/qcom,smd-rpm.yaml          |  2 +-
 .../bindings/sound/google,cros-ec-codec.yaml     |  2 +-
 MAINTAINERS                                      | 16 ++++++++--------
 7 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt
index 8b2a71395647..3e64075ac7ec 100644
--- a/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt
+++ b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt
@@ -37,7 +37,7 @@ Optional nodes:
    supports a single port with a single endpoint.
 
  - See also Documentation/devicetree/bindings/display/tilcdc/panel.txt and
-   Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt for connecting
+   Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml for connecting
    tfp410 DVI encoder or lcd panel to lcdc
 
 [1] There is an errata about AM335x color wiring. For 16-bit color mode
diff --git a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt
index 35c3f56b7f7b..5fe80c1c19fc 100644
--- a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt
+++ b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt
@@ -69,7 +69,7 @@ The following are mandatory properties for the K3 AM65x and J721E SoCs only:
 			the interrupt routes between the IP and the main GIC
 			controllers. See the following binding for additional
 			details,
-			Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt
+			Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml
 
 Child Nodes:
 ============
diff --git a/Documentation/devicetree/bindings/media/i2c/tvp5150.txt b/Documentation/devicetree/bindings/media/i2c/tvp5150.txt
index 6c88ce858d08..719b2995dc17 100644
--- a/Documentation/devicetree/bindings/media/i2c/tvp5150.txt
+++ b/Documentation/devicetree/bindings/media/i2c/tvp5150.txt
@@ -56,7 +56,7 @@ Optional Connector Properties:
                   instead of using the autodetection mechnism. Please look at
                   [1] for more information.
 
-[1] Documentation/devicetree/bindings/display/connector/analog-tv-connector.txt.
+[1] Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml.
 
 Example - three input sources:
 #include <dt-bindings/display/sdtv-standards.h>
diff --git a/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml b/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml
index 41ece1d85315..4cfbffd8414a 100644
--- a/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml
+++ b/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml
@@ -14,7 +14,7 @@ description: |
   Google's ChromeOS EC PWM is a simple PWM attached to the Embedded Controller
   (EC) and controlled via a host-command interface.
   An EC PWM node should be only found as a sub-node of the EC node (see
-  Documentation/devicetree/bindings/mfd/cros-ec.txt).
+  Documentation/devicetree/bindings/mfd/google,cros-ec.yaml).
 
 properties:
   compatible:
diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml
index 468d658ce3e7..2684f22a1d85 100644
--- a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml
+++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml
@@ -20,7 +20,7 @@ description: |
   present and this subnode may contain children that designate regulator
   resources.
 
-  Refer to Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt
+  Refer to Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml
   for information on the regulator subnodes that can exist under the
   rpm_requests.
 
diff --git a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml
index c84e656afb0a..3b9143af2c7c 100644
--- a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml
+++ b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml
@@ -13,7 +13,7 @@ description: |
   Google's ChromeOS EC codec is a digital mic codec provided by the
   Embedded Controller (EC) and is controlled via a host-command interface.
   An EC codec node should only be found as a sub-node of the EC node (see
-  Documentation/devicetree/bindings/mfd/cros-ec.txt).
+  Documentation/devicetree/bindings/mfd/google,cros-ec.yaml).
 
 properties:
   compatible:
diff --git a/MAINTAINERS b/MAINTAINERS
index dffa948a2124..9e0f7b68bba5 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1523,7 +1523,7 @@ L:	linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
 S:	Maintained
 F:	Documentation/devicetree/bindings/arm/actions.yaml
 F:	Documentation/devicetree/bindings/clock/actions,owl-cmu.txt
-F:	Documentation/devicetree/bindings/dma/owl-dma.txt
+F:	Documentation/devicetree/bindings/dma/owl-dma.yaml
 F:	Documentation/devicetree/bindings/i2c/i2c-owl.txt
 F:	Documentation/devicetree/bindings/mmc/owl-mmc.yaml
 F:	Documentation/devicetree/bindings/pinctrl/actions,s900-pinctrl.txt
@@ -5827,7 +5827,7 @@ L:	linux-renesas-soc@vger.kernel.org
 S:	Supported
 T:	git git://linuxtv.org/pinchartl/media drm/du/next
 F:	Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt
-F:	Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt
+F:	Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml
 F:	Documentation/devicetree/bindings/display/renesas,du.txt
 F:	drivers/gpu/drm/rcar-du/
 F:	drivers/gpu/drm/shmobile/
@@ -6952,7 +6952,7 @@ M:	Frank Li <Frank.li@nxp.com>
 L:	linux-arm-kernel@lists.infradead.org
 S:	Maintained
 F:	Documentation/admin-guide/perf/imx-ddr.rst
-F:	Documentation/devicetree/bindings/perf/fsl-imx-ddr.txt
+F:	Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml
 F:	drivers/perf/fsl_imx8_ddr_perf.c
 
 FREESCALE IMX I2C DRIVER
@@ -6960,7 +6960,7 @@ M:	Oleksij Rempel <o.rempel@pengutronix.de>
 R:	Pengutronix Kernel Team <kernel@pengutronix.de>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/devicetree/bindings/i2c/i2c-imx.txt
+F:	Documentation/devicetree/bindings/i2c/i2c-imx.yaml
 F:	drivers/i2c/busses/i2c-imx.c
 
 FREESCALE IMX LPI2C DRIVER
@@ -6968,7 +6968,7 @@ M:	Dong Aisheng <aisheng.dong@nxp.com>
 L:	linux-i2c@vger.kernel.org
 L:	linux-imx@nxp.com
 S:	Maintained
-F:	Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt
+F:	Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml
 F:	drivers/i2c/busses/i2c-imx-lpi2c.c
 
 FREESCALE QORIQ DPAA ETHERNET DRIVER
@@ -11600,7 +11600,7 @@ MIPS GENERIC PLATFORM
 M:	Paul Burton <paulburton@kernel.org>
 L:	linux-mips@vger.kernel.org
 S:	Supported
-F:	Documentation/devicetree/bindings/power/mti,mips-cpc.txt
+F:	Documentation/devicetree/bindings/power/mti,mips-cpc.yaml
 F:	arch/mips/generic/
 F:	arch/mips/tools/generic-board-config.sh
 
@@ -12455,7 +12455,7 @@ NXP SGTL5000 DRIVER
 M:	Fabio Estevam <festevam@gmail.com>
 L:	alsa-devel@alsa-project.org (moderated for non-subscribers)
 S:	Maintained
-F:	Documentation/devicetree/bindings/sound/sgtl5000.txt
+F:	Documentation/devicetree/bindings/sound/sgtl5000.yaml
 F:	sound/soc/codecs/sgtl5000*
 
 NXP SJA1105 ETHERNET SWITCH DRIVER
@@ -16737,7 +16737,7 @@ SYNOPSYS DESIGNWARE DMAC DRIVER
 M:	Viresh Kumar <vireshk@kernel.org>
 R:	Andy Shevchenko <andriy.shevchenko@linux.intel.com>
 S:	Maintained
-F:	Documentation/devicetree/bindings/dma/snps-dma.txt
+F:	Documentation/devicetree/bindings/dma/snps,dma-spear1340.yaml
 F:	drivers/dma/dw/
 F:	include/dt-bindings/dma/dw-dmac.h
 F:	include/linux/dma/dw.h
-- 
2.26.2

[PATCH v6 57/80] net: appletalk: Kconfig: Fix docs location

[Mauro Carvalho Chehab]

The location of ltpc.rst changed. Update it at Kconfig.

Fixes: 4daedf7abb41 ("docs: networking: move AppleTalk / LocalTalk drivers to the hw driver section")

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/net/appletalk/Kconfig | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/net/appletalk/Kconfig b/drivers/net/appletalk/Kconfig
index d4f22a2e5be4..43918398f0d3 100644
--- a/drivers/net/appletalk/Kconfig
+++ b/drivers/net/appletalk/Kconfig
@@ -48,7 +48,7 @@ config LTPC
 	  If you are in doubt, this card is the one with the 65C02 chip on it.
 	  You also need version 1.3.3 or later of the netatalk package.
 	  This driver is experimental, which means that it may not work.
-	  See the file <file:Documentation/networking/ltpc.rst>.
+	  See the file <file:Documentation/networking/device_drivers/appletalk/ltpc.rst>.
 
 config COPS
 	tristate "COPS LocalTalk PC support"
-- 
2.26.2

[PATCH v6 58/80] drivers: net: hamradio: fix document location

[Mauro Carvalho Chehab]

The hamradio docs were moved to a different dir.
Update its location accordingly.

Fixes: 14474950252c ("docs: networking: move z8530 to the hw driver section")

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/net/hamradio/scc.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/net/hamradio/scc.c b/drivers/net/hamradio/scc.c
index 1e915871baa7..36eeb80406f2 100644
--- a/drivers/net/hamradio/scc.c
+++ b/drivers/net/hamradio/scc.c
@@ -7,7 +7,7 @@
  *            ------------------
  *
  * You can find a subset of the documentation in 
- * Documentation/networking/device_drivers/wan/z8530drv.rst.
+ * Documentation/networking/device_drivers/hamradio/z8530drv.rst.
  */
 
 /*
-- 
2.26.2

[PATCH v6 59/80] docs: powerpc: syscall64-abi.rst: fix a malformed table

[Mauro Carvalho Chehab]

As reported:

	Documentation/powerpc/syscall64-abi.rst:53: WARNING: Malformed table.
	Text in column margin in table line 2.

	=========== ============= ========================================
	--- For the sc instruction, differences with the ELF ABI ---
	r0          Volatile      (System call number.)

This table requires a different notation to be valid.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/powerpc/syscall64-abi.rst | 32 ++++++++++++-------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/Documentation/powerpc/syscall64-abi.rst b/Documentation/powerpc/syscall64-abi.rst
index 379817ca64d2..cf9b2857c72a 100644
--- a/Documentation/powerpc/syscall64-abi.rst
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -49,22 +49,22 @@ Register preservation rules
 Register preservation rules match the ELF ABI calling sequence with the
 following differences:
 
---- For the sc instruction, differences with the ELF ABI ---
-=========== ============= ========================================
-r0          Volatile      (System call number.)
-r3          Volatile      (Parameter 1, and return value.)
-r4-r8       Volatile      (Parameters 2-6.)
-cr0         Volatile      (cr0.SO is the return error condition.)
-cr1, cr5-7  Nonvolatile
-lr          Nonvolatile
-=========== ============= ========================================
-
---- For the scv 0 instruction, differences with the ELF ABI ---
-=========== ============= ========================================
-r0          Volatile      (System call number.)
-r3          Volatile      (Parameter 1, and return value.)
-r4-r8       Volatile      (Parameters 2-6.)
-=========== ============= ========================================
++------------------------------------------------------------------------+
+|        For the sc instruction, differences with the ELF ABI		 |
++--------------+--------------+------------------------------------------+
+| r0           | Volatile     | (System call number.)			 |
+| rr3          | Volatile     | (Parameter 1, and return value.)	 |
+| rr4-r8       | Volatile     | (Parameters 2-6.)			 |
+| rcr0         | Volatile     | (cr0.SO is the return error condition.)	 |
+| rcr1, cr5-7  | Nonvolatile  |						 |
+| rlr          | Nonvolatile  |						 |
++--------------+--------------+------------------------------------------+
+|      For the scv 0 instruction, differences with the ELF ABI		 |
++--------------+--------------+------------------------------------------+
+| r0           | Volatile     | (System call number.)			 |
+| r3           | Volatile     | (Parameter 1, and return value.)	 |
+| r4-r8        | Volatile     | (Parameters 2-6.)			 |
++--------------+--------------+------------------------------------------+
 
 All floating point and vector data registers as well as control and status
 registers are nonvolatile.
-- 
2.26.2

[PATCH v6 60/80] block: bio: fix a warning at the kernel-doc markups

[Mauro Carvalho Chehab]

Using "@bio's parent" causes the following waring:
	./block/bio.c:10: WARNING: Inline emphasis start-string without end-string.

The main problem here is that this would be converted into:

	**bio**'s parent

By kernel-doc, which is not a valid notation. It would be
possible to use, instead, this kernel-doc markup:

	``bio's`` parent

Yet, here, is probably simpler to just use an altenative language:

	the parent of @bio

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 block/bio.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/block/bio.c b/block/bio.c
index e865ea55b9f9..cee87a9ff799 100644
--- a/block/bio.c
+++ b/block/bio.c
@@ -327,7 +327,7 @@ static void bio_chain_endio(struct bio *bio)
 /**
  * bio_chain - chain bio completions
  * @bio: the target bio
- * @parent: the @bio's parent bio
+ * @parent: the parent bio of @bio
  *
  * The caller won't have a bi_end_io called when @bio completes - instead,
  * @parent's bi_end_io won't be called until both @parent and @bio have
-- 
2.26.2

[PATCH v6 61/80] kunit: test.h: solve kernel-doc warnings

[Mauro Carvalho Chehab]

There are some warnings there:
	./include/kunit/test.h:90: warning: Function parameter or member 'name' not described in 'kunit_resource'
	./include/kunit/test.h:353: warning: Function parameter or member 'res' not described in 'kunit_add_resource'
	./include/kunit/test.h:367: warning: Function parameter or member 'res' not described in 'kunit_add_named_resource'
	./include/kunit/test.h:367: warning: Function parameter or member 'name' not described in 'kunit_add_named_resource'
	./include/kunit/test.h:367: warning: Function parameter or member 'data' not described in 'kunit_add_named_resource'
	./include/kunit/test.h:367: warning: Excess function parameter 'name_data' description in 'kunit_add_named_resource'

Address them, ensuring that all non-private arguments will
be properly described. With that regards, at struct kunit_resource,
the free argument is described as user-provided. So, this
doesn't seem to belong to the "private" part of the struct.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/kunit/test.h | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/include/kunit/test.h b/include/kunit/test.h
index 59f3144f009a..41b3a266bf8c 100644
--- a/include/kunit/test.h
+++ b/include/kunit/test.h
@@ -25,6 +25,7 @@ typedef void (*kunit_resource_free_t)(struct kunit_resource *);
 /**
  * struct kunit_resource - represents a *test managed resource*
  * @data: for the user to store arbitrary data.
+ * @name: optional name
  * @free: a user supplied function to free the resource. Populated by
  * kunit_resource_alloc().
  *
@@ -80,10 +81,10 @@ typedef void (*kunit_resource_free_t)(struct kunit_resource *);
  */
 struct kunit_resource {
 	void *data;
-	const char *name;		/* optional name */
-
-	/* private: internal use only. */
+	const char *name;
 	kunit_resource_free_t free;
+
+	/* private: internal use only. */
 	struct kref refcount;
 	struct list_head node;
 };
@@ -343,6 +344,7 @@ static inline void kunit_put_resource(struct kunit_resource *res)
  *        none is supplied, the resource data value is simply set to @data.
  *	  If an init function is supplied, @data is passed to it instead.
  * @free: a user-supplied function to free the resource (if needed).
+ * @res: The resource.
  * @data: value to pass to init function or set in resource data field.
  */
 int kunit_add_resource(struct kunit *test,
@@ -356,7 +358,9 @@ int kunit_add_resource(struct kunit *test,
  * @test: The test context object.
  * @init: a user-supplied function to initialize the resource data, if needed.
  * @free: a user-supplied function to free the resource data, if needed.
- * @name_data: name and data to be set for resource.
+ * @res: The resource.
+ * @name: name to be set for resource.
+ * @data: value to pass to init function or set in resource data field.
  */
 int kunit_add_named_resource(struct kunit *test,
 			     kunit_resource_init_t init,
-- 
2.26.2

[PATCH v6 62/80] docs: bio: fix a kerneldoc markup

[Mauro Carvalho Chehab]

Fix this warning:

	./block/bio.c:1098: WARNING: Inline emphasis start-string without end-string.

The thing is that *iter is not a valid markup.

That seems to be a typo:
	*iter -> @iter

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 block/bio.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/block/bio.c b/block/bio.c
index cee87a9ff799..8dcb508b651c 100644
--- a/block/bio.c
+++ b/block/bio.c
@@ -1095,7 +1095,7 @@ static int __bio_iov_append_get_pages(struct bio *bio, struct iov_iter *iter)
  * released.
  *
  * The function tries, but does not guarantee, to pin as many pages as
- * fit into the bio, or are requested in *iter, whatever is smaller. If
+ * fit into the bio, or are requested in @iter, whatever is smaller. If
  * MM encounters an error pinning the requested pages, it stops. Error
  * is returned only if 0 pages could be pinned.
  */
-- 
2.26.2

[PATCH v6 63/80] drivers: core: fix kernel-doc markup for dev_err_probe()

[Mauro Carvalho Chehab]

There are two literal blocks there. Fix the markups, in order
to produce the right html output and solve those warnings:

	./drivers/base/core.c:4218: WARNING: Unexpected indentation.
	./drivers/base/core.c:4222: WARNING: Definition list ends without a blank line; unexpected unindent.
	./drivers/base/core.c:4223: WARNING: Block quote ends without a blank line; unexpected unindent.

Fixes: a787e5400a1c ("driver core: add device probe log helper")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/base/core.c | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/drivers/base/core.c b/drivers/base/core.c
index bb5806a2bd4c..eb5cb88bf194 100644
--- a/drivers/base/core.c
+++ b/drivers/base/core.c
@@ -4211,13 +4211,16 @@ define_dev_printk_level(_dev_info, KERN_INFO);
  * -EPROBE_DEFER and propagate error upwards.
  * In case of -EPROBE_DEFER it sets also defer probe reason, which can be
  * checked later by reading devices_deferred debugfs attribute.
- * It replaces code sequence:
+ * It replaces code sequence::
+ *
  * 	if (err != -EPROBE_DEFER)
  * 		dev_err(dev, ...);
  * 	else
  * 		dev_dbg(dev, ...);
  * 	return err;
- * with
+ *
+ * with::
+ *
  * 	return dev_err_probe(dev, err, ...);
  *
  * Returns @err.
-- 
2.26.2

[PATCH v6 64/80] kunit: test.h: fix a bad kernel-doc markup

[Mauro Carvalho Chehab]

As warned by:

	./include/kunit/test.h:504: WARNING: Block quote ends without a blank line; unexpected unindent.

The right way to describe a function is:

	name - description

Instead, kunit_remove_resource was using:

	name: description

Causing it to be improperly parsed.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/kunit/test.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/kunit/test.h b/include/kunit/test.h
index 41b3a266bf8c..5c5ed262a950 100644
--- a/include/kunit/test.h
+++ b/include/kunit/test.h
@@ -498,8 +498,8 @@ static inline int kunit_destroy_named_resource(struct kunit *test,
 }
 
 /**
- * kunit_remove_resource: remove resource from resource list associated with
- *			  test.
+ * kunit_remove_resource() - remove resource from resource list associated with
+ *			     test.
  * @test: The test context object.
  * @res: The resource to be removed.
  *
-- 
2.26.2

[PATCH v6 65/80] docs: amdgpu: fix a warning when building the documentation

[Mauro Carvalho Chehab]

As reported by Sphinx:

	Documentation/gpu/amdgpu.rst:200: WARNING: Inline emphasis start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/gpu/amdgpu.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst
index 17112352f605..4ed8ecf1cd86 100644
--- a/Documentation/gpu/amdgpu.rst
+++ b/Documentation/gpu/amdgpu.rst
@@ -197,8 +197,8 @@ pp_power_profile_mode
 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
    :doc: pp_power_profile_mode
 
-*_busy_percent
-~~~~~~~~~~~~~~
+\*_busy_percent
+~~~~~~~~~~~~~~~
 
 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
    :doc: gpu_busy_percent
-- 
2.26.2

[PATCH v6 66/80] locking/refcount: document the new "oldp" pointer value

[Mauro Carvalho Chehab]

Changeset a435b9a14356 ("locking/refcount: Provide __refcount API to obtain the old value")
added a new parameter to most refcount functions, but didn't update
the kernel-doc markups.

Add a description for it on all touched functions.

Fixes: a435b9a14356 ("locking/refcount: Provide __refcount API to obtain the old value")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/refcount.h | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/include/linux/refcount.h b/include/linux/refcount.h
index 0e3ee25eb156..24c343bed889 100644
--- a/include/linux/refcount.h
+++ b/include/linux/refcount.h
@@ -151,6 +151,7 @@ static inline unsigned int refcount_read(const refcount_t *r)
  * refcount_add_not_zero - add a value to a refcount unless it is 0
  * @i: the value to add to the refcount
  * @r: the refcount
+ * @oldp: if not NULL, stores the previous value of the refcount
  *
  * Will saturate at REFCOUNT_SATURATED and WARN.
  *
@@ -184,6 +185,7 @@ static inline __must_check bool refcount_add_not_zero(int i, refcount_t *r)
  * refcount_add - add a value to a refcount
  * @i: the value to add to the refcount
  * @r: the refcount
+ * @oldp: if not NULL, stores the previous value of the refcount
  *
  * Similar to atomic_add(), but will saturate at REFCOUNT_SATURATED and WARN.
  *
@@ -209,6 +211,7 @@ static inline void refcount_add(int i, refcount_t *r)
 /**
  * refcount_inc_not_zero - increment a refcount unless it is 0
  * @r: the refcount to increment
+ * @oldp: if not NULL, stores the previous value of the refcount
  *
  * Similar to atomic_inc_not_zero(), but will saturate at REFCOUNT_SATURATED
  * and WARN.
@@ -227,6 +230,7 @@ static inline __must_check bool refcount_inc_not_zero(refcount_t *r)
 /**
  * refcount_inc - increment a refcount
  * @r: the refcount to increment
+ * @oldp: if not NULL, stores the previous value of the refcount
  *
  * Similar to atomic_inc(), but will saturate at REFCOUNT_SATURATED and WARN.
  *
@@ -245,6 +249,7 @@ static inline void refcount_inc(refcount_t *r)
  * refcount_sub_and_test - subtract from a refcount and test if it is 0
  * @i: amount to subtract from the refcount
  * @r: the refcount
+ * @oldp: if not NULL, stores the previous value of the refcount
  *
  * Similar to atomic_dec_and_test(), but it will WARN, return false and
  * ultimately leak on underflow and will fail to decrement when saturated
@@ -279,6 +284,7 @@ static inline __must_check bool refcount_sub_and_test(int i, refcount_t *r)
 /**
  * refcount_dec_and_test - decrement a refcount and test if it is 0
  * @r: the refcount
+ * @oldp: if not NULL, stores the previous value of the refcount
  *
  * Similar to atomic_dec_and_test(), it will WARN on underflow and fail to
  * decrement when saturated at REFCOUNT_SATURATED.
@@ -297,6 +303,7 @@ static inline __must_check bool refcount_dec_and_test(refcount_t *r)
 /**
  * refcount_dec - decrement a refcount
  * @r: the refcount
+ * @oldp: if not NULL, stores the previous value of the refcount
  *
  * Similar to atomic_dec(), it will WARN on underflow and fail to decrement
  * when saturated at REFCOUNT_SATURATED.
-- 
2.26.2

[PATCH v6 67/80] usb: docs: document altmode register/unregister functions

[Mauro Carvalho Chehab]

The typec_bus.rst asks for documentation of those two
functions, but they don't exist:

	./drivers/usb/typec/bus.c:1: warning: 'typec_altmode_unregister_driver' not found
	./drivers/usb/typec/bus.c:1: warning: 'typec_altmode_register_driver' not found

Also, they're not declared on bus.c but, instead, at a header
file (typec_altmode.h).

So, add documentation for both functions at the header and
change the kernel-doc markup under typec_bus.rst to point
to the right place.

While here, also place the documentation for both structs
declared on typec_altmode.h at the rst file.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/usb/typec_bus.rst |  8 +++++++-
 include/linux/usb/typec_altmode.h          | 16 ++++++++++++++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/Documentation/driver-api/usb/typec_bus.rst b/Documentation/driver-api/usb/typec_bus.rst
index 03dfa9c018b7..21c890ae17e5 100644
--- a/Documentation/driver-api/usb/typec_bus.rst
+++ b/Documentation/driver-api/usb/typec_bus.rst
@@ -91,10 +91,16 @@ their control.
 Driver API
 ----------
 
+Alternate mode structs
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: include/linux/usb/typec_altmode.h
+   :functions: typec_altmode_driver typec_altmode_ops
+
 Alternate mode driver registering/unregistering
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. kernel-doc:: drivers/usb/typec/bus.c
+.. kernel-doc:: include/linux/usb/typec_altmode.h
    :functions: typec_altmode_register_driver typec_altmode_unregister_driver
 
 Alternate mode driver operations
diff --git a/include/linux/usb/typec_altmode.h b/include/linux/usb/typec_altmode.h
index a4b65eaa0f62..5e0a7b7647c3 100644
--- a/include/linux/usb/typec_altmode.h
+++ b/include/linux/usb/typec_altmode.h
@@ -152,10 +152,26 @@ struct typec_altmode_driver {
 #define to_altmode_driver(d) container_of(d, struct typec_altmode_driver, \
 					  driver)
 
+/**
+ * typec_altmode_register_driver - registers a USB Type-C alternate mode
+ * 				   device driver
+ * @drv: pointer to struct typec_altmode_driver
+ *
+ * These drivers will be bind to the partner alternate mode devices. They will
+ * handle all SVID specific communication.
+ */
 #define typec_altmode_register_driver(drv) \
 		__typec_altmode_register_driver(drv, THIS_MODULE)
 int __typec_altmode_register_driver(struct typec_altmode_driver *drv,
 				    struct module *module);
+/**
+ * typec_altmode_unregister_driver - unregisters a USB Type-C alternate mode
+ * 				     device driver
+ * @drv: pointer to struct typec_altmode_driver
+ *
+ * These drivers will be bind to the partner alternate mode devices. They will
+ * handle all SVID specific communication.
+ */
 void typec_altmode_unregister_driver(struct typec_altmode_driver *drv);
 
 #define module_typec_altmode_driver(__typec_altmode_driver) \
-- 
2.26.2

[PATCH v6 68/80] nl80211: docs: add a description for s1g_cap parameter

[Mauro Carvalho Chehab]

Changeset df78a0c0b67d ("nl80211: S1G band and channel definitions")
added a new parameter, but didn't add the corresponding kernel-doc
markup, as repoted when doing "make htmldocs":

	./include/net/cfg80211.h:471: warning: Function parameter or member 's1g_cap' not described in 'ieee80211_supported_band'

Add a documentation for it.

Fixes: df78a0c0b67d ("nl80211: S1G band and channel definitions")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/net/cfg80211.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index d9e6b9fbd95b..fb6aece00549 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -449,6 +449,7 @@ struct ieee80211_sta_s1g_cap {
  * @n_bitrates: Number of bitrates in @bitrates
  * @ht_cap: HT capabilities in this band
  * @vht_cap: VHT capabilities in this band
+ * @s1g_cap: S1G capabilities in this band
  * @edmg_cap: EDMG capabilities in this band
  * @n_iftype_data: number of iftype data entries
  * @iftype_data: interface type data entries.  Note that the bits in
-- 
2.26.2

[PATCH v6 69/80] IB/srpt: docs: add a description for cq_size member

[Mauro Carvalho Chehab]

Changeset c804af2c1d31 ("IB/srpt: use new shared CQ mechanism")
added a new member for struct srpt_rdma_ch, but didn't add the
corresponding kernel-doc markup, as repoted when doing
"make htmldocs":
	./drivers/infiniband/ulp/srpt/ib_srpt.h:331: warning: Function parameter or member 'cq_size' not described in 'srpt_rdma_ch'

Add a description for it.

Fixes: c804af2c1d31 ("IB/srpt: use new shared CQ mechanism")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/infiniband/ulp/srpt/ib_srpt.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/infiniband/ulp/srpt/ib_srpt.h b/drivers/infiniband/ulp/srpt/ib_srpt.h
index 41435a699b53..e5d6af14d073 100644
--- a/drivers/infiniband/ulp/srpt/ib_srpt.h
+++ b/drivers/infiniband/ulp/srpt/ib_srpt.h
@@ -256,6 +256,7 @@ enum rdma_ch_state {
  * @rdma_cm:	   See below.
  * @rdma_cm.cm_id: RDMA CM ID associated with the channel.
  * @cq:            IB completion queue for this channel.
+ * @cq_size:	   Size of the @cq pool.
  * @zw_cqe:	   Zero-length write CQE.
  * @rcu:           RCU head.
  * @kref:	   kref for this channel.
-- 
2.26.2

[PATCH v6 70/80] rcu/tree: docs: document bkvcache new members at struct kfree_rcu_cpu

[Mauro Carvalho Chehab]

Changeset 53c72b590b3a ("rcu/tree: cache specified number of objects")
added new members for struct kfree_rcu_cpu, but didn't add the
corresponding at the kernel-doc markup, as repoted when doing
"make htmldocs":
	./kernel/rcu/tree.c:3113: warning: Function parameter or member 'bkvcache' not described in 'kfree_rcu_cpu'
	./kernel/rcu/tree.c:3113: warning: Function parameter or member 'nr_bkv_objs' not described in 'kfree_rcu_cpu'

So, move the description for bkvcache to kernel-doc, and add a
description for nr_bkv_objs.

Fixes: 53c72b590b3a ("rcu/tree: cache specified number of objects")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 kernel/rcu/tree.c | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/kernel/rcu/tree.c b/kernel/rcu/tree.c
index f78ee759af9c..03c54c3478b7 100644
--- a/kernel/rcu/tree.c
+++ b/kernel/rcu/tree.c
@@ -3022,6 +3022,12 @@ struct kfree_rcu_cpu_work {
  * @monitor_todo: Tracks whether a @monitor_work delayed work is pending
  * @initialized: The @rcu_work fields have been initialized
  * @count: Number of objects for which GP not started
+ * @bkvcache:
+ *	A simple cache list that contains objects for reuse purpose.
+ *	In order to save some per-cpu space the list is singular.
+ *	Even though it is lockless an access has to be protected by the
+ *	per-cpu lock.
+ * @nr_bkv_objs: number of allocated objects at @bkvcache.
  *
  * This is a per-CPU structure.  The reason that it is not included in
  * the rcu_data structure is to permit this code to be extracted from
@@ -3037,14 +3043,6 @@ struct kfree_rcu_cpu {
 	bool monitor_todo;
 	bool initialized;
 	int count;
-
-	/*
-	 * A simple cache list that contains objects for
-	 * reuse purpose. In order to save some per-cpu
-	 * space the list is singular. Even though it is
-	 * lockless an access has to be protected by the
-	 * per-cpu lock.
-	 */
 	struct llist_head bkvcache;
 	int nr_bkv_objs;
 };
-- 
2.26.2

[PATCH v6 71/80] Input: sparse-keymap: add a description for @sw

[Mauro Carvalho Chehab]

Add a description for it, in order to avoids this warning:

	./include/linux/input/sparse-keymap.h:43: warning: Function parameter or member 'sw' not described in 'key_entry'

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/input/sparse-keymap.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/linux/input/sparse-keymap.h b/include/linux/input/sparse-keymap.h
index d25d1452dc6e..d0dddc14ebc8 100644
--- a/include/linux/input/sparse-keymap.h
+++ b/include/linux/input/sparse-keymap.h
@@ -20,6 +20,7 @@
  *	private definitions.
  * @code: Device-specific data identifying the button/switch
  * @keycode: KEY_* code assigned to a key/button
+ * @sw: struct with code/value used by KE_SW and KE_VSW
  * @sw.code: SW_* code assigned to a switch
  * @sw.value: Value that should be sent in an input even when KE_SW
  *	switch is toggled. KE_VSW switches ignore this field and
-- 
2.26.2

[PATCH v6 72/80] drm/amd/display: kernel-doc: document force_timing_sync

[Mauro Carvalho Chehab]

As warned when running "make htmldocs":

	./drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:345: warning: Function parameter or member 'force_timing_sync' not described in 'amdgpu_display_manager'

This new struct member was not documented at kernel-doc markup.

Fixes: 3d4e52d0cf24 ("drm/amd/display: Add debugfs for forcing stream timing sync")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
index dd1559c743c2..fc7e3e9fd719 100644
--- a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
+++ b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
@@ -149,6 +149,8 @@ struct amdgpu_dm_backlight_caps {
  * @cached_state: Caches device atomic state for suspend/resume
  * @cached_dc_state: Cached state of content streams
  * @compressor: Frame buffer compression buffer. See &struct dm_comressor_info
+ * @force_timing_sync: set via debugfs. When set, indicates that all connected
+ *		       displays will be forced to synchronize.
  */
 struct amdgpu_display_manager {
 
-- 
2.26.2

[PATCH v6 73/80] drm: kernel-doc: drm_dp_helper.h: fix a typo

[Mauro Carvalho Chehab]

Right now, kernel-doc generates a warning:
	./include/drm/drm_dp_helper.h:1786: warning: Function parameter or member 'hbr2_reset' not described in 'drm_dp_phy_test_params'

This is due to a typo:

	@hb2_reset -> @hbr2_reset

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/drm/drm_dp_helper.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/drm/drm_dp_helper.h b/include/drm/drm_dp_helper.h
index e47dc22ebf50..69f7863ee99a 100644
--- a/include/drm/drm_dp_helper.h
+++ b/include/drm/drm_dp_helper.h
@@ -1760,7 +1760,7 @@ static inline void drm_dp_cec_unset_edid(struct drm_dp_aux *aux)
  * @link_rate: Requested Link rate from DPCD 0x219
  * @num_lanes: Number of lanes requested by sing through DPCD 0x220
  * @phy_pattern: DP Phy test pattern from DPCD 0x248
- * @hb2_reset: DP HBR2_COMPLIANCE_SCRAMBLER_RESET from DCPD 0x24A and 0x24B
+ * @hbr2_reset: DP HBR2_COMPLIANCE_SCRAMBLER_RESET from DCPD 0x24A and 0x24B
  * @custom80: DP Test_80BIT_CUSTOM_PATTERN from DPCDs 0x250 through 0x259
  * @enhanced_frame_cap: flag for enhanced frame capability.
  */
-- 
2.26.2

[PATCH v6 74/80] gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markups

[Mauro Carvalho Chehab]

As reported by kernel-doc:
    ./drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c:1: warning: no structured comments found
    ./drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c:1: warning: no structured comments found

Those files only contain

	/**
	 * DOC:
	 */

markups, but they're included twice there: one to parse
such markup, and another one to parse internal functions.

In the case of amdgpu_xgmi.c, as it has just one such
markup, we can simply include the file once, and let it
parse the entire file without passing arguments to kernel-doc.

This should place everything altogether.

For amdgpu_ras.c, however, we need to remove the kernel-doc
with just internal. This should be re-introduced if this
file ever gets new non-DOC markups.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/gpu/amdgpu.rst | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst
index 4ed8ecf1cd86..aba8df189a74 100644
--- a/Documentation/gpu/amdgpu.rst
+++ b/Documentation/gpu/amdgpu.rst
@@ -74,10 +74,6 @@ AMDGPU XGMI Support
 ===================
 
 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c
-   :doc: AMDGPU XGMI Support
-
-.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c
-   :internal:
 
 AMDGPU RAS Support
 ==================
@@ -115,9 +111,6 @@ RAS VRAM Bad Pages sysfs Interface
 .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c
    :doc: AMDGPU RAS sysfs gpu_vram_bad_pages Interface
 
-.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c
-   :internal:
-
 Sample Code
 -----------
 Sample code for testing error injection can be found here:
-- 
2.26.2

[PATCH v6 75/80] drm: kernel-doc: add description for a new function parameter

[Mauro Carvalho Chehab]

As reported by "make htmldocs":

	./drivers/gpu/drm/drm_prime.c:808: warning: Function parameter or member 'dev' not described in 'drm_prime_pages_to_sg'

Add a description for the new parameter.

Fixes: 707d561f77b5 ("drm: allow limiting the scatter list size.")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/drm_prime.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/gpu/drm/drm_prime.c b/drivers/gpu/drm/drm_prime.c
index 1693aa7c14b5..1395688930f8 100644
--- a/drivers/gpu/drm/drm_prime.c
+++ b/drivers/gpu/drm/drm_prime.c
@@ -793,6 +793,7 @@ static const struct dma_buf_ops drm_gem_prime_dmabuf_ops =  {
 
 /**
  * drm_prime_pages_to_sg - converts a page array into an sg list
+ * @dev: DRM device
  * @pages: pointer to the array of page pointers to convert
  * @nr_pages: length of the page vector
  *
-- 
2.26.2

[PATCH v6 76/80] docs: virt: user_mode_linux_howto_v2.rst: fix a literal block markup

[Mauro Carvalho Chehab]

There's a missing new line for a literal block:

	.../Documentation/virt/uml/user_mode_linux_howto_v2.rst:682: WARNING: Unexpected indentation.

Fixes: 04301bf5b072 ("docs: replace the old User Mode Linux HowTo with a new one")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/virt/uml/user_mode_linux_howto_v2.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/virt/uml/user_mode_linux_howto_v2.rst b/Documentation/virt/uml/user_mode_linux_howto_v2.rst
index f70e6f5873c6..312e431695d9 100644
--- a/Documentation/virt/uml/user_mode_linux_howto_v2.rst
+++ b/Documentation/virt/uml/user_mode_linux_howto_v2.rst
@@ -679,6 +679,7 @@ Starting UML
 
 We can now run UML.
 ::
+
    # linux mem=2048M umid=TEST \
     ubd0=Filesystem.img \
     vec0:transport=tap,ifname=tap0,depth=128,gro=1 \
-- 
2.26.2

[PATCH v6 77/80] workqueue: fix a kernel-doc warning

[Mauro Carvalho Chehab]

As warned by Sphinx:

	./Documentation/core-api/workqueue:400: ./kernel/workqueue.c:1218: WARNING: Unexpected indentation.

the return code table is currently not recognized, as it lacks
markups.

Acked-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 kernel/workqueue.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/kernel/workqueue.c b/kernel/workqueue.c
index c41c3c17b86a..e07d37396dfe 100644
--- a/kernel/workqueue.c
+++ b/kernel/workqueue.c
@@ -1212,11 +1212,14 @@ static void pwq_dec_nr_in_flight(struct pool_workqueue *pwq, int color)
  * stable state - idle, on timer or on worklist.
  *
  * Return:
+ *
+ *  ========	================================================================
  *  1		if @work was pending and we successfully stole PENDING
  *  0		if @work was idle and we claimed PENDING
  *  -EAGAIN	if PENDING couldn't be grabbed at the moment, safe to busy-retry
  *  -ENOENT	if someone else is canceling @work, this state may persist
  *		for arbitrarily long
+ *  ========	================================================================
  *
  * Note:
  * On >= 0 return, the caller owns @work's PENDING bit.  To avoid getting
-- 
2.26.2

[PATCH v6 78/80] mm/doc: fix a literal block markup

[Mauro Carvalho Chehab]

Literal blocks with :: markup should be indented, as otherwise
Sphinx complains:

	Documentation/vm/hmm.rst:363: WARNING: Literal block expected; none found.

Fixes: f7ebd9ed7767 ("mm/doc: add usage description for migrate_vma_*()")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/vm/hmm.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/vm/hmm.rst b/Documentation/vm/hmm.rst
index dd9f76a4ef29..09e28507f5b2 100644
--- a/Documentation/vm/hmm.rst
+++ b/Documentation/vm/hmm.rst
@@ -360,7 +360,7 @@ between device driver specific code and shared common code:
    system memory page, locks the page with ``lock_page()``, and fills in the
    ``dst`` array entry with::
 
-   dst[i] = migrate_pfn(page_to_pfn(dpage)) | MIGRATE_PFN_LOCKED;
+     dst[i] = migrate_pfn(page_to_pfn(dpage)) | MIGRATE_PFN_LOCKED;
 
    Now that the driver knows that this page is being migrated, it can
    invalidate device private MMU mappings and copy device private memory
-- 
2.26.2

[PATCH v6 79/80] drm: drm_edid: remove a duplicated kernel-doc declaration

[Mauro Carvalho Chehab]

It is not possible to create cross-references for duplicated
symbols. While Sphinx always detected it, on Sphinx 3 it
generates warnings like this:

	.../Documentation/gpu/drm-kms-helpers:326: ../drivers/gpu/drm/drm_edid.c:1626: WARNING: Duplicate C declaration, also defined in 'gpu/drm-kms-helpers'.
	Declaration is 'bool drm_edid_are_equal (const struct edid *edid1, const struct edid *edid2)'.

So, get rid of the duplicated kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/drm/drm_edid.h | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/include/drm/drm_edid.h b/include/drm/drm_edid.h
index cfa4f5af49af..6586c9104ec1 100644
--- a/include/drm/drm_edid.h
+++ b/include/drm/drm_edid.h
@@ -359,13 +359,6 @@ drm_load_edid_firmware(struct drm_connector *connector)
 }
 #endif
 
-/**
- * drm_edid_are_equal - compare two edid blobs.
- * @edid1: pointer to first blob
- * @edid2: pointer to second blob
- * This helper can be used during probing to determine if
- * edid had changed.
- */
 bool drm_edid_are_equal(const struct edid *edid1, const struct edid *edid2);
 
 int
-- 
2.26.2

[PATCH v6 80/80] PM / devfreq: remove a duplicated kernel-doc markup

[Mauro Carvalho Chehab]

The update_devfreq() is also documented at devfreq.c, which
has a more complete note.

So, drop the duplicated markup, in order to avoid this
warning:
	.../Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
	Declaration is 'device_link_state'.

(and to cause a problem with cross-references to it)

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/devfreq.h | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/include/linux/devfreq.h b/include/linux/devfreq.h
index 12782fbb4c25..1fbd3a5e97f9 100644
--- a/include/linux/devfreq.h
+++ b/include/linux/devfreq.h
@@ -228,12 +228,7 @@ int devfreq_resume_device(struct devfreq *devfreq);
 void devfreq_suspend(void);
 void devfreq_resume(void);
 
-/**
- * update_devfreq() - Reevaluate the device and configure frequency
- * @devfreq:	the devfreq device
- *
- * Note: devfreq->lock must be held
- */
+/* update_devfreq() - Reevaluate the device and configure frequency */
 int update_devfreq(struct devfreq *devfreq);
 
 /* Helper functions for devfreq user device driver with OPP. */
-- 
2.26.2

Re: [PATCH v6 55/80] memblock: get rid of a :c:type leftover

[Mike Rapoport]

On Tue, Oct 13, 2020 at 01:54:10PM +0200, Mauro Carvalho Chehab wrote:
> chanseset b3a7bb1851c8 ("docs: get rid of :c:type explicit declarations for structs")
> removed several :c:type: markups, except by one.
> 
> Now, Sphinx 3.x complains about it:
> 
> 	.../Documentation/core-api/boot-time-mm:26: ../mm/memblock.c:51: WARNING: Unparseable C cross-reference: 'struct\nmemblock_type'
> 	Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
> 	  struct
> 	memblock_type
> 	  ------^
> 
> As, on Sphinx 3.x, the right markup is c:struct:`foo`.
> 
> So, let's remove it, relying on automarkup.py to convert it.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>

> ---
>  mm/memblock.c | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/mm/memblock.c b/mm/memblock.c
> index 670216826940..a06e68b1e5a0 100644
> --- a/mm/memblock.c
> +++ b/mm/memblock.c
> @@ -50,8 +50,8 @@
>   *
>   * Each region is represented by struct memblock_region that
>   * defines the region extents, its attributes and NUMA node id on NUMA
> - * systems. Every memory type is described by the :c:type:`struct
> - * memblock_type` which contains an array of memory regions along with
> + * systems. Every memory type is described by the struct memblock_type
> + * which contains an array of memory regions along with
>   * the allocator metadata. The "memory" and "reserved" types are nicely
>   * wrapped with struct memblock. This structure is statically
>   * initialized at build time. The region arrays are initially sized to
> -- 
> 2.26.2
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH v6 66/80] locking/refcount: document the new "oldp" pointer value

[Peter Zijlstra]

On Tue, Oct 13, 2020 at 01:54:21PM +0200, Mauro Carvalho Chehab wrote:
> Changeset a435b9a14356 ("locking/refcount: Provide __refcount API to obtain the old value")
> added a new parameter to most refcount functions, but didn't update
> the kernel-doc markups.

Mindless warning begets mindless patch :/ Please turn on brain while
operating the computer.

> Add a description for it on all touched functions.

It's actively wrong now, the function in the comment is the variant with
__ and they do not have the extra parameter.

> Fixes: a435b9a14356 ("locking/refcount: Provide __refcount API to obtain the old value")

Breaks actual sanity.

Re: [PATCH v6 72/80] drm/amd/display: kernel-doc: document force_timing_sync

[Alex Deucher]

Applied.  Thanks!

Alex

On Tue, Oct 13, 2020 at 7:54 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> As warned when running "make htmldocs":
>
>         ./drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:345: warning: Function parameter or member 'force_timing_sync' not described in 'amdgpu_display_manager'
>
> This new struct member was not documented at kernel-doc markup.
>
> Fixes: 3d4e52d0cf24 ("drm/amd/display: Add debugfs for forcing stream timing sync")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
> index dd1559c743c2..fc7e3e9fd719 100644
> --- a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
> +++ b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
> @@ -149,6 +149,8 @@ struct amdgpu_dm_backlight_caps {
>   * @cached_state: Caches device atomic state for suspend/resume
>   * @cached_dc_state: Cached state of content streams
>   * @compressor: Frame buffer compression buffer. See &struct dm_comressor_info
> + * @force_timing_sync: set via debugfs. When set, indicates that all connected
> + *                    displays will be forced to synchronize.
>   */
>  struct amdgpu_display_manager {
>
> --
> 2.26.2
>
> _______________________________________________
> amd-gfx mailing list
> amd-gfx@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/amd-gfx

Re: [PATCH v6 65/80] docs: amdgpu: fix a warning when building the documentation

[Alex Deucher]

Applied.  Thanks!

Alex

On Tue, Oct 13, 2020 at 7:54 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> As reported by Sphinx:
>
>         Documentation/gpu/amdgpu.rst:200: WARNING: Inline emphasis start-string without end-string.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/gpu/amdgpu.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst
> index 17112352f605..4ed8ecf1cd86 100644
> --- a/Documentation/gpu/amdgpu.rst
> +++ b/Documentation/gpu/amdgpu.rst
> @@ -197,8 +197,8 @@ pp_power_profile_mode
>  .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
>     :doc: pp_power_profile_mode
>
> -*_busy_percent
> -~~~~~~~~~~~~~~
> +\*_busy_percent
> +~~~~~~~~~~~~~~~
>
>  .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
>     :doc: gpu_busy_percent
> --
> 2.26.2
>
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v6 70/80] rcu/tree: docs: document bkvcache new members at struct kfree_rcu_cpu

[Paul E. McKenney]

On Tue, Oct 13, 2020 at 01:54:25PM +0200, Mauro Carvalho Chehab wrote:
> Changeset 53c72b590b3a ("rcu/tree: cache specified number of objects")
> added new members for struct kfree_rcu_cpu, but didn't add the
> corresponding at the kernel-doc markup, as repoted when doing
> "make htmldocs":
> 	./kernel/rcu/tree.c:3113: warning: Function parameter or member 'bkvcache' not described in 'kfree_rcu_cpu'
> 	./kernel/rcu/tree.c:3113: warning: Function parameter or member 'nr_bkv_objs' not described in 'kfree_rcu_cpu'
> 
> So, move the description for bkvcache to kernel-doc, and add a
> description for nr_bkv_objs.
> 
> Fixes: 53c72b590b3a ("rcu/tree: cache specified number of objects")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Queued for review and testing, likely target v5.11.

							Thanx, Paul

> ---
>  kernel/rcu/tree.c | 14 ++++++--------
>  1 file changed, 6 insertions(+), 8 deletions(-)
> 
> diff --git a/kernel/rcu/tree.c b/kernel/rcu/tree.c
> index f78ee759af9c..03c54c3478b7 100644
> --- a/kernel/rcu/tree.c
> +++ b/kernel/rcu/tree.c
> @@ -3022,6 +3022,12 @@ struct kfree_rcu_cpu_work {
>   * @monitor_todo: Tracks whether a @monitor_work delayed work is pending
>   * @initialized: The @rcu_work fields have been initialized
>   * @count: Number of objects for which GP not started
> + * @bkvcache:
> + *	A simple cache list that contains objects for reuse purpose.
> + *	In order to save some per-cpu space the list is singular.
> + *	Even though it is lockless an access has to be protected by the
> + *	per-cpu lock.
> + * @nr_bkv_objs: number of allocated objects at @bkvcache.
>   *
>   * This is a per-CPU structure.  The reason that it is not included in
>   * the rcu_data structure is to permit this code to be extracted from
> @@ -3037,14 +3043,6 @@ struct kfree_rcu_cpu {
>  	bool monitor_todo;
>  	bool initialized;
>  	int count;
> -
> -	/*
> -	 * A simple cache list that contains objects for
> -	 * reuse purpose. In order to save some per-cpu
> -	 * space the list is singular. Even though it is
> -	 * lockless an access has to be protected by the
> -	 * per-cpu lock.
> -	 */
>  	struct llist_head bkvcache;
>  	int nr_bkv_objs;
>  };
> -- 
> 2.26.2
> 

Re: [PATCH v6 68/80] nl80211: docs: add a description for s1g_cap parameter

[Thomas Pedersen]

On 2020-10-13 04:54, Mauro Carvalho Chehab wrote:
> Changeset df78a0c0b67d ("nl80211: S1G band and channel definitions")
> added a new parameter, but didn't add the corresponding kernel-doc
> markup, as repoted when doing "make htmldocs":
> 
> 	./include/net/cfg80211.h:471: warning: Function parameter or member
> 's1g_cap' not described in 'ieee80211_supported_band'
> 
> Add a documentation for it.

Sorry about that. Patch looks good.

> Fixes: df78a0c0b67d ("nl80211: S1G band and channel definitions")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Signed-off-by: Thomas Pedersen <thomas@adapt-ip.com>

-- 
thomas

Re: [PATCH v6 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags

[Eric Biggers]

On Tue, Oct 13, 2020 at 01:53:50PM +0200, Mauro Carvalho Chehab wrote:
> The :c:type: tag has problems with Sphinx 3.x, as structs
> there should be declared with c:struct.
> 
> So, remove them, relying at automarkup.py extension to
> convert them into cross-references.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

I left some comments on v5 which weren't addressed.

- Eric

Re: [PATCH v6 68/80] nl80211: docs: add a description for s1g_cap parameter

[Johannes Berg]

Thanks Mauro.


On Tue, 2020-10-13 at 13:54 +0200, Mauro Carvalho Chehab wrote:
> Changeset df78a0c0b67d ("nl80211: S1G band and channel definitions")
> added a new parameter, but didn't add the corresponding kernel-doc
> markup, as repoted when doing "make htmldocs":
> 
> 	./include/net/cfg80211.h:471: warning: Function parameter or member 's1g_cap' not described in 'ieee80211_supported_band'
> 
> Add a documentation for it.

Should I take this through my tree, or is that part of a larger set
that'll go somewhere else?

johannes

Re: [PATCH v6 68/80] nl80211: docs: add a description for s1g_cap parameter

[Mauro Carvalho Chehab]

Em Tue, 13 Oct 2020 20:47:47 +0200
Johannes Berg <johannes@sipsolutions.net> escreveu:

> Thanks Mauro.
> 
> 
> On Tue, 2020-10-13 at 13:54 +0200, Mauro Carvalho Chehab wrote:
> > Changeset df78a0c0b67d ("nl80211: S1G band and channel definitions")
> > added a new parameter, but didn't add the corresponding kernel-doc
> > markup, as repoted when doing "make htmldocs":
> > 
> > 	./include/net/cfg80211.h:471: warning: Function parameter or member 's1g_cap' not described in 'ieee80211_supported_band'
> > 
> > Add a documentation for it.  
> 
> Should I take this through my tree, or is that part of a larger set
> that'll go somewhere else?

Whatever works best for you ;-)

If you don't pick it via your tree, I'm planning to send it
together with the other patches likely on Thursday.


Thanks,
Mauro

Re: [PATCH v6 68/80] nl80211: docs: add a description for s1g_cap parameter

[Johannes Berg]

On Tue, 2020-10-13 at 22:41 +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 13 Oct 2020 20:47:47 +0200
> Johannes Berg <johannes@sipsolutions.net> escreveu:
> 
> > Thanks Mauro.
> > 
> > 
> > On Tue, 2020-10-13 at 13:54 +0200, Mauro Carvalho Chehab wrote:
> > > Changeset df78a0c0b67d ("nl80211: S1G band and channel definitions")
> > > added a new parameter, but didn't add the corresponding kernel-doc
> > > markup, as repoted when doing "make htmldocs":
> > > 
> > > 	./include/net/cfg80211.h:471: warning: Function parameter or member 's1g_cap' not described in 'ieee80211_supported_band'
> > > 
> > > Add a documentation for it.  
> > 
> > Should I take this through my tree, or is that part of a larger set
> > that'll go somewhere else?
> 
> Whatever works best for you ;-)
> 
> If you don't pick it via your tree, I'm planning to send it
> together with the other patches likely on Thursday.

OK, please do, and here's an

Acked-by: Johannes Berg <johannes@sipsolutions.net>


I don't think I can get it this quickly through net-next at this point,
and there's just no point if you have stuff to send anyway :-)

Thanks!

johannes

Re: [PATCH v6 70/80] rcu/tree: docs: document bkvcache new members at struct kfree_rcu_cpu

[Mauro Carvalho Chehab]

Em Tue, 13 Oct 2020 09:34:04 -0700
"Paul E. McKenney" <paulmck@kernel.org> escreveu:

> On Tue, Oct 13, 2020 at 01:54:25PM +0200, Mauro Carvalho Chehab wrote:
> > Changeset 53c72b590b3a ("rcu/tree: cache specified number of objects")
> > added new members for struct kfree_rcu_cpu, but didn't add the
> > corresponding at the kernel-doc markup, as repoted when doing
> > "make htmldocs":
> > 	./kernel/rcu/tree.c:3113: warning: Function parameter or member 'bkvcache' not described in 'kfree_rcu_cpu'
> > 	./kernel/rcu/tree.c:3113: warning: Function parameter or member 'nr_bkv_objs' not described in 'kfree_rcu_cpu'
> > 
> > So, move the description for bkvcache to kernel-doc, and add a
> > description for nr_bkv_objs.
> > 
> > Fixes: 53c72b590b3a ("rcu/tree: cache specified number of objects")
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> 
> Queued for review and testing, likely target v5.11.

Hi Paul,

I would prefer if we could get those on 5.10, if possible.
We're aiming to have 5.10 free of docs warnings ;-)

If you prefer, I can send those patches to Linus with your
ack.

Regards,
Mauro

> 
> 							Thanx, Paul
> 
> > ---
> >  kernel/rcu/tree.c | 14 ++++++--------
> >  1 file changed, 6 insertions(+), 8 deletions(-)
> > 
> > diff --git a/kernel/rcu/tree.c b/kernel/rcu/tree.c
> > index f78ee759af9c..03c54c3478b7 100644
> > --- a/kernel/rcu/tree.c
> > +++ b/kernel/rcu/tree.c
> > @@ -3022,6 +3022,12 @@ struct kfree_rcu_cpu_work {
> >   * @monitor_todo: Tracks whether a @monitor_work delayed work is pending
> >   * @initialized: The @rcu_work fields have been initialized
> >   * @count: Number of objects for which GP not started
> > + * @bkvcache:
> > + *	A simple cache list that contains objects for reuse purpose.
> > + *	In order to save some per-cpu space the list is singular.
> > + *	Even though it is lockless an access has to be protected by the
> > + *	per-cpu lock.
> > + * @nr_bkv_objs: number of allocated objects at @bkvcache.
> >   *
> >   * This is a per-CPU structure.  The reason that it is not included in
> >   * the rcu_data structure is to permit this code to be extracted from
> > @@ -3037,14 +3043,6 @@ struct kfree_rcu_cpu {
> >  	bool monitor_todo;
> >  	bool initialized;
> >  	int count;
> > -
> > -	/*
> > -	 * A simple cache list that contains objects for
> > -	 * reuse purpose. In order to save some per-cpu
> > -	 * space the list is singular. Even though it is
> > -	 * lockless an access has to be protected by the
> > -	 * per-cpu lock.
> > -	 */
> >  	struct llist_head bkvcache;
> >  	int nr_bkv_objs;
> >  };
> > -- 
> > 2.26.2
> >   



Thanks,
Mauro

Re: [PATCH v6 70/80] rcu/tree: docs: document bkvcache new members at struct kfree_rcu_cpu

[Paul E. McKenney]

On Tue, Oct 13, 2020 at 10:46:08PM +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 13 Oct 2020 09:34:04 -0700
> "Paul E. McKenney" <paulmck@kernel.org> escreveu:
> 
> > On Tue, Oct 13, 2020 at 01:54:25PM +0200, Mauro Carvalho Chehab wrote:
> > > Changeset 53c72b590b3a ("rcu/tree: cache specified number of objects")
> > > added new members for struct kfree_rcu_cpu, but didn't add the
> > > corresponding at the kernel-doc markup, as repoted when doing
> > > "make htmldocs":
> > > 	./kernel/rcu/tree.c:3113: warning: Function parameter or member 'bkvcache' not described in 'kfree_rcu_cpu'
> > > 	./kernel/rcu/tree.c:3113: warning: Function parameter or member 'nr_bkv_objs' not described in 'kfree_rcu_cpu'
> > > 
> > > So, move the description for bkvcache to kernel-doc, and add a
> > > description for nr_bkv_objs.
> > > 
> > > Fixes: 53c72b590b3a ("rcu/tree: cache specified number of objects")
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> > 
> > Queued for review and testing, likely target v5.11.
> 
> Hi Paul,
> 
> I would prefer if we could get those on 5.10, if possible.
> We're aiming to have 5.10 free of docs warnings ;-)
> 
> If you prefer, I can send those patches to Linus with your
> ack.

That sounds easier:

Acked-by: Paul E. McKenney <paulmck@kernel.org>

Alan's objection is quite valid, but we will address that issue in a
follow-on patch that will not be on the fast track.

							Thanx, Paul

> Regards,
> Mauro
> 
> > 
> > 							Thanx, Paul
> > 
> > > ---
> > >  kernel/rcu/tree.c | 14 ++++++--------
> > >  1 file changed, 6 insertions(+), 8 deletions(-)
> > > 
> > > diff --git a/kernel/rcu/tree.c b/kernel/rcu/tree.c
> > > index f78ee759af9c..03c54c3478b7 100644
> > > --- a/kernel/rcu/tree.c
> > > +++ b/kernel/rcu/tree.c
> > > @@ -3022,6 +3022,12 @@ struct kfree_rcu_cpu_work {
> > >   * @monitor_todo: Tracks whether a @monitor_work delayed work is pending
> > >   * @initialized: The @rcu_work fields have been initialized
> > >   * @count: Number of objects for which GP not started
> > > + * @bkvcache:
> > > + *	A simple cache list that contains objects for reuse purpose.
> > > + *	In order to save some per-cpu space the list is singular.
> > > + *	Even though it is lockless an access has to be protected by the
> > > + *	per-cpu lock.
> > > + * @nr_bkv_objs: number of allocated objects at @bkvcache.
> > >   *
> > >   * This is a per-CPU structure.  The reason that it is not included in
> > >   * the rcu_data structure is to permit this code to be extracted from
> > > @@ -3037,14 +3043,6 @@ struct kfree_rcu_cpu {
> > >  	bool monitor_todo;
> > >  	bool initialized;
> > >  	int count;
> > > -
> > > -	/*
> > > -	 * A simple cache list that contains objects for
> > > -	 * reuse purpose. In order to save some per-cpu
> > > -	 * space the list is singular. Even though it is
> > > -	 * lockless an access has to be protected by the
> > > -	 * per-cpu lock.
> > > -	 */
> > >  	struct llist_head bkvcache;
> > >  	int nr_bkv_objs;
> > >  };
> > > -- 
> > > 2.26.2
> > >   
> 
> 
> 
> Thanks,
> Mauro

Re: [PATCH v6 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags

[Mauro Carvalho Chehab]

Em Tue, 13 Oct 2020 10:25:12 -0700
Eric Biggers <ebiggers@kernel.org> escreveu:

> On Tue, Oct 13, 2020 at 01:53:50PM +0200, Mauro Carvalho Chehab wrote:
> > The :c:type: tag has problems with Sphinx 3.x, as structs
> > there should be declared with c:struct.
> > 
> > So, remove them, relying at automarkup.py extension to
> > convert them into cross-references.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> 
> I left some comments on v5 which weren't addressed.
> 
> - Eric

Sorry, I missed your reply. I'm dropping fscrypt.rst changes
that were on this patch:

	[PATCH v6 23/80] docs: get rid of :c:type explicit declarations for structs

and replacing with the enclosed one that should be addressing
your issues.

Thanks,
Mauro

[PATCH v6.1 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags

The :c:type: tag has problems with Sphinx 3.x, as structs
there should be declared with c:struct.

So, remove them, relying at automarkup.py extension to
convert them into cross-references.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst
index 423c5a0daf45..44b67ebd6e40 100644
--- a/Documentation/filesystems/fscrypt.rst
+++ b/Documentation/filesystems/fscrypt.rst
@@ -436,9 +436,9 @@ FS_IOC_SET_ENCRYPTION_POLICY
 
 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
 empty directory or verifies that a directory or regular file already
-has the specified encryption policy.  It takes in a pointer to a
-:c:type:`struct fscrypt_policy_v1` or a :c:type:`struct
-fscrypt_policy_v2`, defined as follows::
+has the specified encryption policy.  It takes in a pointer to
+struct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as
+follows::
 
     #define FSCRYPT_POLICY_V1               0
     #define FSCRYPT_KEY_DESCRIPTOR_SIZE     8
@@ -464,11 +464,11 @@ fscrypt_policy_v2`, defined as follows::
 
 This structure must be initialized as follows:
 
-- ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is
-  :c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct
-  is :c:type:`fscrypt_policy_v2`.  (Note: we refer to the original
-  policy version as "v1", though its version code is really 0.)  For
-  new encrypted directories, use v2 policies.
+- ``version`` must be FSCRYPT_POLICY_V1 (0) if
+  struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if
+  struct fscrypt_policy_v2 is used. (Note: we refer to the original
+  policy version as "v1", though its version code is really 0.)
+  For new encrypted directories, use v2 policies.
 
 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
   be set to constants from ``<linux/fscrypt.h>`` which identify the
@@ -508,9 +508,9 @@ This structure must be initialized as follows:
   replaced with ``master_key_identifier``, which is longer and cannot
   be arbitrarily chosen.  Instead, the key must first be added using
   `FS_IOC_ADD_ENCRYPTION_KEY`_.  Then, the ``key_spec.u.identifier``
-  the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must
-  be used as the ``master_key_identifier`` in the :c:type:`struct
-  fscrypt_policy_v2`.
+  the kernel returned in the struct fscrypt_add_key_arg must
+  be used as the ``master_key_identifier`` in
+  struct fscrypt_policy_v2.
 
 If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
 verifies that the file is an empty directory.  If so, the specified
@@ -590,7 +590,7 @@ FS_IOC_GET_ENCRYPTION_POLICY_EX
 The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
 policy, if any, for a directory or regular file.  No additional
 permissions are required beyond the ability to open the file.  It
-takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`,
+takes in a pointer to struct fscrypt_get_policy_ex_arg,
 defined as follows::
 
     struct fscrypt_get_policy_ex_arg {
@@ -637,9 +637,8 @@ The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the
 encryption policy, if any, for a directory or regular file.  However,
 unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
 FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
-version.  It takes in a pointer directly to a :c:type:`struct
-fscrypt_policy_v1` rather than a :c:type:`struct
-fscrypt_get_policy_ex_arg`.
+version.  It takes in a pointer directly to struct fscrypt_policy_v1
+rather than struct fscrypt_get_policy_ex_arg.
 
 The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
 for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
@@ -680,8 +679,7 @@ the filesystem, making all files on the filesystem which were
 encrypted using that key appear "unlocked", i.e. in plaintext form.
 It can be executed on any file or directory on the target filesystem,
 but using the filesystem's root directory is recommended.  It takes in
-a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as
-follows::
+a pointer to struct fscrypt_add_key_arg, defined as follows::
 
     struct fscrypt_add_key_arg {
             struct fscrypt_key_specifier key_spec;
@@ -710,17 +708,16 @@ follows::
             __u8 raw[];
     };
 
-:c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized
+struct fscrypt_add_key_arg must be zeroed, then initialized
 as follows:
 
 - If the key is being added for use by v1 encryption policies, then
   ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and
   ``key_spec.u.descriptor`` must contain the descriptor of the key
   being added, corresponding to the value in the
-  ``master_key_descriptor`` field of :c:type:`struct
-  fscrypt_policy_v1`.  To add this type of key, the calling process
-  must have the CAP_SYS_ADMIN capability in the initial user
-  namespace.
+  ``master_key_descriptor`` field of struct fscrypt_policy_v1.
+  To add this type of key, the calling process must have the
+  CAP_SYS_ADMIN capability in the initial user namespace.
 
   Alternatively, if the key is being added for use by v2 encryption
   policies, then ``key_spec.type`` must contain
@@ -737,12 +734,13 @@ as follows:
 
 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
   field.  Otherwise ``key_id`` is the ID of a Linux keyring key of
-  type "fscrypt-provisioning" whose payload is a :c:type:`struct
-  fscrypt_provisioning_key_payload` whose ``raw`` field contains the
-  raw key and whose ``type`` field matches ``key_spec.type``.  Since
-  ``raw`` is variable-length, the total size of this key's payload
-  must be ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the
-  raw key size.  The process must have Search permission on this key.
+  type "fscrypt-provisioning" whose payload is
+  struct fscrypt_provisioning_key_payload whose ``raw`` field contains
+  the raw key and whose ``type`` field matches ``key_spec.type``.
+  Since ``raw`` is variable-length, the total size of this key's
+  payload must be ``sizeof(struct fscrypt_provisioning_key_payload)``
+  plus the raw key size.  The process must have Search permission on
+  this key.
 
   Most users should leave this 0 and specify the raw key directly.
   The support for specifying a Linux keyring key is intended mainly to
@@ -860,8 +858,8 @@ The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
 encryption key from the filesystem, and possibly removes the key
 itself.  It can be executed on any file or directory on the target
 filesystem, but using the filesystem's root directory is recommended.
-It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`,
-defined as follows::
+It takes in a pointer to struct fscrypt_remove_key_arg, defined
+as follows::
 
     struct fscrypt_remove_key_arg {
             struct fscrypt_key_specifier key_spec;
@@ -956,8 +954,8 @@ FS_IOC_GET_ENCRYPTION_KEY_STATUS
 The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
 master encryption key.  It can be executed on any file or directory on
 the target filesystem, but using the filesystem's root directory is
-recommended.  It takes in a pointer to a :c:type:`struct
-fscrypt_get_key_status_arg`, defined as follows::
+recommended.  It takes in a pointer to
+struct fscrypt_get_key_status_arg, defined as follows::
 
     struct fscrypt_get_key_status_arg {
             /* input */
@@ -1148,10 +1146,10 @@ Implementation details
 Encryption context
 ------------------
 
-An encryption policy is represented on-disk by a :c:type:`struct
-fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`.  It is
-up to individual filesystems to decide where to store it, but normally
-it would be stored in a hidden extended attribute.  It should *not* be
+An encryption policy is represented on-disk by
+struct fscrypt_context_v1 or struct fscrypt_context_v2.  It is up to
+individual filesystems to decide where to store it, but normally it
+would be stored in a hidden extended attribute.  It should *not* be
 exposed by the xattr-related system calls such as getxattr() and
 setxattr() because of the special semantics of the encryption xattr.
 (In particular, there would be much confusion if an encryption policy
@@ -1249,8 +1247,8 @@ a strong "hash" of the ciphertext filename, along with the optional
 filesystem-specific hash(es) needed for directory lookups.  This
 allows the filesystem to still, with a high degree of confidence, map
 the filename given in ->lookup() back to a particular directory entry
-that was previously listed by readdir().  See :c:type:`struct
-fscrypt_nokey_name` in the source for more details.
+that was previously listed by readdir().  See
+struct fscrypt_nokey_name in the source for more details.
 
 Note that the precise way that filenames are presented to userspace
 without the key is subject to change in the future.  It is only meant

Re: [PATCH v6 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags

[Eric Biggers]

On Wed, Oct 14, 2020 at 08:59:07AM +0200, Mauro Carvalho Chehab wrote:
> [PATCH v6.1 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags
> 
> The :c:type: tag has problems with Sphinx 3.x, as structs
> there should be declared with c:struct.
> 
> So, remove them, relying at automarkup.py extension to
> convert them into cross-references.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

"relying at" => "relying on".

Otherwise looks fine, you can add:

Reviewed-by: Eric Biggers <ebiggers@google.com>

I do still wonder about your comment though:

> It should be said that, currently, if there's no documentation for "foo",
> automarkup will just keep using the regular text font, keeping the text
> untouched.

That will apply to most (maybe all) of the structures mentioned in this file.
I expected that if the documentation system now automatically recognizes
'struct foo', then it would render it in code font even when 'struct foo' isn't
documented.  Any particular reason why that isn't the case?  Not like I care
much myself, but it's a bit unexpected and it means this change actually makes
the rendered documentation look worse...

- Eric

Re: [PATCH v6 69/80] IB/srpt: docs: add a description for cq_size member

[Bart Van Assche]

On 10/13/20 4:54 AM, Mauro Carvalho Chehab wrote:
> Changeset c804af2c1d31 ("IB/srpt: use new shared CQ mechanism")
> added a new member for struct srpt_rdma_ch, but didn't add the
> corresponding kernel-doc markup, as repoted when doing
> "make htmldocs":
> 	./drivers/infiniband/ulp/srpt/ib_srpt.h:331: warning: Function parameter or member 'cq_size' not described in 'srpt_rdma_ch'
> 
> Add a description for it.
> 
> Fixes: c804af2c1d31 ("IB/srpt: use new shared CQ mechanism")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/infiniband/ulp/srpt/ib_srpt.h | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/drivers/infiniband/ulp/srpt/ib_srpt.h b/drivers/infiniband/ulp/srpt/ib_srpt.h
> index 41435a699b53..e5d6af14d073 100644
> --- a/drivers/infiniband/ulp/srpt/ib_srpt.h
> +++ b/drivers/infiniband/ulp/srpt/ib_srpt.h
> @@ -256,6 +256,7 @@ enum rdma_ch_state {
>   * @rdma_cm:	   See below.
>   * @rdma_cm.cm_id: RDMA CM ID associated with the channel.
>   * @cq:            IB completion queue for this channel.
> + * @cq_size:	   Size of the @cq pool.
>   * @zw_cqe:	   Zero-length write CQE.
>   * @rcu:           RCU head.
>   * @kref:	   kref for this channel.

That doesn't seem correct to me. My understanding is that cq_size is the
number of CQEs in @cq. @cq is a completion queue and not a CQ pool.

Bart.

Re: [PATCH v6 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags

[Mauro Carvalho Chehab]

Em Wed, 14 Oct 2020 14:59:54 -0700
Eric Biggers <ebiggers@kernel.org> escreveu:

> On Wed, Oct 14, 2020 at 08:59:07AM +0200, Mauro Carvalho Chehab wrote:
> > [PATCH v6.1 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags
> > 
> > The :c:type: tag has problems with Sphinx 3.x, as structs
> > there should be declared with c:struct.
> > 
> > So, remove them, relying at automarkup.py extension to
> > convert them into cross-references.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> 
> "relying at" => "relying on".
> 
> Otherwise looks fine, you can add:
> 
> Reviewed-by: Eric Biggers <ebiggers@google.com>

Thank you for reviewing it!

> I do still wonder about your comment though:
> 
> > It should be said that, currently, if there's no documentation for "foo",
> > automarkup will just keep using the regular text font, keeping the text
> > untouched.  
> 
> That will apply to most (maybe all) of the structures mentioned in this file.
> I expected that if the documentation system now automatically recognizes
> 'struct foo', then it would render it in code font even when 'struct foo' isn't
> documented.  Any particular reason why that isn't the case?  Not like I care
> much myself, but it's a bit unexpected and it means this change actually makes
> the rendered documentation look worse...

Yeah, I agree that using monospaced fonts on this case too would
be nice. The C domain actually uses italic monospaced fonts for
broken XREFs.

I suspect that changing this at automarkup.py would be simple, but
not sure if it would be safe.

Jon can tell more about that, as he's the author of automarkup,
but I suspect that the reason for the current behavior is to avoid 
false-positives. 

I mean, if "struct foo" symbol doesn't exist at the C domain, this
might mean that the parser is doing something wrong. So, a more
conservative approach is to keep the string as-is.

On the other hand, if one finds a valid "struct foo" using normal
fonts, this would mean that either the doc is outdated, mentioning
an struct that were removed/renamed or that there's a missing 
kernel-doc markup.

In any case, the fix is to simply fix the kernel-doc markup for
struct foo.

I guess in the future automarkup.py could issue a warning in
order to warn about missing cross-references, perhaps when
W=1 or W=2 is used.

Thanks,
Mauro

Re: [PATCH v6 00/80] htmldoc build fixes with Sphinx 2.x and 3.x

[Daniel Vetter]

On Tue, Oct 13, 2020 at 01:53:15PM +0200, Mauro Carvalho Chehab wrote:
> This series actually folds the previous Sphinx 3.x patch series
> with the other patches I sent fixing warnings with Sphinx
> 2.x and with kernel-doc and that weren't merged yet via
> some other tree.
>
> It is based on the top of upstream, plus the media
> pull request I sent yesterday:
>
>       https://lore.kernel.org/lkml/20201012134139.0d58f5d7@coco.lan/
>
> My plan is to send a pull request with those patches after Thursday's
> linux next release.
>
> On this series, I removed the patches that depend on material
> currently found only at linux-next.

Was a bit tricky to find the cover letter here and that you plan to
send these out this merge window. I think we'll have some confusion
now with Alex from amd having picked up a few already.

Anyway Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch> for the
remaining drm patches. Although I can also pick them up to
drm-misc-next (but that's going to be 5.11 or so).
-Daniel


>
> Mauro Carvalho Chehab (79):
>   scripts: kernel-doc: add support for typedef enum
>   scripts: kernel-doc: make it more compatible with Sphinx 3.x
>   scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx
>     3.x
>   scripts: kernel-doc: fix troubles with line counts
>   scripts: kernel-doc: reimplement -nofunction argument
>   scripts: kernel-doc: fix typedef identification
>   scripts: kernel-doc: don't mangle with parameter list
>   scripts: kernel-doc: allow passing desired Sphinx C domain dialect
>   scripts: kernel-doc: fix line number handling
>   scripts: kernel-doc: try to use c:function if possible
>   docs: cdomain.py: add support for a new Sphinx 3.1+ tag
>   docs: cdomain.py: extend it to handle new Sphinx 3.x tags
>   docs: kerneldoc.py: append the name of the parsed doc file
>   docs: kerneldoc.py: add support for kerneldoc -nosymbol
>   media: docs: make CEC documents compatible with Sphinx 3.1+
>   media: docs: make V4L documents more compatible with Sphinx 3.1+
>   media: docs: make DVB documents more compatible with Sphinx 3.1+
>   media: docs: make MC documents more compatible with Sphinx 3.1+
>   media: docs: make RC documents more compatible with Sphinx 3.1+
>   media: cec-core.rst: don't use c:type for structs
>   docs: remove some replace macros like |struct foo|
>   docs: get rid of :c:type explicit declarations for structs
>   docs: trace-uses.rst: remove bogus c-domain tags
>   docs: it_IT: fix namespace collisions at locking.rst
>   docs: net: ieee802154.rst: fix C expressions
>   docs: genericirq.rst: don't document chip.c functions twice
>   docs: kernel-api.rst: drop kernel/irq/manage.c kernel-doc tag
>   docs: remove sound API duplication
>   docs: basics.rst: move kernel-doc workqueue markups to workqueue.rst
>   docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup
>   docs: device_link.rst: remove duplicated kernel-doc include
>   docs: basics.rst: get rid of rcu kernel-doc macros
>   docs: pstore-blk.rst: fix kernel-doc tags
>   docs: fs: fscrypt.rst: get rid of :c:type: tags
>   docs: devices.rst: get rid of :c:type macros
>   docs: sound: writing-an-alsa-driver.rst: get rid of :c:type
>   docs: block: blk-mq.rst: get rid of :c:type
>   docs: writing-an-alsa-driver.rst: fix some bad c:func: markups
>   docs: fpga: replace :c:member: macros
>   docs: kgdb.rst: fix :c:type: usages
>   docs: libata.rst: fix a wrong usage of :c:type: tag
>   docs: infrastructure.rst: don't include firmware kernel-doc
>   docs: gpu: i915.rst: Fix several C duplication warnings
>   docs: devices.rst: fix a C reference markup
>   docs: it_IT: hacking.rst: fix a typo on a markup
>   docs: mei.rst: fix a C expression markup
>   docs: basics.rst: avoid duplicated C function declaration
>   docs: conf.py: fix c:function support with Sphinx 3.x
>   docs: conf.py: change the Sphinx 3.x+ text
>   docs: infrastructure.rst: exclude device_link_state from device.h
>   docs: zh_CN: amu.rst: fix document title markup
>   media: uAPI: buffer.rst: remove a left-over documentation
>   math64.h: kernel-docs: Convert some markups into normal comments
>   memblock: get rid of a :c:type leftover
>   dt-bindings: fix references to files converted to yaml
>   net: appletalk: Kconfig: Fix docs location
>   drivers: net: hamradio: fix document location
>   docs: powerpc: syscall64-abi.rst: fix a malformed table
>   block: bio: fix a warning at the kernel-doc markups
>   kunit: test.h: solve kernel-doc warnings
>   docs: bio: fix a kerneldoc markup
>   drivers: core: fix kernel-doc markup for dev_err_probe()
>   kunit: test.h: fix a bad kernel-doc markup
>   docs: amdgpu: fix a warning when building the documentation
>   locking/refcount: document the new "oldp" pointer value
>   usb: docs: document altmode register/unregister functions
>   nl80211: docs: add a description for s1g_cap parameter
>   IB/srpt: docs: add a description for cq_size member
>   rcu/tree: docs: document bkvcache new members at struct kfree_rcu_cpu
>   Input: sparse-keymap: add a description for @sw
>   drm/amd/display: kernel-doc: document force_timing_sync
>   drm: kernel-doc: drm_dp_helper.h: fix a typo
>   gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markups
>   drm: kernel-doc: add description for a new function parameter
>   docs: virt: user_mode_linux_howto_v2.rst: fix a literal block markup
>   workqueue: fix a kernel-doc warning
>   mm/doc: fix a literal block markup
>   drm: drm_edid: remove a duplicated kernel-doc declaration
>   PM / devfreq: remove a duplicated kernel-doc markup
>
> Nícolas F. R. A. Prado (1):
>   docs: automarkup.py: make it ready for Sphinx 3.1+
>
>  Documentation/admin-guide/pm/cpufreq.rst      |  11 +-
>  Documentation/admin-guide/pstore-blk.rst      |  10 +-
>  Documentation/block/blk-mq.rst                |  12 +-
>  Documentation/block/inline-encryption.rst     |   8 +-
>  Documentation/conf.py                         |  65 +++-
>  Documentation/core-api/genericirq.rst         |   2 +
>  Documentation/core-api/kernel-api.rst         |   6 -
>  Documentation/core-api/workqueue.rst          |   2 +
>  Documentation/dev-tools/kgdb.rst              |   6 +-
>  .../bindings/display/tilcdc/tilcdc.txt        |   2 +-
>  .../bindings/mailbox/omap-mailbox.txt         |   2 +-
>  .../devicetree/bindings/media/i2c/tvp5150.txt |   2 +-
>  .../bindings/pwm/google,cros-ec-pwm.yaml      |   2 +-
>  .../bindings/soc/qcom/qcom,smd-rpm.yaml       |   2 +-
>  .../bindings/sound/google,cros-ec-codec.yaml  |   2 +-
>  Documentation/doc-guide/kernel-doc.rst        |   8 +
>  Documentation/driver-api/basics.rst           |  19 +-
>  Documentation/driver-api/device_link.rst      |  13 +-
>  Documentation/driver-api/fpga/fpga-bridge.rst |   4 +-
>  Documentation/driver-api/fpga/fpga-mgr.rst    |   6 +-
>  .../driver-api/fpga/fpga-programming.rst      |   2 +-
>  Documentation/driver-api/fpga/fpga-region.rst |   6 +-
>  Documentation/driver-api/iio/buffers.rst      |   2 +-
>  Documentation/driver-api/iio/core.rst         |   6 +-
>  Documentation/driver-api/iio/hw-consumer.rst  |   2 +-
>  .../driver-api/iio/triggered-buffers.rst      |   2 +-
>  Documentation/driver-api/iio/triggers.rst     |   4 +-
>  Documentation/driver-api/index.rst            |   1 -
>  Documentation/driver-api/infrastructure.rst   |   4 +-
>  Documentation/driver-api/libata.rst           |   2 +-
>  Documentation/driver-api/media/cec-core.rst   |   2 +-
>  .../driver-api/media/dtv-frontend.rst         |   4 +-
>  Documentation/driver-api/media/mc-core.rst    |  24 +-
>  .../driver-api/media/v4l2-controls.rst        |   2 +-
>  Documentation/driver-api/media/v4l2-dev.rst   |   8 +-
>  .../driver-api/media/v4l2-device.rst          |   6 +-
>  Documentation/driver-api/media/v4l2-event.rst |  10 +-
>  Documentation/driver-api/media/v4l2-fh.rst    |  16 +-
>  .../driver-api/media/v4l2-subdev.rst          |   2 +-
>  Documentation/driver-api/mei/mei.rst          |   2 +-
>  Documentation/driver-api/pm/cpuidle.rst       |  65 ++--
>  Documentation/driver-api/pm/devices.rst       |  26 +-
>  Documentation/driver-api/regulator.rst        |   4 +-
>  Documentation/driver-api/sound.rst            |  54 ----
>  Documentation/driver-api/target.rst           |  12 -
>  Documentation/driver-api/usb/URB.rst          |   2 +-
>  Documentation/driver-api/usb/gadget.rst       |  10 +-
>  Documentation/driver-api/usb/hotplug.rst      |   2 +-
>  Documentation/driver-api/usb/typec_bus.rst    |   8 +-
>  Documentation/filesystems/fscrypt.rst         |  61 ++--
>  Documentation/filesystems/fsverity.rst        |   2 +-
>  Documentation/gpu/amdgpu.rst                  |  11 +-
>  Documentation/gpu/i915.rst                    |  29 +-
>  Documentation/networking/ieee802154.rst       |  18 +-
>  Documentation/powerpc/syscall64-abi.rst       |  32 +-
>  Documentation/sound/designs/tracepoints.rst   |  22 +-
>  .../sound/kernel-api/alsa-driver-api.rst      |   1 +
>  .../kernel-api/writing-an-alsa-driver.rst     | 110 +++----
>  Documentation/sphinx/automarkup.py            |  69 +++-
>  Documentation/sphinx/cdomain.py               |  93 +++++-
>  Documentation/sphinx/kerneldoc.py             |  15 +-
>  Documentation/sphinx/parse-headers.pl         |   2 +-
>  Documentation/trace/ftrace-uses.rst           |  12 +-
>  .../it_IT/kernel-hacking/hacking.rst          |   2 +-
>  .../it_IT/kernel-hacking/locking.rst          |   2 +
>  .../translations/zh_CN/arm64/amu.rst          |   4 +-
>  .../media/cec/cec-func-close.rst              |  10 +-
>  .../media/cec/cec-func-ioctl.rst              |  11 +-
>  .../userspace-api/media/cec/cec-func-open.rst |  10 +-
>  .../userspace-api/media/cec/cec-func-poll.rst |  14 +-
>  .../media/cec/cec-ioc-adap-g-caps.rst         |  10 +-
>  .../media/cec/cec-ioc-adap-g-conn-info.rst    |  11 +-
>  .../media/cec/cec-ioc-adap-g-log-addrs.rst    |  20 +-
>  .../media/cec/cec-ioc-adap-g-phys-addr.rst    |  15 +-
>  .../media/cec/cec-ioc-dqevent.rst             |  15 +-
>  .../media/cec/cec-ioc-g-mode.rst              |  16 +-
>  .../media/cec/cec-ioc-receive.rst             |  18 +-
>  .../dvb/audio-bilingual-channel-select.rst    |   7 +-
>  .../media/dvb/audio-channel-select.rst        |   8 +-
>  .../media/dvb/audio-clear-buffer.rst          |   8 +-
>  .../media/dvb/audio-continue.rst              |   7 +-
>  .../userspace-api/media/dvb/audio-fclose.rst  |   7 +-
>  .../userspace-api/media/dvb/audio-fopen.rst   |   7 +-
>  .../userspace-api/media/dvb/audio-fwrite.rst  |   7 +-
>  .../media/dvb/audio-get-capabilities.rst      |   8 +-
>  .../media/dvb/audio-get-status.rst            |   8 +-
>  .../userspace-api/media/dvb/audio-pause.rst   |   9 +-
>  .../userspace-api/media/dvb/audio-play.rst    |   7 +-
>  .../media/dvb/audio-select-source.rst         |   8 +-
>  .../media/dvb/audio-set-av-sync.rst           |   8 +-
>  .../media/dvb/audio-set-bypass-mode.rst       |   9 +-
>  .../userspace-api/media/dvb/audio-set-id.rst  |   9 +-
>  .../media/dvb/audio-set-mixer.rst             |   9 +-
>  .../media/dvb/audio-set-mute.rst              |   8 +-
>  .../media/dvb/audio-set-streamtype.rst        |  10 +-
>  .../userspace-api/media/dvb/audio-stop.rst    |   9 +-
>  .../userspace-api/media/dvb/ca-fclose.rst     |   7 +-
>  .../userspace-api/media/dvb/ca-fopen.rst      |   7 +-
>  .../userspace-api/media/dvb/ca-get-cap.rst    |   8 +-
>  .../media/dvb/ca-get-descr-info.rst           |   9 +-
>  .../userspace-api/media/dvb/ca-get-msg.rst    |  10 +-
>  .../media/dvb/ca-get-slot-info.rst            |   9 +-
>  .../userspace-api/media/dvb/ca-reset.rst      |   9 +-
>  .../userspace-api/media/dvb/ca-send-msg.rst   |   9 +-
>  .../userspace-api/media/dvb/ca-set-descr.rst  |   8 +-
>  .../userspace-api/media/dvb/dmx-add-pid.rst   |  10 +-
>  .../userspace-api/media/dvb/dmx-expbuf.rst    |  11 +-
>  .../userspace-api/media/dvb/dmx-fclose.rst    |   9 +-
>  .../userspace-api/media/dvb/dmx-fopen.rst     |   5 +-
>  .../userspace-api/media/dvb/dmx-fread.rst     |   7 +-
>  .../userspace-api/media/dvb/dmx-fwrite.rst    |   6 +-
>  .../media/dvb/dmx-get-pes-pids.rst            |  12 +-
>  .../userspace-api/media/dvb/dmx-get-stc.rst   |  12 +-
>  .../userspace-api/media/dvb/dmx-mmap.rst      |  15 +-
>  .../userspace-api/media/dvb/dmx-munmap.rst    |  14 +-
>  .../userspace-api/media/dvb/dmx-qbuf.rst      |  17 +-
>  .../userspace-api/media/dvb/dmx-querybuf.rst  |   9 +-
>  .../media/dvb/dmx-remove-pid.rst              |  10 +-
>  .../userspace-api/media/dvb/dmx-reqbufs.rst   |   9 +-
>  .../media/dvb/dmx-set-buffer-size.rst         |  10 +-
>  .../media/dvb/dmx-set-filter.rst              |  12 +-
>  .../media/dvb/dmx-set-pes-filter.rst          |  13 +-
>  .../userspace-api/media/dvb/dmx-start.rst     |  11 +-
>  .../userspace-api/media/dvb/dmx-stop.rst      |   9 +-
>  .../media/dvb/fe-diseqc-recv-slave-reply.rst  |   9 +-
>  .../media/dvb/fe-diseqc-reset-overload.rst    |   9 +-
>  .../media/dvb/fe-diseqc-send-burst.rst        |  10 +-
>  .../media/dvb/fe-diseqc-send-master-cmd.rst   |   9 +-
>  .../dvb/fe-dishnetwork-send-legacy-cmd.rst    |  10 +-
>  .../media/dvb/fe-enable-high-lnb-voltage.rst  |  10 +-
>  .../userspace-api/media/dvb/fe-get-event.rst  |  12 +-
>  .../media/dvb/fe-get-frontend.rst             |  12 +-
>  .../userspace-api/media/dvb/fe-get-info.rst   |  11 +-
>  .../media/dvb/fe-get-property.rst             |  15 +-
>  .../userspace-api/media/dvb/fe-read-ber.rst   |   9 +-
>  .../media/dvb/fe-read-signal-strength.rst     |   9 +-
>  .../userspace-api/media/dvb/fe-read-snr.rst   |   9 +-
>  .../media/dvb/fe-read-status.rst              |  11 +-
>  .../media/dvb/fe-read-uncorrected-blocks.rst  |   9 +-
>  .../media/dvb/fe-set-frontend-tune-mode.rst   |  10 +-
>  .../media/dvb/fe-set-frontend.rst             |  11 +-
>  .../userspace-api/media/dvb/fe-set-tone.rst   |  10 +-
>  .../media/dvb/fe-set-voltage.rst              |  10 +-
>  .../media/dvb/frontend_f_close.rst            |   8 +-
>  .../media/dvb/frontend_f_open.rst             |  10 +-
>  .../userspace-api/media/dvb/net-add-if.rst    |   9 +-
>  .../userspace-api/media/dvb/net-get-if.rst    |  10 +-
>  .../userspace-api/media/dvb/net-remove-if.rst |  10 +-
>  .../media/dvb/video-clear-buffer.rst          |   8 +-
>  .../userspace-api/media/dvb/video-command.rst |  10 +-
>  .../media/dvb/video-continue.rst              |   8 +-
>  .../media/dvb/video-fast-forward.rst          |  10 +-
>  .../userspace-api/media/dvb/video-fclose.rst  |   6 +-
>  .../userspace-api/media/dvb/video-fopen.rst   |   6 +-
>  .../userspace-api/media/dvb/video-freeze.rst  |   8 +-
>  .../userspace-api/media/dvb/video-fwrite.rst  |   6 +-
>  .../media/dvb/video-get-capabilities.rst      |   8 +-
>  .../media/dvb/video-get-event.rst             |   8 +-
>  .../media/dvb/video-get-frame-count.rst       |   8 +-
>  .../userspace-api/media/dvb/video-get-pts.rst |   8 +-
>  .../media/dvb/video-get-size.rst              |   8 +-
>  .../media/dvb/video-get-status.rst            |   7 +-
>  .../userspace-api/media/dvb/video-play.rst    |   8 +-
>  .../media/dvb/video-select-source.rst         |   7 +-
>  .../media/dvb/video-set-blank.rst             |   8 +-
>  .../media/dvb/video-set-display-format.rst    |   8 +-
>  .../media/dvb/video-set-format.rst            |   9 +-
>  .../media/dvb/video-set-streamtype.rst        |   8 +-
>  .../media/dvb/video-slowmotion.rst            |  10 +-
>  .../media/dvb/video-stillpicture.rst          |   8 +-
>  .../userspace-api/media/dvb/video-stop.rst    |   8 +-
>  .../media/dvb/video-try-command.rst           |   8 +-
>  .../media/mediactl/media-func-close.rst       |  10 +-
>  .../media/mediactl/media-func-ioctl.rst       |  10 +-
>  .../media/mediactl/media-func-open.rst        |  10 +-
>  .../media/mediactl/media-ioc-device-info.rst  |  13 +-
>  .../mediactl/media-ioc-enum-entities.rst      |  11 +-
>  .../media/mediactl/media-ioc-enum-links.rst   |  13 +-
>  .../media/mediactl/media-ioc-g-topology.rst   |  14 +-
>  .../mediactl/media-ioc-request-alloc.rst      |  11 +-
>  .../media/mediactl/media-ioc-setup-link.rst   |  10 +-
>  .../mediactl/media-request-ioc-queue.rst      |   7 +-
>  .../mediactl/media-request-ioc-reinit.rst     |   8 +-
>  .../media/mediactl/request-api.rst            |   5 +-
>  .../media/mediactl/request-func-close.rst     |   8 +-
>  .../media/mediactl/request-func-ioctl.rst     |   8 +-
>  .../media/mediactl/request-func-poll.rst      |  12 +-
>  .../media/rc/lirc-get-features.rst            |   9 +-
>  .../media/rc/lirc-get-rec-mode.rst            |  12 +-
>  .../media/rc/lirc-get-rec-resolution.rst      |   8 +-
>  .../media/rc/lirc-get-send-mode.rst           |  14 +-
>  .../media/rc/lirc-get-timeout.rst             |  13 +-
>  .../userspace-api/media/rc/lirc-read.rst      |  10 +-
>  .../rc/lirc-set-measure-carrier-mode.rst      |   8 +-
>  .../media/rc/lirc-set-rec-carrier-range.rst   |   6 +-
>  .../media/rc/lirc-set-rec-carrier.rst         |   8 +-
>  .../media/rc/lirc-set-rec-timeout-reports.rst |   8 +-
>  .../media/rc/lirc-set-rec-timeout.rst         |  13 +-
>  .../media/rc/lirc-set-send-carrier.rst        |   8 +-
>  .../media/rc/lirc-set-send-duty-cycle.rst     |   8 +-
>  .../media/rc/lirc-set-transmitter-mask.rst    |   8 +-
>  .../media/rc/lirc-set-wideband-receiver.rst   |   8 +-
>  .../userspace-api/media/rc/lirc-write.rst     |   7 +-
>  .../userspace-api/media/v4l/buffer.rst        |  28 +-
>  .../userspace-api/media/v4l/dev-capture.rst   |   7 +-
>  .../userspace-api/media/v4l/dev-output.rst    |   7 +-
>  .../userspace-api/media/v4l/dev-raw-vbi.rst   |  19 +-
>  .../userspace-api/media/v4l/dev-rds.rst       |  12 +-
>  .../media/v4l/dev-sliced-vbi.rst              |  31 +-
>  .../userspace-api/media/v4l/diff-v4l.rst      |  39 +--
>  .../userspace-api/media/v4l/dmabuf.rst        |   8 +-
>  .../userspace-api/media/v4l/format.rst        |   7 +-
>  .../userspace-api/media/v4l/func-close.rst    |   8 +-
>  .../userspace-api/media/v4l/func-ioctl.rst    |  10 +-
>  .../userspace-api/media/v4l/func-mmap.rst     |  18 +-
>  .../userspace-api/media/v4l/func-munmap.rst   |  14 +-
>  .../userspace-api/media/v4l/func-open.rst     |  14 +-
>  .../userspace-api/media/v4l/func-poll.rst     |  40 ++-
>  .../userspace-api/media/v4l/func-read.rst     |  39 ++-
>  .../userspace-api/media/v4l/func-select.rst   |  42 ++-
>  .../userspace-api/media/v4l/func-write.rst    |  13 +-
>  .../userspace-api/media/v4l/hist-v4l2.rst     |  70 +---
>  Documentation/userspace-api/media/v4l/io.rst  |   6 +-
>  .../media/v4l/libv4l-introduction.rst         |  30 +-
>  .../userspace-api/media/v4l/mmap.rst          |  26 +-
>  .../userspace-api/media/v4l/open.rst          |  15 +-
>  Documentation/userspace-api/media/v4l/rw.rst  |  18 +-
>  .../userspace-api/media/v4l/streaming-par.rst |   5 +-
>  .../userspace-api/media/v4l/userp.rst         |  11 +-
>  .../media/v4l/vidioc-create-bufs.rst          |  11 +-
>  .../media/v4l/vidioc-cropcap.rst              |  11 +-
>  .../media/v4l/vidioc-dbg-g-chip-info.rst      |  13 +-
>  .../media/v4l/vidioc-dbg-g-register.rst       |  18 +-
>  .../media/v4l/vidioc-decoder-cmd.rst          |  19 +-
>  .../media/v4l/vidioc-dqevent.rst              |  19 +-
>  .../media/v4l/vidioc-dv-timings-cap.rst       |  17 +-
>  .../media/v4l/vidioc-encoder-cmd.rst          |  25 +-
>  .../media/v4l/vidioc-enum-dv-timings.rst      |  16 +-
>  .../media/v4l/vidioc-enum-fmt.rst             |  12 +-
>  .../media/v4l/vidioc-enum-frameintervals.rst  |  15 +-
>  .../media/v4l/vidioc-enum-framesizes.rst      |  16 +-
>  .../media/v4l/vidioc-enum-freq-bands.rst      |  12 +-
>  .../media/v4l/vidioc-enumaudio.rst            |  10 +-
>  .../media/v4l/vidioc-enumaudioout.rst         |  10 +-
>  .../media/v4l/vidioc-enuminput.rst            |  14 +-
>  .../media/v4l/vidioc-enumoutput.rst           |  13 +-
>  .../media/v4l/vidioc-enumstd.rst              |  23 +-
>  .../userspace-api/media/v4l/vidioc-expbuf.rst |  14 +-
>  .../media/v4l/vidioc-g-audio.rst              |  18 +-
>  .../media/v4l/vidioc-g-audioout.rst           |  16 +-
>  .../userspace-api/media/v4l/vidioc-g-crop.rst |  16 +-
>  .../userspace-api/media/v4l/vidioc-g-ctrl.rst |  16 +-
>  .../media/v4l/vidioc-g-dv-timings.rst         |  26 +-
>  .../userspace-api/media/v4l/vidioc-g-edid.rst |  25 +-
>  .../media/v4l/vidioc-g-enc-index.rst          |  13 +-
>  .../media/v4l/vidioc-g-ext-ctrls.rst          |  21 +-
>  .../userspace-api/media/v4l/vidioc-g-fbuf.rst |  18 +-
>  .../userspace-api/media/v4l/vidioc-g-fmt.rst  |  22 +-
>  .../media/v4l/vidioc-g-frequency.rst          |  16 +-
>  .../media/v4l/vidioc-g-input.rst              |  15 +-
>  .../media/v4l/vidioc-g-jpegcomp.rst           |  17 +-
>  .../media/v4l/vidioc-g-modulator.rst          |  17 +-
>  .../media/v4l/vidioc-g-output.rst             |  15 +-
>  .../userspace-api/media/v4l/vidioc-g-parm.rst |  30 +-
>  .../media/v4l/vidioc-g-priority.rst           |  16 +-
>  .../media/v4l/vidioc-g-selection.rst          |  15 +-
>  .../media/v4l/vidioc-g-sliced-vbi-cap.rst     |  12 +-
>  .../userspace-api/media/v4l/vidioc-g-std.rst  |  24 +-
>  .../media/v4l/vidioc-g-tuner.rst              |  19 +-
>  .../media/v4l/vidioc-log-status.rst           |  10 +-
>  .../media/v4l/vidioc-overlay.rst              |  10 +-
>  .../media/v4l/vidioc-prepare-buf.rst          |  10 +-
>  .../userspace-api/media/v4l/vidioc-qbuf.rst   |  17 +-
>  .../media/v4l/vidioc-query-dv-timings.rst     |  15 +-
>  .../media/v4l/vidioc-querybuf.rst             |  10 +-
>  .../media/v4l/vidioc-querycap.rst             |  16 +-
>  .../media/v4l/vidioc-queryctrl.rst            |  22 +-
>  .../media/v4l/vidioc-querystd.rst             |  15 +-
>  .../media/v4l/vidioc-reqbufs.rst              |  10 +-
>  .../media/v4l/vidioc-s-hw-freq-seek.rst       |  11 +-
>  .../media/v4l/vidioc-streamon.rst             |  14 +-
>  .../v4l/vidioc-subdev-enum-frame-interval.rst |  10 +-
>  .../v4l/vidioc-subdev-enum-frame-size.rst     |  11 +-
>  .../v4l/vidioc-subdev-enum-mbus-code.rst      |  10 +-
>  .../media/v4l/vidioc-subdev-g-crop.rst        |  16 +-
>  .../media/v4l/vidioc-subdev-g-fmt.rst         |  17 +-
>  .../v4l/vidioc-subdev-g-frame-interval.rst    |  16 +-
>  .../media/v4l/vidioc-subdev-g-selection.rst   |  17 +-
>  .../media/v4l/vidioc-subdev-querycap.rst      |   9 +-
>  .../media/v4l/vidioc-subscribe-event.rst      |  17 +-
>  .../virt/uml/user_mode_linux_howto_v2.rst     |   1 +
>  Documentation/vm/hmm.rst                      |   2 +-
>  Documentation/vm/ksm.rst                      |   2 +-
>  Documentation/vm/memory-model.rst             |   6 +-
>  MAINTAINERS                                   |  16 +-
>  block/bio.c                                   |   4 +-
>  drivers/base/core.c                           |   7 +-
>  .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h |   2 +
>  drivers/gpu/drm/drm_prime.c                   |   1 +
>  drivers/infiniband/ulp/srpt/ib_srpt.h         |   1 +
>  drivers/net/appletalk/Kconfig                 |   2 +-
>  drivers/net/hamradio/scc.c                    |   2 +-
>  include/drm/drm_dp_helper.h                   |   2 +-
>  include/drm/drm_edid.h                        |   7 -
>  include/kunit/test.h                          |  16 +-
>  include/linux/devfreq.h                       |   7 +-
>  include/linux/input/sparse-keymap.h           |   1 +
>  include/linux/math64.h                        |   8 +-
>  include/linux/refcount.h                      |   7 +
>  include/linux/usb/typec_altmode.h             |  16 +
>  include/net/cfg80211.h                        |   1 +
>  kernel/rcu/tree.c                             |  14 +-
>  kernel/workqueue.c                            |   3 +
>  mm/ksm.c                                      |   2 +-
>  mm/memblock.c                                 |   8 +-
>  scripts/kernel-doc                            | 303 +++++++++++++-----
>  316 files changed, 1921 insertions(+), 2285 deletions(-)
>  delete mode 100644 Documentation/driver-api/sound.rst
>
> --
> 2.26.2
>
>

--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [PATCH v6 00/80] htmldoc build fixes with Sphinx 2.x and 3.x

[Mauro Carvalho Chehab]

Em Thu, 15 Oct 2020 17:49:23 +0200
Daniel Vetter <daniel@ffwll.ch> escreveu:

> On Tue, Oct 13, 2020 at 01:53:15PM +0200, Mauro Carvalho Chehab wrote:
> > This series actually folds the previous Sphinx 3.x patch series
> > with the other patches I sent fixing warnings with Sphinx
> > 2.x and with kernel-doc and that weren't merged yet via
> > some other tree.
> >
> > It is based on the top of upstream, plus the media
> > pull request I sent yesterday:
> >
> >       https://lore.kernel.org/lkml/20201012134139.0d58f5d7@coco.lan/
> >
> > My plan is to send a pull request with those patches after Thursday's
> > linux next release.
> >
> > On this series, I removed the patches that depend on material
> > currently found only at linux-next.  
> 
> Was a bit tricky to find the cover letter here and that you plan to
> send these out this merge window. 

Sorry for that. As this series touch lots of subsystems, just c/c
the maintainers mean more than 50 c/c to patch 00. Some e-mail
servers may not accept e-mails with too many c/c people. 

Yet, checking at the c/c list of the original patch, you were
copied on patch 00/80. So, maybe the e-mail server had silently
dropped the original e-mail.

> I think we'll have some confusion
> now with Alex from amd having picked up a few already.

I ended moving (at least part of) the drm patches from this
series into a second one, as I'm intending to submit most of
those patches today or tomorrow, and the remaining ones by the
end of the merge window.

> Anyway Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch> for the
> remaining drm patches. 

Thank you!

> Although I can also pick them up to
> drm-misc-next (but that's going to be 5.11 or so).

It would be a way better to have them merged for 5.10, in
order to have a clean html build there.

Thanks,
Mauro

Re: [PATCH v6 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags

[Eric Biggers]

On Thu, Oct 15, 2020 at 07:32:07AM +0200, Mauro Carvalho Chehab wrote:
> On the other hand, if one finds a valid "struct foo" using normal
> fonts, this would mean that either the doc is outdated, mentioning
> an struct that were removed/renamed or that there's a missing 
> kernel-doc markup.
> 
> In any case, the fix is to simply fix the kernel-doc markup for
> struct foo.
> 
> I guess in the future automarkup.py could issue a warning in
> order to warn about missing cross-references, perhaps when
> W=1 or W=2 is used.

Well, most structs that fscrypt.rst refers to are defined in
include/uapi/linux/fscrypt.h.  The whole fscrypt UAPI, including the fields of
these structs, is documented in fscrypt.rst.  So I didn't really intend the
fscrypt UAPI structs to have kerneldoc comments, as people are supposed to refer
to the documentation in fscrypt.rst instead.  We could have both, but it feels a
bit redundant.

- Eric

Re: [PATCH v6 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags

[Mauro Carvalho Chehab]

Em Thu, 15 Oct 2020 09:36:05 -0700
Eric Biggers <ebiggers@kernel.org> escreveu:

> On Thu, Oct 15, 2020 at 07:32:07AM +0200, Mauro Carvalho Chehab wrote:
> > On the other hand, if one finds a valid "struct foo" using normal
> > fonts, this would mean that either the doc is outdated, mentioning
> > an struct that were removed/renamed or that there's a missing 
> > kernel-doc markup.
> > 
> > In any case, the fix is to simply fix the kernel-doc markup for
> > struct foo.
> > 
> > I guess in the future automarkup.py could issue a warning in
> > order to warn about missing cross-references, perhaps when
> > W=1 or W=2 is used.  
> 
> Well, most structs that fscrypt.rst refers to are defined in
> include/uapi/linux/fscrypt.h.  The whole fscrypt UAPI, including the fields of
> these structs, is documented in fscrypt.rst.  So I didn't really intend the
> fscrypt UAPI structs to have kerneldoc comments, as people are supposed to refer
> to the documentation in fscrypt.rst instead.  We could have both, but it feels a
> bit redundant.

Yeah, we do the same on V4L: the uAPI doesn't use kernel-docs. It is
documented, instead, at ReST files.

In any case, if all structs are documented, automarkup should
be using monospaced fonts and be generating cross-references.

If not, the regular expressions there may need tweaks ;-)

Thanks,
Mauro

Re: [PATCH v6 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags

[Jonathan Corbet]

On Thu, 15 Oct 2020 07:32:07 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> > That will apply to most (maybe all) of the structures mentioned in this file.
> > I expected that if the documentation system now automatically recognizes
> > 'struct foo', then it would render it in code font even when 'struct foo' isn't
> > documented.  Any particular reason why that isn't the case?  Not like I care
> > much myself, but it's a bit unexpected and it means this change actually makes
> > the rendered documentation look worse...  
> 
> Yeah, I agree that using monospaced fonts on this case too would
> be nice. The C domain actually uses italic monospaced fonts for
> broken XREFs.
> 
> I suspect that changing this at automarkup.py would be simple, but
> not sure if it would be safe.
> 
> Jon can tell more about that, as he's the author of automarkup,
> but I suspect that the reason for the current behavior is to avoid 
> false-positives. 

Automarkup has always behaved that way because ... well, because nobody
got around to changing it.  I don't see any reason not to use a monospace
font for such things, just without a link; shouldn't be a problem to do.
I'll see if I can't get to it once things stabilize a bit.

Thanks,

jon

Re: [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings

[Joonas Lahtinen]

+ Lionel

Can you please take a look at best resolving the below problem.

Maybe we should eliminate the duplicate declarations? Updating such
a list manually seems error prone to me.

Regards, Joonas

Quoting Mauro Carvalho Chehab (2020-10-13 14:53:59)
> As reported by Sphinx:
> 
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_oa_wait_unlocked'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_oa_poll_wait'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_oa_read'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_oa_stream_enable'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_oa_stream_disable'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_oa_stream_init'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_read'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_poll_locked'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_poll'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_enable_locked'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_disable_locked'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_ioctl'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_destroy_locked'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_release'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_open_ioctl_locked'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'read_properties_unlocked'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_open_ioctl'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_register'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_unregister'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_add_config_ioctl'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_remove_config_ioctl'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_init'.
>         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>         Declaration is 'i915_perf_fini'.
> 
> With Sphinx 3, C declarations can't be duplicated anymore,
> so let's exclude those from the other internals found on
> i915_perf.c file.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
>  1 file changed, 25 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 33cc6ddf8f64..cff1f154b473 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
>  .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>     :functions: i915_oa_poll_wait
>  
> -All i915 Perf Internals
> ------------------------
> +Other i915 Perf Internals
> +-------------------------
>  
> -This section simply includes all currently documented i915 perf internals, in
> -no particular order, but may include some more minor utilities or platform
> +This section simply includes all other currently documented i915 perf internals,
> +in no particular order, but may include some more minor utilities or platform
>  specific details than found in the more high-level sections.
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>     :internal:
> +   :no-identifiers:
> +       i915_perf_init
> +       i915_perf_fini
> +       i915_perf_register
> +       i915_perf_unregister
> +       i915_perf_open_ioctl
> +       i915_perf_release
> +       i915_perf_add_config_ioctl
> +       i915_perf_remove_config_ioctl
> +       read_properties_unlocked
> +       i915_perf_open_ioctl_locked
> +       i915_perf_destroy_locked
> +       i915_perf_read i915_perf_ioctl
> +       i915_perf_enable_locked
> +       i915_perf_disable_locked
> +       i915_perf_poll i915_perf_poll_locked
> +       i915_oa_stream_init i915_oa_read
> +       i915_oa_stream_enable
> +       i915_oa_stream_disable
> +       i915_oa_wait_unlocked
> +       i915_oa_poll_wait
>  
>  Style
>  =====
> -- 
> 2.26.2
> 

Re: [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings

[Mauro Carvalho Chehab]

Em Fri, 16 Oct 2020 14:01:07 +0300
Joonas Lahtinen <joonas.lahtinen@linux.intel.com> escreveu:

> + Lionel
> 
> Can you please take a look at best resolving the below problem.
> 
> Maybe we should eliminate the duplicate declarations? Updating such
> a list manually seems error prone to me.

For Kernel 5.10, IMO the best is to apply this patch as-is, as any
other thing would need to be postponed, and we want 5.10 free of
doc warnings.

Yet, when I wrote this one, I almost took a different approach:
to implement something like @*group (or \*group) directives that
exists on doxygen:

	https://www.doxygen.nl/manual/grouping.html

If something like that gets added to kernel-doc syntax, then
one could do something like:

	/**
	 * DOC: some foo description
	 * @group foo
	 */
 
	/**
	 * foo1 - do some foo things 
	 * @group foo
	...
	 */

	/**
	 * foo2 - do some other foo things
	 * @group foo
	...
	 */

	/**
	 * bar - do bar things
	 * @group bar
	...
	 */


And then, at kernel-doc markup:

	FOO
	===

	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
		:group: foo


	BAR
	===
	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
		:group: bar


I suspect that something like that would be a lot easier to maintain.

Once having someone like that implemented, it should be easy to also
have something like this:

	OTHERS
	======
	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
		:export:
		:not-grouped:

in order to pick other functions that aren't grouped.

I suspect that implementing something like that at kernel-doc.pl
won't be hard.

Regards,
Mauro

> 
> Regards, Joonas
> 
> Quoting Mauro Carvalho Chehab (2020-10-13 14:53:59)
> > As reported by Sphinx:
> > 
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_oa_wait_unlocked'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_oa_poll_wait'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_oa_read'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_oa_stream_enable'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_oa_stream_disable'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_oa_stream_init'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_read'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_poll_locked'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_poll'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_enable_locked'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_disable_locked'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_ioctl'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_destroy_locked'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_release'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_open_ioctl_locked'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'read_properties_unlocked'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_open_ioctl'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_register'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_unregister'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_add_config_ioctl'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_remove_config_ioctl'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_init'.
> >         ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> >         Declaration is 'i915_perf_fini'.
> > 
> > With Sphinx 3, C declarations can't be duplicated anymore,
> > so let's exclude those from the other internals found on
> > i915_perf.c file.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
> >  1 file changed, 25 insertions(+), 4 deletions(-)
> > 
> > diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> > index 33cc6ddf8f64..cff1f154b473 100644
> > --- a/Documentation/gpu/i915.rst
> > +++ b/Documentation/gpu/i915.rst
> > @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
> >  .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> >     :functions: i915_oa_poll_wait
> >  
> > -All i915 Perf Internals
> > ------------------------
> > +Other i915 Perf Internals
> > +-------------------------
> >  
> > -This section simply includes all currently documented i915 perf internals, in
> > -no particular order, but may include some more minor utilities or platform
> > +This section simply includes all other currently documented i915 perf internals,
> > +in no particular order, but may include some more minor utilities or platform
> >  specific details than found in the more high-level sections.
> >  
> >  .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> >     :internal:
> > +   :no-identifiers:
> > +       i915_perf_init
> > +       i915_perf_fini
> > +       i915_perf_register
> > +       i915_perf_unregister
> > +       i915_perf_open_ioctl
> > +       i915_perf_release
> > +       i915_perf_add_config_ioctl
> > +       i915_perf_remove_config_ioctl
> > +       read_properties_unlocked
> > +       i915_perf_open_ioctl_locked
> > +       i915_perf_destroy_locked
> > +       i915_perf_read i915_perf_ioctl
> > +       i915_perf_enable_locked
> > +       i915_perf_disable_locked
> > +       i915_perf_poll i915_perf_poll_locked
> > +       i915_oa_stream_init i915_oa_read
> > +       i915_oa_stream_enable
> > +       i915_oa_stream_disable
> > +       i915_oa_wait_unlocked
> > +       i915_oa_poll_wait
> >  
> >  Style
> >  =====
> > -- 
> > 2.26.2
> >   



Thanks,
Mauro

Re: [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings

[Lionel Landwerlin]

On 16/10/2020 14:37, Mauro Carvalho Chehab wrote:
> Em Fri, 16 Oct 2020 14:01:07 +0300
> Joonas Lahtinen <joonas.lahtinen@linux.intel.com> escreveu:
>
>> + Lionel
>>
>> Can you please take a look at best resolving the below problem.
>>
>> Maybe we should eliminate the duplicate declarations? Updating such
>> a list manually seems error prone to me.
> For Kernel 5.10, IMO the best is to apply this patch as-is, as any
> other thing would need to be postponed, and we want 5.10 free of
> doc warnings.


That's odd... Most of the functions are documented. Is it that we're 
missing the "()" after the function name maybe?


-Lionel


>
> Yet, when I wrote this one, I almost took a different approach:
> to implement something like @*group (or \*group) directives that
> exists on doxygen:
>
> 	https://www.doxygen.nl/manual/grouping.html
>
> If something like that gets added to kernel-doc syntax, then
> one could do something like:
>
> 	/**
> 	 * DOC: some foo description
> 	 * @group foo
> 	 */
>   
> 	/**
> 	 * foo1 - do some foo things
> 	 * @group foo
> 	...
> 	 */
>
> 	/**
> 	 * foo2 - do some other foo things
> 	 * @group foo
> 	...
> 	 */
>
> 	/**
> 	 * bar - do bar things
> 	 * @group bar
> 	...
> 	 */
>
>
> And then, at kernel-doc markup:
>
> 	FOO
> 	===
>
> 	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> 		:group: foo
>
>
> 	BAR
> 	===
> 	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> 		:group: bar
>
>
> I suspect that something like that would be a lot easier to maintain.
>
> Once having someone like that implemented, it should be easy to also
> have something like this:
>
> 	OTHERS
> 	======
> 	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> 		:export:
> 		:not-grouped:
>
> in order to pick other functions that aren't grouped.
>
> I suspect that implementing something like that at kernel-doc.pl
> won't be hard.
>
> Regards,
> Mauro
>
>> Regards, Joonas
>>
>> Quoting Mauro Carvalho Chehab (2020-10-13 14:53:59)
>>> As reported by Sphinx:
>>>
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_oa_wait_unlocked'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_oa_poll_wait'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_oa_read'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_oa_stream_enable'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_oa_stream_disable'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_oa_stream_init'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_read'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_poll_locked'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_poll'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_enable_locked'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_disable_locked'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_ioctl'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_destroy_locked'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_release'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_open_ioctl_locked'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'read_properties_unlocked'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_open_ioctl'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_register'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_unregister'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_add_config_ioctl'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_remove_config_ioctl'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_init'.
>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>          Declaration is 'i915_perf_fini'.
>>>
>>> With Sphinx 3, C declarations can't be duplicated anymore,
>>> so let's exclude those from the other internals found on
>>> i915_perf.c file.
>>>
>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>> ---
>>>   Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
>>>   1 file changed, 25 insertions(+), 4 deletions(-)
>>>
>>> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
>>> index 33cc6ddf8f64..cff1f154b473 100644
>>> --- a/Documentation/gpu/i915.rst
>>> +++ b/Documentation/gpu/i915.rst
>>> @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
>>>   .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>>      :functions: i915_oa_poll_wait
>>>   
>>> -All i915 Perf Internals
>>> ------------------------
>>> +Other i915 Perf Internals
>>> +-------------------------
>>>   
>>> -This section simply includes all currently documented i915 perf internals, in
>>> -no particular order, but may include some more minor utilities or platform
>>> +This section simply includes all other currently documented i915 perf internals,
>>> +in no particular order, but may include some more minor utilities or platform
>>>   specific details than found in the more high-level sections.
>>>   
>>>   .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>>      :internal:
>>> +   :no-identifiers:
>>> +       i915_perf_init
>>> +       i915_perf_fini
>>> +       i915_perf_register
>>> +       i915_perf_unregister
>>> +       i915_perf_open_ioctl
>>> +       i915_perf_release
>>> +       i915_perf_add_config_ioctl
>>> +       i915_perf_remove_config_ioctl
>>> +       read_properties_unlocked
>>> +       i915_perf_open_ioctl_locked
>>> +       i915_perf_destroy_locked
>>> +       i915_perf_read i915_perf_ioctl
>>> +       i915_perf_enable_locked
>>> +       i915_perf_disable_locked
>>> +       i915_perf_poll i915_perf_poll_locked
>>> +       i915_oa_stream_init i915_oa_read
>>> +       i915_oa_stream_enable
>>> +       i915_oa_stream_disable
>>> +       i915_oa_wait_unlocked
>>> +       i915_oa_poll_wait
>>>   
>>>   Style
>>>   =====
>>> -- 
>>> 2.26.2
>>>    
>
>
> Thanks,
> Mauro

Re: [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings

[Jani Nikula]

On Fri, 16 Oct 2020, Lionel Landwerlin <lionel.g.landwerlin@intel.com> wrote:
> On 16/10/2020 14:37, Mauro Carvalho Chehab wrote:
>> Em Fri, 16 Oct 2020 14:01:07 +0300
>> Joonas Lahtinen <joonas.lahtinen@linux.intel.com> escreveu:
>>
>>> + Lionel
>>>
>>> Can you please take a look at best resolving the below problem.
>>>
>>> Maybe we should eliminate the duplicate declarations? Updating such
>>> a list manually seems error prone to me.
>> For Kernel 5.10, IMO the best is to apply this patch as-is, as any
>> other thing would need to be postponed, and we want 5.10 free of
>> doc warnings.
>
>
> That's odd... Most of the functions are documented. Is it that we're 
> missing the "()" after the function name maybe?

The problem is we first include named functions, and then go on to
include everything again, duplicating the documentation for the named
functions.

BR,
Jani.


>
>
> -Lionel
>
>
>>
>> Yet, when I wrote this one, I almost took a different approach:
>> to implement something like @*group (or \*group) directives that
>> exists on doxygen:
>>
>> 	https://www.doxygen.nl/manual/grouping.html
>>
>> If something like that gets added to kernel-doc syntax, then
>> one could do something like:
>>
>> 	/**
>> 	 * DOC: some foo description
>> 	 * @group foo
>> 	 */
>>   
>> 	/**
>> 	 * foo1 - do some foo things
>> 	 * @group foo
>> 	...
>> 	 */
>>
>> 	/**
>> 	 * foo2 - do some other foo things
>> 	 * @group foo
>> 	...
>> 	 */
>>
>> 	/**
>> 	 * bar - do bar things
>> 	 * @group bar
>> 	...
>> 	 */
>>
>>
>> And then, at kernel-doc markup:
>>
>> 	FOO
>> 	===
>>
>> 	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>> 		:group: foo
>>
>>
>> 	BAR
>> 	===
>> 	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>> 		:group: bar
>>
>>
>> I suspect that something like that would be a lot easier to maintain.
>>
>> Once having someone like that implemented, it should be easy to also
>> have something like this:
>>
>> 	OTHERS
>> 	======
>> 	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>> 		:export:
>> 		:not-grouped:
>>
>> in order to pick other functions that aren't grouped.
>>
>> I suspect that implementing something like that at kernel-doc.pl
>> won't be hard.
>>
>> Regards,
>> Mauro
>>
>>> Regards, Joonas
>>>
>>> Quoting Mauro Carvalho Chehab (2020-10-13 14:53:59)
>>>> As reported by Sphinx:
>>>>
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_oa_wait_unlocked'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_oa_poll_wait'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_oa_read'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_oa_stream_enable'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_oa_stream_disable'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_oa_stream_init'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_read'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_poll_locked'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_poll'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_enable_locked'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_disable_locked'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_ioctl'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_destroy_locked'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_release'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_open_ioctl_locked'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'read_properties_unlocked'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_open_ioctl'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_register'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_unregister'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_add_config_ioctl'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_remove_config_ioctl'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_init'.
>>>>          ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>          Declaration is 'i915_perf_fini'.
>>>>
>>>> With Sphinx 3, C declarations can't be duplicated anymore,
>>>> so let's exclude those from the other internals found on
>>>> i915_perf.c file.
>>>>
>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>>> ---
>>>>   Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
>>>>   1 file changed, 25 insertions(+), 4 deletions(-)
>>>>
>>>> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
>>>> index 33cc6ddf8f64..cff1f154b473 100644
>>>> --- a/Documentation/gpu/i915.rst
>>>> +++ b/Documentation/gpu/i915.rst
>>>> @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
>>>>   .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>>>      :functions: i915_oa_poll_wait
>>>>   
>>>> -All i915 Perf Internals
>>>> ------------------------
>>>> +Other i915 Perf Internals
>>>> +-------------------------
>>>>   
>>>> -This section simply includes all currently documented i915 perf internals, in
>>>> -no particular order, but may include some more minor utilities or platform
>>>> +This section simply includes all other currently documented i915 perf internals,
>>>> +in no particular order, but may include some more minor utilities or platform
>>>>   specific details than found in the more high-level sections.
>>>>   
>>>>   .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>>>      :internal:
>>>> +   :no-identifiers:
>>>> +       i915_perf_init
>>>> +       i915_perf_fini
>>>> +       i915_perf_register
>>>> +       i915_perf_unregister
>>>> +       i915_perf_open_ioctl
>>>> +       i915_perf_release
>>>> +       i915_perf_add_config_ioctl
>>>> +       i915_perf_remove_config_ioctl
>>>> +       read_properties_unlocked
>>>> +       i915_perf_open_ioctl_locked
>>>> +       i915_perf_destroy_locked
>>>> +       i915_perf_read i915_perf_ioctl
>>>> +       i915_perf_enable_locked
>>>> +       i915_perf_disable_locked
>>>> +       i915_perf_poll i915_perf_poll_locked
>>>> +       i915_oa_stream_init i915_oa_read
>>>> +       i915_oa_stream_enable
>>>> +       i915_oa_stream_disable
>>>> +       i915_oa_wait_unlocked
>>>> +       i915_oa_poll_wait
>>>>   
>>>>   Style
>>>>   =====
>>>> -- 
>>>> 2.26.2
>>>>    
>>
>>
>> Thanks,
>> Mauro
>
>

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings

[Lionel Landwerlin]

On 16/10/2020 14:50, Jani Nikula wrote:
> On Fri, 16 Oct 2020, Lionel Landwerlin <lionel.g.landwerlin@intel.com> wrote:
>> On 16/10/2020 14:37, Mauro Carvalho Chehab wrote:
>>> Em Fri, 16 Oct 2020 14:01:07 +0300
>>> Joonas Lahtinen <joonas.lahtinen@linux.intel.com> escreveu:
>>>
>>>> + Lionel
>>>>
>>>> Can you please take a look at best resolving the below problem.
>>>>
>>>> Maybe we should eliminate the duplicate declarations? Updating such
>>>> a list manually seems error prone to me.
>>> For Kernel 5.10, IMO the best is to apply this patch as-is, as any
>>> other thing would need to be postponed, and we want 5.10 free of
>>> doc warnings.
>>
>> That's odd... Most of the functions are documented. Is it that we're
>> missing the "()" after the function name maybe?
> The problem is we first include named functions, and then go on to
> include everything again, duplicating the documentation for the named
> functions.
>
> BR,
> Jani.


Thanks, now the patch makes sense.


-Lionel


>
>
>>
>> -Lionel
>>
>>
>>> Yet, when I wrote this one, I almost took a different approach:
>>> to implement something like @*group (or \*group) directives that
>>> exists on doxygen:
>>>
>>> 	https://www.doxygen.nl/manual/grouping.html
>>>
>>> If something like that gets added to kernel-doc syntax, then
>>> one could do something like:
>>>
>>> 	/**
>>> 	 * DOC: some foo description
>>> 	 * @group foo
>>> 	 */
>>>    
>>> 	/**
>>> 	 * foo1 - do some foo things
>>> 	 * @group foo
>>> 	...
>>> 	 */
>>>
>>> 	/**
>>> 	 * foo2 - do some other foo things
>>> 	 * @group foo
>>> 	...
>>> 	 */
>>>
>>> 	/**
>>> 	 * bar - do bar things
>>> 	 * @group bar
>>> 	...
>>> 	 */
>>>
>>>
>>> And then, at kernel-doc markup:
>>>
>>> 	FOO
>>> 	===
>>>
>>> 	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>> 		:group: foo
>>>
>>>
>>> 	BAR
>>> 	===
>>> 	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>> 		:group: bar
>>>
>>>
>>> I suspect that something like that would be a lot easier to maintain.
>>>
>>> Once having someone like that implemented, it should be easy to also
>>> have something like this:
>>>
>>> 	OTHERS
>>> 	======
>>> 	.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>> 		:export:
>>> 		:not-grouped:
>>>
>>> in order to pick other functions that aren't grouped.
>>>
>>> I suspect that implementing something like that at kernel-doc.pl
>>> won't be hard.
>>>
>>> Regards,
>>> Mauro
>>>
>>>> Regards, Joonas
>>>>
>>>> Quoting Mauro Carvalho Chehab (2020-10-13 14:53:59)
>>>>> As reported by Sphinx:
>>>>>
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_oa_wait_unlocked'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_oa_poll_wait'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_oa_read'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_oa_stream_enable'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_oa_stream_disable'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_oa_stream_init'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_read'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_poll_locked'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_poll'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_enable_locked'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_disable_locked'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_ioctl'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_destroy_locked'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_release'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_open_ioctl_locked'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'read_properties_unlocked'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_open_ioctl'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_register'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_unregister'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_add_config_ioctl'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_remove_config_ioctl'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_init'.
>>>>>           ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>>           Declaration is 'i915_perf_fini'.
>>>>>
>>>>> With Sphinx 3, C declarations can't be duplicated anymore,
>>>>> so let's exclude those from the other internals found on
>>>>> i915_perf.c file.
>>>>>
>>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>>>> ---
>>>>>    Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
>>>>>    1 file changed, 25 insertions(+), 4 deletions(-)
>>>>>
>>>>> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
>>>>> index 33cc6ddf8f64..cff1f154b473 100644
>>>>> --- a/Documentation/gpu/i915.rst
>>>>> +++ b/Documentation/gpu/i915.rst
>>>>> @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
>>>>>    .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>>>>       :functions: i915_oa_poll_wait
>>>>>    
>>>>> -All i915 Perf Internals
>>>>> ------------------------
>>>>> +Other i915 Perf Internals
>>>>> +-------------------------
>>>>>    
>>>>> -This section simply includes all currently documented i915 perf internals, in
>>>>> -no particular order, but may include some more minor utilities or platform
>>>>> +This section simply includes all other currently documented i915 perf internals,
>>>>> +in no particular order, but may include some more minor utilities or platform
>>>>>    specific details than found in the more high-level sections.
>>>>>    
>>>>>    .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>>>>       :internal:
>>>>> +   :no-identifiers:
>>>>> +       i915_perf_init
>>>>> +       i915_perf_fini
>>>>> +       i915_perf_register
>>>>> +       i915_perf_unregister
>>>>> +       i915_perf_open_ioctl
>>>>> +       i915_perf_release
>>>>> +       i915_perf_add_config_ioctl
>>>>> +       i915_perf_remove_config_ioctl
>>>>> +       read_properties_unlocked
>>>>> +       i915_perf_open_ioctl_locked
>>>>> +       i915_perf_destroy_locked
>>>>> +       i915_perf_read i915_perf_ioctl
>>>>> +       i915_perf_enable_locked
>>>>> +       i915_perf_disable_locked
>>>>> +       i915_perf_poll i915_perf_poll_locked
>>>>> +       i915_oa_stream_init i915_oa_read
>>>>> +       i915_oa_stream_enable
>>>>> +       i915_oa_stream_disable
>>>>> +       i915_oa_wait_unlocked
>>>>> +       i915_oa_poll_wait
>>>>>    
>>>>>    Style
>>>>>    =====
>>>>> -- 
>>>>> 2.26.2
>>>>>     
>>>
>>> Thanks,
>>> Mauro
>>

Re: [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings

[Lionel Landwerlin]

On 13/10/2020 14:53, Mauro Carvalho Chehab wrote:
> As reported by Sphinx:
>
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_oa_wait_unlocked'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_oa_poll_wait'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_oa_read'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_oa_stream_enable'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_oa_stream_disable'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_oa_stream_init'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_read'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_poll_locked'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_poll'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_enable_locked'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_disable_locked'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_ioctl'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_destroy_locked'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_release'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_open_ioctl_locked'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'read_properties_unlocked'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_open_ioctl'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_register'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_unregister'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_add_config_ioctl'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_remove_config_ioctl'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_init'.
> 	./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> 	Declaration is 'i915_perf_fini'.
>
> With Sphinx 3, C declarations can't be duplicated anymore,
> so let's exclude those from the other internals found on
> i915_perf.c file.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Lionel Landwerlin <lionel.g.landwerlin@intel.com>
> ---
>   Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
>   1 file changed, 25 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 33cc6ddf8f64..cff1f154b473 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
>   .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>      :functions: i915_oa_poll_wait
>   
> -All i915 Perf Internals
> ------------------------
> +Other i915 Perf Internals
> +-------------------------
>   
> -This section simply includes all currently documented i915 perf internals, in
> -no particular order, but may include some more minor utilities or platform
> +This section simply includes all other currently documented i915 perf internals,
> +in no particular order, but may include some more minor utilities or platform
>   specific details than found in the more high-level sections.
>   
>   .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>      :internal:
> +   :no-identifiers:
> +       i915_perf_init
> +       i915_perf_fini
> +       i915_perf_register
> +       i915_perf_unregister
> +       i915_perf_open_ioctl
> +       i915_perf_release
> +       i915_perf_add_config_ioctl
> +       i915_perf_remove_config_ioctl
> +       read_properties_unlocked
> +       i915_perf_open_ioctl_locked
> +       i915_perf_destroy_locked
> +       i915_perf_read i915_perf_ioctl
> +       i915_perf_enable_locked
> +       i915_perf_disable_locked
> +       i915_perf_poll i915_perf_poll_locked
> +       i915_oa_stream_init i915_oa_read
> +       i915_oa_stream_enable
> +       i915_oa_stream_disable
> +       i915_oa_wait_unlocked
> +       i915_oa_poll_wait
>   
>   Style
>   =====