1. 15 Oct, 2020 40 commits
    • Mauro Carvalho Chehab's avatar
      drivers: core: fix kernel-doc markup for dev_err_probe() · 074b3aad
      Mauro Carvalho Chehab authored
      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: a787e540 ("driver core: add device probe log helper")
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      074b3aad
    • Mauro Carvalho Chehab's avatar
      docs: bio: fix a kerneldoc markup · 5cd3ddc1
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      5cd3ddc1
    • Mauro Carvalho Chehab's avatar
      kunit: test.h: solve kernel-doc warnings · 38d9b909
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      38d9b909
    • Mauro Carvalho Chehab's avatar
      block: bio: fix a warning at the kernel-doc markups · 5b874af6
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      5b874af6
    • Mauro Carvalho Chehab's avatar
      docs: powerpc: syscall64-abi.rst: fix a malformed table · 209b44c8
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      209b44c8
    • Mauro Carvalho Chehab's avatar
      drivers: net: hamradio: fix document location · d4dd87f8
      Mauro Carvalho Chehab authored
      The hamradio docs were moved to a different dir.
      Update its location accordingly.
      
      Fixes: 14474950 ("docs: networking: move z8530 to the hw driver section")
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      d4dd87f8
    • Mauro Carvalho Chehab's avatar
      net: appletalk: Kconfig: Fix docs location · edba14eb
      Mauro Carvalho Chehab authored
      The location of ltpc.rst changed. Update it at Kconfig.
      
      Fixes: 4daedf7a ("docs: networking: move AppleTalk / LocalTalk drivers to the hw driver section")
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      edba14eb
    • Mauro Carvalho Chehab's avatar
      dt-bindings: fix references to files converted to yaml · 480017f0
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      480017f0
    • Mauro Carvalho Chehab's avatar
      memblock: get rid of a :c:type leftover · 1bf162e4
      Mauro Carvalho Chehab authored
      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.
      Reviewed-by: default avatarMike Rapoport <rppt@linux.ibm.com>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      1bf162e4
    • Mauro Carvalho Chehab's avatar
      math64.h: kernel-docs: Convert some markups into normal comments · c2a9a645
      Mauro Carvalho Chehab authored
      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: default avatarVincenzo Frascino <vincenzo.frascino@arm.com>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      c2a9a645
    • Mauro Carvalho Chehab's avatar
      media: uAPI: buffer.rst: remove a left-over documentation · 5e44635c
      Mauro Carvalho Chehab authored
      Changeset 129134e5 ("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: 129134e5 ("media: media/v4l2: remove V4L2_FLAG_MEMORY_NON_CONSISTENT flag")
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      5e44635c
    • Mauro Carvalho Chehab's avatar
      docs: zh_CN: amu.rst: fix document title markup · ed159f97
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      ed159f97
    • Mauro Carvalho Chehab's avatar
      docs: infrastructure.rst: exclude device_link_state from device.h · f41f716d
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      f41f716d
    • Mauro Carvalho Chehab's avatar
      docs: conf.py: change the Sphinx 3.x+ text · 14059a38
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      14059a38
    • Mauro Carvalho Chehab's avatar
      docs: conf.py: fix c:function support with Sphinx 3.x · b34b86d7
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      b34b86d7
    • Mauro Carvalho Chehab's avatar
      docs: basics.rst: avoid duplicated C function declaration · a57c3522
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      a57c3522
    • Mauro Carvalho Chehab's avatar
      docs: mei.rst: fix a C expression markup · ccf12273
      Mauro Carvalho Chehab authored
      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: default avatarTomas Winkler <tomas.winkler@intel.com>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      ccf12273
    • Mauro Carvalho Chehab's avatar
      docs: it_IT: hacking.rst: fix a typo on a markup · 366a0765
      Mauro Carvalho Chehab authored
      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: default avatarFederico Vaga <federico.vaga@vaga.pv.it>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      366a0765
    • Mauro Carvalho Chehab's avatar
      docs: devices.rst: fix a C reference markup · 2f27ed75
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      2f27ed75
    • Mauro Carvalho Chehab's avatar
      docs: gpu: i915.rst: Fix several C duplication warnings · 11604da2
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      11604da2
    • Mauro Carvalho Chehab's avatar
      docs: infrastructure.rst: don't include firmware kernel-doc · afe178ad
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      afe178ad
    • Mauro Carvalho Chehab's avatar
      docs: libata.rst: fix a wrong usage of :c:type: tag · b989451b
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      b989451b
    • Mauro Carvalho Chehab's avatar
      docs: kgdb.rst: fix :c:type: usages · 365ff56f
      Mauro Carvalho Chehab authored
      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: default avatarDaniel Thompson <daniel.thompson@linaro.org>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      365ff56f
    • Mauro Carvalho Chehab's avatar
      docs: fpga: replace :c:member: macros · 64d41516
      Mauro Carvalho Chehab authored
      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: default avatarMoritz Fischer <mdf@kernel.org>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      64d41516
    • Mauro Carvalho Chehab's avatar
      docs: writing-an-alsa-driver.rst: fix some bad c:func: markups · 4d9d18ad
      Mauro Carvalho Chehab authored
      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: default avatarTakashi Iwai <tiwai@suse.de>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      4d9d18ad
    • Mauro Carvalho Chehab's avatar
      docs: block: blk-mq.rst: get rid of :c:type · 8ac86734
      Mauro Carvalho Chehab authored
      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: default avatarAndré Almeida <andrealmeid@collabora.com>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      8ac86734
    • Mauro Carvalho Chehab's avatar
      docs: sound: writing-an-alsa-driver.rst: get rid of :c:type · 68735902
      Mauro Carvalho Chehab authored
      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: default avatarTakashi Iwai <tiwai@suse.de>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      68735902
    • Mauro Carvalho Chehab's avatar
      docs: devices.rst: get rid of :c:type macros · 6624d64d
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      6624d64d
    • Mauro Carvalho Chehab's avatar
      docs: fs: fscrypt.rst: get rid of :c:type: tags · 74e2f8d3
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      74e2f8d3
    • Mauro Carvalho Chehab's avatar
      docs: pstore-blk.rst: fix kernel-doc tags · b30fd8e9
      Mauro Carvalho Chehab authored
      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: default avatarKees Cook <keescook@chromium.org>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      b30fd8e9
    • Mauro Carvalho Chehab's avatar
      docs: basics.rst: get rid of rcu kernel-doc macros · 044248db
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      044248db
    • Mauro Carvalho Chehab's avatar
      docs: device_link.rst: remove duplicated kernel-doc include · 58bc57b0
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      58bc57b0
    • Mauro Carvalho Chehab's avatar
      docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup · 3048ba60
      Mauro Carvalho Chehab authored
      This is already included at scsi.rst. So, remove the duplication,
      in order to avoid Sphinx warnings.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      3048ba60
    • Mauro Carvalho Chehab's avatar
      docs: basics.rst: move kernel-doc workqueue markups to workqueue.rst · c9e3d519
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      c9e3d519
    • Mauro Carvalho Chehab's avatar
      docs: remove sound API duplication · 1842c96b
      Mauro Carvalho Chehab authored
      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: default avatarTakashi Iwai <tiwai@suse.de>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      1842c96b
    • Mauro Carvalho Chehab's avatar
      docs: kernel-api.rst: drop kernel/irq/manage.c kernel-doc tag · f182e7fd
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      f182e7fd
    • Mauro Carvalho Chehab's avatar
      docs: genericirq.rst: don't document chip.c functions twice · 9b9b0bda
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      9b9b0bda
    • Mauro Carvalho Chehab's avatar
      docs: net: ieee802154.rst: fix C expressions · 640e3f80
      Mauro Carvalho Chehab authored
      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: default avatarDavid S. Miller <davem@davemloft.net>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      640e3f80
    • Mauro Carvalho Chehab's avatar
      docs: it_IT: fix namespace collisions at locking.rst · 71a8156e
      Mauro Carvalho Chehab authored
      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: default avatarFederico Vaga <federico.vaga@vaga.pv.it>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      71a8156e
    • Mauro Carvalho Chehab's avatar
      docs: trace-uses.rst: remove bogus c-domain tags · d7faad15
      Mauro Carvalho Chehab authored
      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: default avatarKamalesh Babulal <kamalesh@linux.vnet.ibm.com>
      Acked-by: default avatarSteven Rostedt (VMware) <rostedt@goodmis.org>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
      d7faad15