Kernel-doc has always be limited to a probably bad documented
rule:
The kernel-doc markups should appear *imediatelly before* the
function or data structure that it documents.
On other words, if a C file would contain something like this:
/**
* foo - function foo
* @args: foo args
*/
static inline void bar(int args);
/**
* bar - function bar
* @args: foo args
*/
static inline void foo(void *args);
The output (in ReST format) will be:
.. c:function:: void bar (int args)
function foo
**Parameters**
``int args``
foo args
.. c:function:: void foo (void *args)
function bar
**Parameters**
``void *args``
foo args
Which is clearly a wrong result. Before this changeset,
not even a warning is produced on such cases.
As placing such markups just before the documented
data is a common practice, on most cases this is fine.
However, as patches touch things, identifiers may be
renamed, and people may forget to update the kernel-doc
markups to follow such changes.
This has been happening for quite a while, as there are
lots of files with kernel-doc problems.
This series address those issues and add a file at the
end that will enforce that the identifier will match the
kernel-doc markup, avoiding this problem from
keep happening as time goes by.
This series is based on current upstream tree.
@maintainers: feel free to pick the patches and
apply them directly on your trees, as all patches on
this series are independent from the other ones.
Jon,
The first patch contains a trivial bug fix that I got
at kernel-doc script while writing this series. Feel
free to pick it anytime.
The last one should likely be applied only after we
have everything else in place, as otherwise it will
produce hundreds of warnings, and the broken
markups will be ignored.
Mauro Carvalho Chehab (56):
scripts: kernel-doc: fix typedef parsing
drm: amdgpu_dm: fix a typo
amdgpu: fix a few kernel-doc markup issues
drm: drm_print.h: fix kernel-doc markups
s390: fix kernel-doc markups
x86: mtrr: fix a kernel-doc markup
block: blk-mq: fix a kernel-doc markup
ata: fix some kernel-doc markups
drivers: base: fix some kernel-doc markups
EDAC: fix some kernel-doc markups
drm/amdgpu: fix some kernel-doc markups
drm: fix some kernel-doc markups
HSI: fix a kernel-doc markup
IB: fix kernel-doc markups
media: fix kernel-doc markups
mei: bus: fix a kernel-doc markup
mtd: rawnand: fix a kernel-doc markup
net: phy: fix kernel-doc markups
net: datagram: fix some kernel-doc markups
net: core: fix some kernel-doc markups
mac80211: fix kernel-doc markups
parport: fix a kernel-doc markup
PCI: fix kernel-doc markups
PNP: fix kernel-doc markups
rapidio: fix kernel-doc a markup
regulator: fix a kernel-doc markup
scsi: fix some kernel-doc markups
slimbus: fix a kernel-doc markup
spi: fix a typo inside a kernel-doc markup
uio: fix some kernel-doc markups
usb: dwc3: fix kernel-doc markups
video: fix some kernel-doc markups
vme: fix two kernel-doc markups
fs: fix kernel-doc markups
jbd2: fix kernel-doc markups
locks: fix a typo at a kernel-doc markup
pstore/zone: fix a kernel-doc markup
clk: fix a kernel-doc markup
completion: fix kernel-doc markups
firmware: stratix10-svc: fix kernel-doc markups
connector: fix a kernel-doc markup
lib/crc7: fix a kernel-doc markup
hrtimer: fix kernel-doc markups
genirq: fix kernel-doc markups
iio: fix a kernel-doc markup
list: fix a typo at the kernel-doc markup
memblock: fix kernel-doc markups
sound: fix kernel-doc markups
refcount.h: fix a kernel-doc markup
w1: fix a kernel-doc markup
audit: fix a kernel-doc markup
resource: fix kernel-doc markups
shed: fix kernel-doc markup
mm: fix kernel-doc markups
selftests: kselftest_harness.h: partially fix kernel-doc markups
scrpits: kernel-doc: validate kernel-doc markup with the actual names
arch/s390/include/asm/ccwdev.h | 2 +-
arch/s390/include/asm/cio.h | 2 +-
arch/x86/kernel/cpu/mtrr/mtrr.c | 3 +-
block/blk-mq.c | 2 +-
drivers/ata/libata-core.c | 2 +-
drivers/ata/libata-eh.c | 2 +-
drivers/ata/libata-scsi.c | 2 +-
drivers/base/class.c | 2 +-
drivers/base/devres.c | 2 +-
drivers/base/firmware_loader/fallback.c | 2 +-
drivers/edac/edac_device.h | 11 ++-
drivers/gpu/drm/amd/amdgpu/amdgpu_device.c | 8 ++-
drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c | 2 +-
drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 2 +-
.../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 2 +-
.../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h | 6 +-
drivers/gpu/drm/drm_atomic_state_helper.c | 2 +-
drivers/gpu/drm/drm_connector.c | 3 +-
drivers/gpu/drm/drm_dp_helper.c | 2 +-
drivers/gpu/drm/drm_framebuffer.c | 2 +-
drivers/gpu/drm/drm_gem.c | 4 +-
drivers/gpu/drm/drm_gem_vram_helper.c | 2 +-
drivers/gpu/drm/drm_mode_object.c | 2 +-
drivers/gpu/drm/drm_modes.c | 4 +-
drivers/gpu/drm/drm_scdc_helper.c | 2 +-
drivers/gpu/drm/i915/display/intel_dpll_mgr.c | 2 +-
drivers/gpu/drm/i915/i915_gem_evict.c | 2 +-
drivers/gpu/drm/i915/i915_perf.c | 8 ++-
drivers/gpu/drm/scheduler/sched_main.c | 2 +-
drivers/gpu/drm/v3d/v3d_sched.c | 2 +-
drivers/gpu/drm/vc4/vc4_bo.c | 2 +-
drivers/hsi/hsi_core.c | 2 +-
drivers/infiniband/core/cm.c | 5 +-
drivers/infiniband/core/cq.c | 4 +-
drivers/infiniband/core/iwpm_util.h | 2 +-
drivers/infiniband/core/sa_query.c | 3 +-
drivers/infiniband/core/verbs.c | 4 +-
drivers/infiniband/sw/rdmavt/ah.c | 2 +-
drivers/infiniband/sw/rdmavt/mcast.c | 12 ++--
drivers/infiniband/sw/rdmavt/qp.c | 8 +--
drivers/infiniband/ulp/iser/iscsi_iser.c | 2 +-
.../infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +-
.../ulp/opa_vnic/opa_vnic_vema_iface.c | 2 +-
drivers/infiniband/ulp/srpt/ib_srpt.h | 2 +-
drivers/media/dvb-frontends/ascot2e.h | 2 +-
drivers/media/dvb-frontends/cxd2820r.h | 2 +-
drivers/media/dvb-frontends/drxk.h | 2 +-
drivers/media/dvb-frontends/dvb-pll.h | 2 +-
drivers/media/dvb-frontends/helene.h | 4 +-
drivers/media/dvb-frontends/horus3a.h | 2 +-
drivers/media/dvb-frontends/ix2505v.h | 4 +-
drivers/media/dvb-frontends/m88ds3103.h | 2 +-
drivers/media/dvb-frontends/mb86a20s.h | 2 +-
drivers/media/dvb-frontends/stb6000.h | 2 +-
drivers/media/dvb-frontends/tda826x.h | 2 +-
drivers/media/dvb-frontends/zl10036.h | 4 +-
drivers/misc/mei/bus.c | 2 +-
drivers/mtd/nand/raw/nand_bbt.c | 2 +-
drivers/net/phy/mdio_bus.c | 2 +-
drivers/net/phy/phy-c45.c | 2 +-
drivers/net/phy/phy.c | 2 +-
drivers/net/phy/phy_device.c | 2 +-
drivers/net/phy/phylink.c | 2 +-
drivers/parport/share.c | 2 +-
drivers/pci/p2pdma.c | 10 +--
drivers/pci/pci-driver.c | 4 +-
drivers/pci/pci.c | 2 +-
drivers/pci/probe.c | 4 +-
drivers/pci/slot.c | 5 +-
drivers/pnp/core.c | 4 +-
drivers/rapidio/rio.c | 2 +-
drivers/regulator/core.c | 2 +-
drivers/scsi/iscsi_tcp.c | 4 +-
drivers/scsi/libiscsi.c | 2 +-
drivers/scsi/scsi_devinfo.c | 3 +-
drivers/scsi/scsi_lib.c | 6 +-
drivers/scsi/scsi_transport_fc.c | 2 +-
drivers/slimbus/slimbus.h | 2 +-
drivers/spi/spi.c | 6 +-
.../staging/media/ipu3/include/intel-ipu3.h | 8 +--
drivers/uio/uio.c | 4 +-
drivers/usb/dwc3/core.c | 2 +-
drivers/usb/dwc3/core.h | 2 +-
drivers/usb/gadget/composite.c | 2 +-
drivers/usb/typec/mux.c | 2 +-
drivers/video/fbdev/core/fbcmap.c | 2 +-
drivers/video/hdmi.c | 3 +-
drivers/vme/vme.c | 4 +-
fs/dcache.c | 72 +++++++++----------
fs/inode.c | 4 +-
fs/jbd2/journal.c | 34 ++++-----
fs/jbd2/transaction.c | 31 ++++----
fs/locks.c | 2 +-
fs/pstore/zone.c | 2 +-
fs/seq_file.c | 5 +-
fs/super.c | 12 ++--
include/drm/drm_atomic_helper.h | 4 +-
include/drm/drm_connector.h | 2 +-
include/drm/drm_device.h | 2 +-
include/drm/drm_dsc.h | 3 +-
include/drm/drm_gem_vram_helper.h | 8 +--
include/drm/drm_print.h | 20 +++++-
include/linux/clk.h | 2 +-
include/linux/completion.h | 10 ++-
include/linux/connector.h | 2 +-
include/linux/device/class.h | 14 ++++
include/linux/edac.h | 4 +-
.../firmware/intel/stratix10-svc-client.h | 10 +--
include/linux/hrtimer.h | 6 +-
include/linux/iio/trigger.h | 2 +-
include/linux/jbd2.h | 2 +-
include/linux/list.h | 2 +-
include/linux/memblock.h | 4 +-
include/linux/mtd/rawnand.h | 3 +-
include/linux/netdevice.h | 11 ++-
include/linux/parport.h | 31 ++++++++
include/linux/refcount.h | 2 +-
include/linux/uio_driver.h | 16 +++++
include/linux/usb/composite.h | 2 +-
include/linux/w1.h | 2 +-
include/media/dvbdev.h | 2 +-
include/media/v4l2-ctrls.h | 2 +-
include/media/v4l2-dev.h | 4 +-
include/media/v4l2-device.h | 2 +-
include/media/v4l2-dv-timings.h | 2 +-
include/media/v4l2-fwnode.h | 2 +-
include/media/v4l2-mediabus.h | 6 +-
include/media/v4l2-subdev.h | 2 +-
include/media/videobuf2-core.h | 2 +-
include/net/cfg80211.h | 9 +--
include/net/mac80211.h | 7 +-
include/rdma/ib_verbs.h | 11 +++
include/sound/core.h | 3 +-
include/sound/pcm.h | 4 +-
include/uapi/drm/amdgpu_drm.h | 2 +-
include/uapi/sound/compress_offload.h | 2 +-
kernel/audit.c | 2 +-
kernel/irq/chip.c | 2 +-
kernel/irq/generic-chip.c | 2 +-
kernel/resource.c | 24 ++++---
kernel/sched/core.c | 16 ++---
kernel/sched/fair.c | 3 +-
kernel/time/hrtimer.c | 2 +-
lib/crc7.c | 2 +-
mm/gup.c | 24 ++++---
mm/page_alloc.c | 16 ++---
mm/truncate.c | 10 ++-
net/core/datagram.c | 2 +-
net/core/dev.c | 4 +-
net/core/skbuff.c | 2 +-
net/ethernet/eth.c | 6 +-
net/mac80211/sta_info.h | 9 ++-
net/sunrpc/rpc_pipe.c | 3 +-
scripts/kernel-doc | 64 ++++++++++++-----
sound/core/control.c | 4 +-
sound/core/pcm_dmaengine.c | 3 +-
sound/core/pcm_lib.c | 2 +-
sound/core/pcm_native.c | 4 +-
sound/soc/soc-core.c | 2 +-
sound/soc/soc-dapm.c | 2 +-
tools/testing/selftests/kselftest_harness.h | 66 ++++++++---------
161 files changed, 558 insertions(+), 382 deletions(-)
--
2.26.2
Some functions have different names between their prototypes
and the kernel-doc markup.
Others need to be fixed, as kernel-doc markups should use this format:
identifier - description
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/infiniband/core/cm.c | 5 +++--
drivers/infiniband/core/cq.c | 4 ++--
drivers/infiniband/core/iwpm_util.h | 2 +-
drivers/infiniband/core/sa_query.c | 3 ++-
drivers/infiniband/core/verbs.c | 4 ++--
drivers/infiniband/sw/rdmavt/ah.c | 2 +-
drivers/infiniband/sw/rdmavt/mcast.c | 12 ++++++------
drivers/infiniband/sw/rdmavt/qp.c | 8 ++++----
drivers/infiniband/ulp/iser/iscsi_iser.c | 2 +-
drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +-
.../infiniband/ulp/opa_vnic/opa_vnic_vema_iface.c | 2 +-
drivers/infiniband/ulp/srpt/ib_srpt.h | 2 +-
include/rdma/ib_verbs.h | 11 +++++++++++
13 files changed, 36 insertions(+), 23 deletions(-)
diff --git a/drivers/infiniband/core/cm.c b/drivers/infiniband/core/cm.c
index 5740d1ba3568..2dfbfdd6cc57 100644
--- a/drivers/infiniband/core/cm.c
+++ b/drivers/infiniband/core/cm.c
@@ -1251,7 +1251,8 @@ int ib_cm_listen(struct ib_cm_id *cm_id, __be64 service_id, __be64 service_mask)
EXPORT_SYMBOL(ib_cm_listen);
/**
- * Create a new listening ib_cm_id and listen on the given service ID.
+ * ib_cm_insert_listen - Create a new listening ib_cm_id and listen on
+ * the given service ID.
*
* If there's an existing ID listening on that same device and service ID,
* return it.
@@ -1764,7 +1765,7 @@ static u16 cm_get_bth_pkey(struct cm_work *work)
}
/**
- * Convert OPA SGID to IB SGID
+ * cm_opa_to_ib_sgid - Convert OPA SGID to IB SGID
* ULPs (such as IPoIB) do not understand OPA GIDs and will
* reject them as the local_gid will not match the sgid. Therefore,
* change the pathrec's SGID to an IB SGID.
diff --git a/drivers/infiniband/core/cq.c b/drivers/infiniband/core/cq.c
index 12ebacf52958..d4248bbe74da 100644
--- a/drivers/infiniband/core/cq.c
+++ b/drivers/infiniband/core/cq.c
@@ -123,7 +123,7 @@ static int __ib_process_cq(struct ib_cq *cq, int budget, struct ib_wc *wcs,
}
/**
- * ib_process_direct_cq - process a CQ in caller context
+ * ib_process_cq_direct - process a CQ in caller context
* @cq: CQ to process
* @budget: number of CQEs to poll for
*
@@ -197,7 +197,7 @@ static void ib_cq_completion_workqueue(struct ib_cq *cq, void *private)
}
/**
- * __ib_alloc_cq allocate a completion queue
+ * __ib_alloc_cq - allocate a completion queue
* @dev: device to allocate the CQ for
* @private: driver private data, accessible from cq->cq_context
* @nr_cqe: number of CQEs to allocate
diff --git a/drivers/infiniband/core/iwpm_util.h b/drivers/infiniband/core/iwpm_util.h
index 1bf87d9fd0bd..eeb8e6010907 100644
--- a/drivers/infiniband/core/iwpm_util.h
+++ b/drivers/infiniband/core/iwpm_util.h
@@ -141,7 +141,7 @@ int iwpm_wait_complete_req(struct iwpm_nlmsg_request *nlmsg_request);
int iwpm_get_nlmsg_seq(void);
/**
- * iwpm_add_reminfo - Add remote address info of the connecting peer
+ * iwpm_add_remote_info - Add remote address info of the connecting peer
* to the remote info hash table
* @reminfo: The remote info to be added
*/
diff --git a/drivers/infiniband/core/sa_query.c b/drivers/infiniband/core/sa_query.c
index 8c930bf1df89..89a831fa1885 100644
--- a/drivers/infiniband/core/sa_query.c
+++ b/drivers/infiniband/core/sa_query.c
@@ -1435,7 +1435,8 @@ enum opa_pr_supported {
};
/**
- * Check if current PR query can be an OPA query.
+ * opa_pr_query_possible - Check if current PR query can be an OPA query.
+ *
* Retuns PR_NOT_SUPPORTED if a path record query is not
* possible, PR_OPA_SUPPORTED if an OPA path record query
* is possible and PR_IB_SUPPORTED if an IB path record
diff --git a/drivers/infiniband/core/verbs.c b/drivers/infiniband/core/verbs.c
index 740f8454b6b4..89f379cd7909 100644
--- a/drivers/infiniband/core/verbs.c
+++ b/drivers/infiniband/core/verbs.c
@@ -244,7 +244,7 @@ EXPORT_SYMBOL(rdma_port_get_link_layer);
/* Protection domains */
/**
- * ib_alloc_pd - Allocates an unused protection domain.
+ * __ib_alloc_pd - Allocates an unused protection domain.
* @device: The device on which to allocate the protection domain.
* @flags: protection domain flags
* @caller: caller's build-time module name
@@ -1662,7 +1662,7 @@ static bool is_qp_type_connected(const struct ib_qp *qp)
qp->qp_type == IB_QPT_XRC_TGT);
}
-/**
+/*
* IB core internal function to perform QP attributes modification.
*/
static int _ib_modify_qp(struct ib_qp *qp, struct ib_qp_attr *attr,
diff --git a/drivers/infiniband/sw/rdmavt/ah.c b/drivers/infiniband/sw/rdmavt/ah.c
index b938c4ffa99a..3c175bd4ad55 100644
--- a/drivers/infiniband/sw/rdmavt/ah.c
+++ b/drivers/infiniband/sw/rdmavt/ah.c
@@ -126,7 +126,7 @@ int rvt_create_ah(struct ib_ah *ibah, struct rdma_ah_init_attr *init_attr,
}
/**
- * rvt_destory_ah - Destory an address handle
+ * rvt_destroy_ah - Destory an address handle
* @ibah: address handle
* @destroy_flags: destroy address handle flags (see enum rdma_destroy_ah_flags)
*
diff --git a/drivers/infiniband/sw/rdmavt/mcast.c b/drivers/infiniband/sw/rdmavt/mcast.c
index dd11c6fcd060..5233a63d99a6 100644
--- a/drivers/infiniband/sw/rdmavt/mcast.c
+++ b/drivers/infiniband/sw/rdmavt/mcast.c
@@ -54,7 +54,7 @@
#include "mcast.h"
/**
- * rvt_driver_mcast - init resources for multicast
+ * rvt_driver_mcast_init - init resources for multicast
* @rdi: rvt dev struct
*
* This is per device that registers with rdmavt
@@ -69,7 +69,7 @@ void rvt_driver_mcast_init(struct rvt_dev_info *rdi)
}
/**
- * mcast_qp_alloc - alloc a struct to link a QP to mcast GID struct
+ * rvt_mcast_qp_alloc - alloc a struct to link a QP to mcast GID struct
* @qp: the QP to link
*/
static struct rvt_mcast_qp *rvt_mcast_qp_alloc(struct rvt_qp *qp)
@@ -98,7 +98,7 @@ static void rvt_mcast_qp_free(struct rvt_mcast_qp *mqp)
}
/**
- * mcast_alloc - allocate the multicast GID structure
+ * rvt_mcast_alloc - allocate the multicast GID structure
* @mgid: the multicast GID
* @lid: the muilticast LID (host order)
*
@@ -181,7 +181,7 @@ struct rvt_mcast *rvt_mcast_find(struct rvt_ibport *ibp, union ib_gid *mgid,
EXPORT_SYMBOL(rvt_mcast_find);
/**
- * mcast_add - insert mcast GID into table and attach QP struct
+ * rvt_mcast_add - insert mcast GID into table and attach QP struct
* @mcast: the mcast GID table
* @mqp: the QP to attach
*
@@ -426,8 +426,8 @@ int rvt_detach_mcast(struct ib_qp *ibqp, union ib_gid *gid, u16 lid)
}
/**
- *rvt_mast_tree_empty - determine if any qps are attached to any mcast group
- *@rdi: rvt dev struct
+ * rvt_mcast_tree_empty - determine if any qps are attached to any mcast group
+ * @rdi: rvt dev struct
*
* Return: in use count
*/
diff --git a/drivers/infiniband/sw/rdmavt/qp.c b/drivers/infiniband/sw/rdmavt/qp.c
index ee48befc8978..a0cdde8a2335 100644
--- a/drivers/infiniband/sw/rdmavt/qp.c
+++ b/drivers/infiniband/sw/rdmavt/qp.c
@@ -1823,7 +1823,7 @@ int rvt_query_qp(struct ib_qp *ibqp, struct ib_qp_attr *attr,
}
/**
- * rvt_post_receive - post a receive on a QP
+ * rvt_post_recv - post a receive on a QP
* @ibqp: the QP to post the receive on
* @wr: the WR to post
* @bad_wr: the first bad WR is put here
@@ -2245,7 +2245,7 @@ int rvt_post_send(struct ib_qp *ibqp, const struct ib_send_wr *wr,
}
/**
- * rvt_post_srq_receive - post a receive on a shared receive queue
+ * rvt_post_srq_recv - post a receive on a shared receive queue
* @ibsrq: the SRQ to post the receive on
* @wr: the list of work requests to post
* @bad_wr: A pointer to the first WR to cause a problem is put here
@@ -2497,7 +2497,7 @@ int rvt_get_rwqe(struct rvt_qp *qp, bool wr_id_only)
EXPORT_SYMBOL(rvt_get_rwqe);
/**
- * qp_comm_est - handle trap with QP established
+ * rvt_comm_est - handle trap with QP established
* @qp: the QP
*/
void rvt_comm_est(struct rvt_qp *qp)
@@ -2943,7 +2943,7 @@ static enum ib_wc_status loopback_qp_drop(struct rvt_ibport *rvp,
}
/**
- * ruc_loopback - handle UC and RC loopback requests
+ * rvt_ruc_loopback - handle UC and RC loopback requests
* @sqp: the sending QP
*
* This is called from rvt_do_send() to forward a WQE addressed to the same HFI
diff --git a/drivers/infiniband/ulp/iser/iscsi_iser.c b/drivers/infiniband/ulp/iser/iscsi_iser.c
index 3690e28cc7ea..84cebf937680 100644
--- a/drivers/infiniband/ulp/iser/iscsi_iser.c
+++ b/drivers/infiniband/ulp/iser/iscsi_iser.c
@@ -739,7 +739,7 @@ iscsi_iser_set_param(struct iscsi_cls_conn *cls_conn,
}
/**
- * iscsi_iser_set_param() - set class connection parameter
+ * iscsi_iser_conn_get_stats() - set class connection parameter
* @cls_conn: iscsi class connection
* @stats: iscsi stats to output
*
diff --git a/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h b/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
index f64519872297..012fc27c5c93 100644
--- a/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
+++ b/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
@@ -437,7 +437,7 @@ struct opa_veswport_trap {
} __packed;
/**
- * struct opa_vnic_iface_macs_entry - single entry in the mac list
+ * struct opa_vnic_iface_mac_entry - single entry in the mac list
* @mac_addr: MAC address
*/
struct opa_vnic_iface_mac_entry {
diff --git a/drivers/infiniband/ulp/opa_vnic/opa_vnic_vema_iface.c b/drivers/infiniband/ulp/opa_vnic/opa_vnic_vema_iface.c
index 868b5aec1537..292c037aa239 100644
--- a/drivers/infiniband/ulp/opa_vnic/opa_vnic_vema_iface.c
+++ b/drivers/infiniband/ulp/opa_vnic/opa_vnic_vema_iface.c
@@ -74,7 +74,7 @@ void opa_vnic_vema_report_event(struct opa_vnic_adapter *adapter, u8 event)
}
/**
- * opa_vnic_get_error_counters - get summary counters
+ * opa_vnic_get_summary_counters - get summary counters
* @adapter: vnic port adapter
* @cntrs: pointer to destination summary counters structure
*
diff --git a/drivers/infiniband/ulp/srpt/ib_srpt.h b/drivers/infiniband/ulp/srpt/ib_srpt.h
index bdeb010efee6..76e66f630c17 100644
--- a/drivers/infiniband/ulp/srpt/ib_srpt.h
+++ b/drivers/infiniband/ulp/srpt/ib_srpt.h
@@ -347,7 +347,7 @@ struct srpt_nexus {
};
/**
- * struct srpt_port_attib - attributes for SRPT port
+ * struct srpt_port_attrib - attributes for SRPT port
* @srp_max_rdma_size: Maximum size of SRP RDMA transfers for new connections.
* @srp_max_rsp_size: Maximum size of SRP response messages in bytes.
* @srp_sq_size: Shared receive queue (SRQ) size.
diff --git a/include/rdma/ib_verbs.h b/include/rdma/ib_verbs.h
index 9bf6c319a670..5837bf0ac451 100644
--- a/include/rdma/ib_verbs.h
+++ b/include/rdma/ib_verbs.h
@@ -3430,6 +3430,17 @@ enum ib_pd_flags {
struct ib_pd *__ib_alloc_pd(struct ib_device *device, unsigned int flags,
const char *caller);
+/**
+ * ib_alloc_pd - Allocates an unused protection domain.
+ * @device: The device on which to allocate the protection domain.
+ * @flags: protection domain flags
+ *
+ * A protection domain object provides an association between QPs, shared
+ * receive queues, address handles, memory regions, and memory windows.
+ *
+ * Every PD has a local_dma_lkey which can be used as the lkey value for local
+ * memory operations.
+ */
#define ib_alloc_pd(device, flags) \
__ib_alloc_pd((device), (flags), KBUILD_MODNAME)
--
2.26.2
Fix a typo:
blk_mq_run_hw_queue -> blk_mq_run_hw_queues
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
block/blk-mq.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/block/blk-mq.c b/block/blk-mq.c
index 696450257ac1..bca2e3962262 100644
--- a/block/blk-mq.c
+++ b/block/blk-mq.c
@@ -1664,7 +1664,7 @@ void blk_mq_run_hw_queue(struct blk_mq_hw_ctx *hctx, bool async)
EXPORT_SYMBOL(blk_mq_run_hw_queue);
/**
- * blk_mq_run_hw_queue - Run all hardware queues in a request queue.
+ * blk_mq_run_hw_queues - Run all hardware queues in a request queue.
* @q: Pointer to the request queue to run.
* @async: If we want to run the queue asynchronously.
*/
--
2.26.2
Some identifiers have different names between their prototypes
and the kernel-doc markup.
Others need to be fixed, as kernel-doc markups should use this format:
identifier - description
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/gpu/drm/drm_atomic_state_helper.c | 2 +-
drivers/gpu/drm/drm_connector.c | 3 ++-
drivers/gpu/drm/drm_dp_helper.c | 2 +-
drivers/gpu/drm/drm_framebuffer.c | 2 +-
drivers/gpu/drm/drm_gem.c | 4 ++--
drivers/gpu/drm/drm_gem_vram_helper.c | 2 +-
drivers/gpu/drm/drm_mode_object.c | 2 +-
drivers/gpu/drm/drm_modes.c | 4 ++--
drivers/gpu/drm/drm_scdc_helper.c | 2 +-
drivers/gpu/drm/i915/display/intel_dpll_mgr.c | 2 +-
drivers/gpu/drm/i915/i915_gem_evict.c | 2 +-
drivers/gpu/drm/i915/i915_perf.c | 8 +++++---
drivers/gpu/drm/scheduler/sched_main.c | 2 +-
drivers/gpu/drm/v3d/v3d_sched.c | 2 +-
drivers/gpu/drm/vc4/vc4_bo.c | 2 +-
include/drm/drm_atomic_helper.h | 4 ++--
include/drm/drm_connector.h | 2 +-
include/drm/drm_device.h | 2 +-
include/drm/drm_dsc.h | 3 ++-
include/drm/drm_gem_vram_helper.h | 8 ++++----
20 files changed, 32 insertions(+), 28 deletions(-)
diff --git a/drivers/gpu/drm/drm_atomic_state_helper.c b/drivers/gpu/drm/drm_atomic_state_helper.c
index 9ad74045158e..ddcf5c2c8e6a 100644
--- a/drivers/gpu/drm/drm_atomic_state_helper.c
+++ b/drivers/gpu/drm/drm_atomic_state_helper.c
@@ -543,7 +543,7 @@ void drm_atomic_helper_connector_destroy_state(struct drm_connector *connector,
EXPORT_SYMBOL(drm_atomic_helper_connector_destroy_state);
/**
- * __drm_atomic_helper_private_duplicate_state - copy atomic private state
+ * __drm_atomic_helper_private_obj_duplicate_state - copy atomic private state
* @obj: CRTC object
* @state: new private object state
*
diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
index 717c4e7271b0..9dde11466cc2 100644
--- a/drivers/gpu/drm/drm_connector.c
+++ b/drivers/gpu/drm/drm_connector.c
@@ -1427,7 +1427,8 @@ void drm_hdmi_avi_infoframe_content_type(struct hdmi_avi_infoframe *frame,
EXPORT_SYMBOL(drm_hdmi_avi_infoframe_content_type);
/**
- * drm_mode_attach_tv_margin_properties - attach TV connector margin properties
+ * drm_connector_attach_tv_margin_properties - attach TV connector margin
+ * properties
* @connector: DRM connector
*
* Called by a driver when it needs to attach TV margin props to a connector.
diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
index deeed73f4ed6..485c3e78ba98 100644
--- a/drivers/gpu/drm/drm_dp_helper.c
+++ b/drivers/gpu/drm/drm_dp_helper.c
@@ -1084,7 +1084,7 @@ drm_dp_subconnector_type(const u8 dpcd[DP_RECEIVER_CAP_SIZE],
EXPORT_SYMBOL(drm_dp_subconnector_type);
/**
- * drm_mode_set_dp_subconnector_property - set subconnector for DP connector
+ * drm_dp_set_subconnector_property - set subconnector for DP connector
* @connector: connector to set property on
* @status: connector status
* @dpcd: DisplayPort configuration data
diff --git a/drivers/gpu/drm/drm_framebuffer.c b/drivers/gpu/drm/drm_framebuffer.c
index 2f5b0c2bb0fe..aca62ed51e82 100644
--- a/drivers/gpu/drm/drm_framebuffer.c
+++ b/drivers/gpu/drm/drm_framebuffer.c
@@ -552,7 +552,7 @@ int drm_mode_getfb(struct drm_device *dev,
}
/**
- * drm_mode_getfb2 - get extended FB info
+ * drm_mode_getfb2_ioctl - get extended FB info
* @dev: drm device for the ioctl
* @data: data pointer for the ioctl
* @file_priv: drm file for the ioctl call
diff --git a/drivers/gpu/drm/drm_gem.c b/drivers/gpu/drm/drm_gem.c
index 19d73868490e..74af32106cae 100644
--- a/drivers/gpu/drm/drm_gem.c
+++ b/drivers/gpu/drm/drm_gem.c
@@ -873,7 +873,7 @@ drm_gem_flink_ioctl(struct drm_device *dev, void *data,
}
/**
- * drm_gem_open - implementation of the GEM_OPEN ioctl
+ * drm_gem_open_ioctl - implementation of the GEM_OPEN ioctl
* @dev: drm_device
* @data: ioctl data
* @file_priv: drm file-private structure
@@ -918,7 +918,7 @@ drm_gem_open_ioctl(struct drm_device *dev, void *data,
}
/**
- * gem_gem_open - initalizes GEM file-private structures at devnode open time
+ * drm_gem_open - initalizes GEM file-private structures at devnode open time
* @dev: drm_device which is being opened by userspace
* @file_private: drm file-private structure to set up
*
diff --git a/drivers/gpu/drm/drm_gem_vram_helper.c b/drivers/gpu/drm/drm_gem_vram_helper.c
index 50cad0e4a92e..e81f6954d233 100644
--- a/drivers/gpu/drm/drm_gem_vram_helper.c
+++ b/drivers/gpu/drm/drm_gem_vram_helper.c
@@ -640,7 +640,7 @@ static void drm_gem_vram_object_free(struct drm_gem_object *gem)
*/
/**
- * drm_gem_vram_driver_create_dumb() - \
+ * drm_gem_vram_driver_dumb_create() - \
Implements &struct drm_driver.dumb_create
* @file: the DRM file
* @dev: the DRM device
diff --git a/drivers/gpu/drm/drm_mode_object.c b/drivers/gpu/drm/drm_mode_object.c
index db05f386a709..b26588b52795 100644
--- a/drivers/gpu/drm/drm_mode_object.c
+++ b/drivers/gpu/drm/drm_mode_object.c
@@ -115,7 +115,7 @@ void drm_mode_object_unregister(struct drm_device *dev,
}
/**
- * drm_lease_required - check types which must be leased to be used
+ * drm_mode_object_lease_required - check types which must be leased to be used
* @type: type of object
*
* Returns whether the provided type of drm_mode_object must
diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
index 501b4fe55a3d..33fb2f05ce66 100644
--- a/drivers/gpu/drm/drm_modes.c
+++ b/drivers/gpu/drm/drm_modes.c
@@ -1889,7 +1889,7 @@ drm_mode_create_from_cmdline_mode(struct drm_device *dev,
EXPORT_SYMBOL(drm_mode_create_from_cmdline_mode);
/**
- * drm_crtc_convert_to_umode - convert a drm_display_mode into a modeinfo
+ * drm_mode_convert_to_umode - convert a drm_display_mode into a modeinfo
* @out: drm_mode_modeinfo struct to return to the user
* @in: drm_display_mode to use
*
@@ -1941,7 +1941,7 @@ void drm_mode_convert_to_umode(struct drm_mode_modeinfo *out,
}
/**
- * drm_crtc_convert_umode - convert a modeinfo into a drm_display_mode
+ * drm_mode_convert_umode - convert a modeinfo into a drm_display_mode
* @dev: drm device
* @out: drm_display_mode to return to the user
* @in: drm_mode_modeinfo to use
diff --git a/drivers/gpu/drm/drm_scdc_helper.c b/drivers/gpu/drm/drm_scdc_helper.c
index 311e71bbba5b..991b8c86d78d 100644
--- a/drivers/gpu/drm/drm_scdc_helper.c
+++ b/drivers/gpu/drm/drm_scdc_helper.c
@@ -125,7 +125,7 @@ ssize_t drm_scdc_write(struct i2c_adapter *adapter, u8 offset,
EXPORT_SYMBOL(drm_scdc_write);
/**
- * drm_scdc_check_scrambling_status - what is status of scrambling?
+ * drm_scdc_get_scrambling_status - what is status of scrambling?
* @adapter: I2C adapter for DDC channel
*
* Reads the scrambler status over SCDC, and checks the
diff --git a/drivers/gpu/drm/i915/display/intel_dpll_mgr.c b/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
index e08684e34078..8abbae8f8808 100644
--- a/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
+++ b/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
@@ -4531,7 +4531,7 @@ void intel_dpll_sanitize_state(struct drm_i915_private *i915)
}
/**
- * intel_shared_dpll_dump_hw_state - write hw_state to dmesg
+ * intel_dpll_dump_hw_state - write hw_state to dmesg
* @dev_priv: i915 drm device
* @hw_state: hw state to be written to the log
*
diff --git a/drivers/gpu/drm/i915/i915_gem_evict.c b/drivers/gpu/drm/i915/i915_gem_evict.c
index 6501939929d5..e1a66c8245b8 100644
--- a/drivers/gpu/drm/i915/i915_gem_evict.c
+++ b/drivers/gpu/drm/i915/i915_gem_evict.c
@@ -238,7 +238,7 @@ i915_gem_evict_something(struct i915_address_space *vm,
}
/**
- * i915_gem_evict_for_vma - Evict vmas to make room for binding a new one
+ * i915_gem_evict_for_node - Evict vmas to make room for binding a new one
* @vm: address space to evict from
* @target: range (and color) to evict for
* @flags: additional flags to control the eviction algorithm
diff --git a/drivers/gpu/drm/i915/i915_perf.c b/drivers/gpu/drm/i915/i915_perf.c
index e94976976571..3ced82820483 100644
--- a/drivers/gpu/drm/i915/i915_perf.c
+++ b/drivers/gpu/drm/i915/i915_perf.c
@@ -625,7 +625,8 @@ static int append_oa_sample(struct i915_perf_stream *stream,
}
/**
- * Copies all buffered OA reports into userspace read() buffer.
+ * gen8_append_oa_reports - Copies all buffered OA reports into
+ * userspace read() buffer.
* @stream: An i915-perf stream opened for OA metrics
* @buf: destination buffer given by userspace
* @count: the number of bytes userspace wants to read
@@ -917,7 +918,8 @@ static int gen8_oa_read(struct i915_perf_stream *stream,
}
/**
- * Copies all buffered OA reports into userspace read() buffer.
+ * gen7_append_oa_reports - Copies all buffered OA reports into
+ * userspace read() buffer.
* @stream: An i915-perf stream opened for OA metrics
* @buf: destination buffer given by userspace
* @count: the number of bytes userspace wants to read
@@ -3227,7 +3229,7 @@ static long i915_perf_config_locked(struct i915_perf_stream *stream,
}
/**
- * i915_perf_ioctl - support ioctl() usage with i915 perf stream FDs
+ * i915_perf_ioctl_locked - support ioctl() usage with i915 perf stream FDs
* @stream: An i915 perf stream
* @cmd: the ioctl request
* @arg: the ioctl data
diff --git a/drivers/gpu/drm/scheduler/sched_main.c b/drivers/gpu/drm/scheduler/sched_main.c
index 9a0d77a68018..c6332d75025e 100644
--- a/drivers/gpu/drm/scheduler/sched_main.c
+++ b/drivers/gpu/drm/scheduler/sched_main.c
@@ -446,7 +446,7 @@ void drm_sched_stop(struct drm_gpu_scheduler *sched, struct drm_sched_job *bad)
EXPORT_SYMBOL(drm_sched_stop);
/**
- * drm_sched_job_recovery - recover jobs after a reset
+ * drm_sched_start - recover jobs after a reset
*
* @sched: scheduler instance
* @full_recovery: proceed with complete sched restart
diff --git a/drivers/gpu/drm/v3d/v3d_sched.c b/drivers/gpu/drm/v3d/v3d_sched.c
index 0747614a78f0..f968f389633a 100644
--- a/drivers/gpu/drm/v3d/v3d_sched.c
+++ b/drivers/gpu/drm/v3d/v3d_sched.c
@@ -64,7 +64,7 @@ v3d_job_free(struct drm_sched_job *sched_job)
}
/**
- * Returns the fences that the job depends on, one by one.
+ * v3d_job_dependency - Returns the fences that the job depends on, one by one.
*
* If placed in the scheduler's .dependency method, the corresponding
* .run_job won't be called until all of them have been signaled.
diff --git a/drivers/gpu/drm/vc4/vc4_bo.c b/drivers/gpu/drm/vc4/vc4_bo.c
index 74ceebd62fbc..b8c04c6eb7f9 100644
--- a/drivers/gpu/drm/vc4/vc4_bo.c
+++ b/drivers/gpu/drm/vc4/vc4_bo.c
@@ -375,7 +375,7 @@ static struct vc4_bo *vc4_bo_get_from_cache(struct drm_device *dev,
}
/**
- * vc4_gem_create_object - Implementation of driver->gem_create_object.
+ * vc4_create_object - Implementation of driver->gem_create_object.
* @dev: DRM device
* @size: Size in bytes of the memory the object will reference
*
diff --git a/include/drm/drm_atomic_helper.h b/include/drm/drm_atomic_helper.h
index 85df04c8e62f..5f47720440fa 100644
--- a/include/drm/drm_atomic_helper.h
+++ b/include/drm/drm_atomic_helper.h
@@ -167,7 +167,7 @@ int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
drm_for_each_plane_mask(plane, (crtc)->dev, (crtc)->state->plane_mask)
/**
- * drm_crtc_atomic_state_for_each_plane - iterate over attached planes in new state
+ * drm_atomic_crtc_state_for_each_plane - iterate over attached planes in new state
* @plane: the loop cursor
* @crtc_state: the incoming CRTC state
*
@@ -180,7 +180,7 @@ int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
drm_for_each_plane_mask(plane, (crtc_state)->state->dev, (crtc_state)->plane_mask)
/**
- * drm_crtc_atomic_state_for_each_plane_state - iterate over attached planes in new state
+ * drm_atomic_crtc_state_for_each_plane_state - iterate over attached planes in new state
* @plane: the loop cursor
* @plane_state: loop cursor for the plane's state, must be const
* @crtc_state: the incoming CRTC state
diff --git a/include/drm/drm_connector.h b/include/drm/drm_connector.h
index 928136556174..fcdc58d8b88b 100644
--- a/include/drm/drm_connector.h
+++ b/include/drm/drm_connector.h
@@ -84,7 +84,7 @@ enum drm_connector_status {
};
/**
- * enum drm_connector_registration_status - userspace registration status for
+ * enum drm_connector_registration_state - userspace registration status for
* a &drm_connector
*
* This enum is used to track the status of initializing a connector and
diff --git a/include/drm/drm_device.h b/include/drm/drm_device.h
index f4f68e7a9149..3ae248938305 100644
--- a/include/drm/drm_device.h
+++ b/include/drm/drm_device.h
@@ -27,7 +27,7 @@ struct pci_controller;
/**
- * enum drm_switch_power - power state of drm device
+ * enum switch_power_state - power state of drm device
*/
enum switch_power_state {
diff --git a/include/drm/drm_dsc.h b/include/drm/drm_dsc.h
index 732f32740c86..53c51231b31c 100644
--- a/include/drm/drm_dsc.h
+++ b/include/drm/drm_dsc.h
@@ -273,7 +273,8 @@ struct drm_dsc_config {
};
/**
- * struct picture_parameter_set - Represents 128 bytes of Picture Parameter Set
+ * struct drm_dsc_picture_parameter_set - Represents 128 bytes of
+ * Picture Parameter Set
*
* The VESA DSC standard defines picture parameter set (PPS) which display
* stream compression encoders must communicate to decoders.
diff --git a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h
index 62cc6e6c3a4f..9a67dcca1f4a 100644
--- a/include/drm/drm_gem_vram_helper.h
+++ b/include/drm/drm_gem_vram_helper.h
@@ -69,8 +69,8 @@ struct drm_gem_vram_object {
};
/**
- * Returns the container of type &struct drm_gem_vram_object
- * for field bo.
+ * drm_gem_vram_of_bo - Returns the container of type
+ * &struct drm_gem_vram_object for field bo.
* @bo: the VRAM buffer object
* Returns: The containing GEM VRAM object
*/
@@ -81,8 +81,8 @@ static inline struct drm_gem_vram_object *drm_gem_vram_of_bo(
}
/**
- * Returns the container of type &struct drm_gem_vram_object
- * for field gem.
+ * drm_gem_vram_of_gem - Returns the container of type
+ * &struct drm_gem_vram_object for field gem.
* @gem: the GEM object
* Returns: The containing GEM VRAM object
*/
--
2.26.2
A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/w1.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/linux/w1.h b/include/linux/w1.h
index 949d3b10e531..9a2a0ef39018 100644
--- a/include/linux/w1.h
+++ b/include/linux/w1.h
@@ -280,7 +280,7 @@ int w1_register_family(struct w1_family *family);
void w1_unregister_family(struct w1_family *family);
/**
- * module_w1_driver() - Helper macro for registering a 1-Wire families
+ * module_w1_family() - Helper macro for registering a 1-Wire families
* @__w1_family: w1_family struct
*
* Helper macro for 1-Wire families which do not do anything special in module
--
2.26.2
Some identifiers have different names between their prototypes
and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
kernel/irq/chip.c | 2 +-
kernel/irq/generic-chip.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/kernel/irq/chip.c b/kernel/irq/chip.c
index b9b9618e1aca..df75c3573dcb 100644
--- a/kernel/irq/chip.c
+++ b/kernel/irq/chip.c
@@ -61,7 +61,7 @@ int irq_set_chip(unsigned int irq, struct irq_chip *chip)
EXPORT_SYMBOL(irq_set_chip);
/**
- * irq_set_type - set the irq trigger type for an irq
+ * irq_set_irq_type - set the irq trigger type for an irq
* @irq: irq number
* @type: IRQ_TYPE_{LEVEL,EDGE}_* value - see include/linux/irq.h
*/
diff --git a/kernel/irq/generic-chip.c b/kernel/irq/generic-chip.c
index e2999a070a99..a23ac2bbf433 100644
--- a/kernel/irq/generic-chip.c
+++ b/kernel/irq/generic-chip.c
@@ -269,7 +269,7 @@ irq_gc_init_mask_cache(struct irq_chip_generic *gc, enum irq_gc_flags flags)
}
/**
- * __irq_alloc_domain_generic_chip - Allocate generic chips for an irq domain
+ * __irq_alloc_domain_generic_chips - Allocate generic chips for an irq domain
* @d: irq domain for which to allocate chips
* @irqs_per_chip: Number of interrupts each chip handles (max 32)
* @num_ct: Number of irq_chip_type instances associated with this
--
2.26.2
The documented struct is psz_head and not psz_buffer.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
fs/pstore/zone.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/fs/pstore/zone.c b/fs/pstore/zone.c
index 3ce89216670c..46a1610c06fa 100644
--- a/fs/pstore/zone.c
+++ b/fs/pstore/zone.c
@@ -23,7 +23,7 @@
#include "internal.h"
/**
- * struct psz_head - header of zone to flush to storage
+ * struct psz_buffer - header of zone to flush to storage
*
* @sig: signature to indicate header (PSZ_SIG xor PSZONE-type value)
* @datalen: length of data in @data
--
2.26.2
locks_delete_lock -> locks_delete_block
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
fs/locks.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/fs/locks.c b/fs/locks.c
index 1f84a03601fe..f3c3ce82a455 100644
--- a/fs/locks.c
+++ b/fs/locks.c
@@ -750,7 +750,7 @@ static void __locks_wake_up_blocks(struct file_lock *blocker)
}
/**
- * locks_delete_lock - stop waiting for a file lock
+ * locks_delete_block - stop waiting for a file lock
* @waiter: the lock which was waiting
*
* lockd/nfsd need to disconnect the lock while working on it.
--
2.26.2
Kernel-doc markup should use this format:
identifier - description
They should not have any type before that, as otherwise
the parser won't do the right thing.
Also, some identifiers have different names between their
prototypes and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
fs/jbd2/journal.c | 34 ++++++++++++++++++----------------
fs/jbd2/transaction.c | 31 ++++++++++++++++---------------
include/linux/jbd2.h | 2 +-
3 files changed, 35 insertions(+), 32 deletions(-)
diff --git a/fs/jbd2/journal.c b/fs/jbd2/journal.c
index 0c7c42bd530f..f71848367ab6 100644
--- a/fs/jbd2/journal.c
+++ b/fs/jbd2/journal.c
@@ -566,12 +566,14 @@ static int __jbd2_journal_force_commit(journal_t *journal)
}
/**
- * Force and wait upon a commit if the calling process is not within
- * transaction. This is used for forcing out undo-protected data which contains
- * bitmaps, when the fs is running out of space.
+ * jbd2_journal_force_commit_nested - Force and wait upon a commit if the
+ * calling process is not within transaction.
*
* @journal: journal to force
* Returns true if progress was made.
+ *
+ * This is used for forcing out undo-protected data which contains
+ * bitmaps, when the fs is running out of space.
*/
int jbd2_journal_force_commit_nested(journal_t *journal)
{
@@ -582,7 +584,7 @@ int jbd2_journal_force_commit_nested(journal_t *journal)
}
/**
- * int journal_force_commit() - force any uncommitted transactions
+ * jbd2_journal_force_commit() - force any uncommitted transactions
* @journal: journal to force
*
* Caller want unconditional commit. We can only force the running transaction
@@ -1899,7 +1901,7 @@ static int load_superblock(journal_t *journal)
/**
- * int jbd2_journal_load() - Read journal from disk.
+ * jbd2_journal_load() - Read journal from disk.
* @journal: Journal to act on.
*
* Given a journal_t structure which tells us which disk blocks contain
@@ -1972,7 +1974,7 @@ int jbd2_journal_load(journal_t *journal)
}
/**
- * void jbd2_journal_destroy() - Release a journal_t structure.
+ * jbd2_journal_destroy() - Release a journal_t structure.
* @journal: Journal to act on.
*
* Release a journal_t structure once it is no longer in use by the
@@ -2050,7 +2052,7 @@ int jbd2_journal_destroy(journal_t *journal)
/**
- *int jbd2_journal_check_used_features() - Check if features specified are used.
+ * jbd2_journal_check_used_features() - Check if features specified are used.
* @journal: Journal to check.
* @compat: bitmask of compatible features
* @ro: bitmask of features that force read-only mount
@@ -2085,7 +2087,7 @@ int jbd2_journal_check_used_features(journal_t *journal, unsigned long compat,
}
/**
- * int jbd2_journal_check_available_features() - Check feature set in journalling layer
+ * jbd2_journal_check_available_features() - Check feature set in journalling layer
* @journal: Journal to check.
* @compat: bitmask of compatible features
* @ro: bitmask of features that force read-only mount
@@ -2117,7 +2119,7 @@ int jbd2_journal_check_available_features(journal_t *journal, unsigned long comp
}
/**
- * int jbd2_journal_set_features() - Mark a given journal feature in the superblock
+ * jbd2_journal_set_features() - Mark a given journal feature in the superblock
* @journal: Journal to act on.
* @compat: bitmask of compatible features
* @ro: bitmask of features that force read-only mount
@@ -2201,7 +2203,7 @@ int jbd2_journal_set_features(journal_t *journal, unsigned long compat,
}
/*
- * jbd2_journal_clear_features () - Clear a given journal feature in the
+ * jbd2_journal_clear_features() - Clear a given journal feature in the
* superblock
* @journal: Journal to act on.
* @compat: bitmask of compatible features
@@ -2230,7 +2232,7 @@ void jbd2_journal_clear_features(journal_t *journal, unsigned long compat,
EXPORT_SYMBOL(jbd2_journal_clear_features);
/**
- * int jbd2_journal_flush () - Flush journal
+ * jbd2_journal_flush() - Flush journal
* @journal: Journal to act on.
*
* Flush all data for a given journal to disk and empty the journal.
@@ -2305,7 +2307,7 @@ int jbd2_journal_flush(journal_t *journal)
}
/**
- * int jbd2_journal_wipe() - Wipe journal contents
+ * jbd2_journal_wipe() - Wipe journal contents
* @journal: Journal to act on.
* @write: flag (see below)
*
@@ -2346,7 +2348,7 @@ int jbd2_journal_wipe(journal_t *journal, int write)
}
/**
- * void jbd2_journal_abort () - Shutdown the journal immediately.
+ * jbd2_journal_abort () - Shutdown the journal immediately.
* @journal: the journal to shutdown.
* @errno: an error number to record in the journal indicating
* the reason for the shutdown.
@@ -2437,7 +2439,7 @@ void jbd2_journal_abort(journal_t *journal, int errno)
}
/**
- * int jbd2_journal_errno () - returns the journal's error state.
+ * jbd2_journal_errno() - returns the journal's error state.
* @journal: journal to examine.
*
* This is the errno number set with jbd2_journal_abort(), the last
@@ -2461,7 +2463,7 @@ int jbd2_journal_errno(journal_t *journal)
}
/**
- * int jbd2_journal_clear_err () - clears the journal's error state
+ * jbd2_journal_clear_err() - clears the journal's error state
* @journal: journal to act on.
*
* An error must be cleared or acked to take a FS out of readonly
@@ -2481,7 +2483,7 @@ int jbd2_journal_clear_err(journal_t *journal)
}
/**
- * void jbd2_journal_ack_err() - Ack journal err.
+ * jbd2_journal_ack_err() - Ack journal err.
* @journal: journal to act on.
*
* An error must be cleared or acked to take a FS out of readonly
diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c
index 43985738aa86..4cf88191b025 100644
--- a/fs/jbd2/transaction.c
+++ b/fs/jbd2/transaction.c
@@ -517,7 +517,7 @@ EXPORT_SYMBOL(jbd2__journal_start);
/**
- * handle_t *jbd2_journal_start() - Obtain a new handle.
+ * jbd2_journal_start() - Obtain a new handle.
* @journal: Journal to start transaction on.
* @nblocks: number of block buffer we might modify
*
@@ -564,7 +564,7 @@ void jbd2_journal_free_reserved(handle_t *handle)
EXPORT_SYMBOL(jbd2_journal_free_reserved);
/**
- * int jbd2_journal_start_reserved() - start reserved handle
+ * jbd2_journal_start_reserved() - start reserved handle
* @handle: handle to start
* @type: for handle statistics
* @line_no: for handle statistics
@@ -618,7 +618,7 @@ int jbd2_journal_start_reserved(handle_t *handle, unsigned int type,
EXPORT_SYMBOL(jbd2_journal_start_reserved);
/**
- * int jbd2_journal_extend() - extend buffer credits.
+ * jbd2_journal_extend() - extend buffer credits.
* @handle: handle to 'extend'
* @nblocks: nr blocks to try to extend by.
* @revoke_records: number of revoke records to try to extend by.
@@ -743,7 +743,7 @@ static void stop_this_handle(handle_t *handle)
}
/**
- * int jbd2_journal_restart() - restart a handle .
+ * jbd2__journal_restart() - restart a handle .
* @handle: handle to restart
* @nblocks: nr credits requested
* @revoke_records: number of revoke record credits requested
@@ -813,7 +813,7 @@ int jbd2_journal_restart(handle_t *handle, int nblocks)
EXPORT_SYMBOL(jbd2_journal_restart);
/**
- * void jbd2_journal_lock_updates () - establish a transaction barrier.
+ * jbd2_journal_lock_updates () - establish a transaction barrier.
* @journal: Journal to establish a barrier on.
*
* This locks out any further updates from being started, and blocks
@@ -872,7 +872,7 @@ void jbd2_journal_lock_updates(journal_t *journal)
}
/**
- * void jbd2_journal_unlock_updates (journal_t* journal) - release barrier
+ * jbd2_journal_unlock_updates () - release barrier
* @journal: Journal to release the barrier on.
*
* Release a transaction barrier obtained with jbd2_journal_lock_updates().
@@ -1180,7 +1180,8 @@ static bool jbd2_write_access_granted(handle_t *handle, struct buffer_head *bh,
}
/**
- * int jbd2_journal_get_write_access() - notify intent to modify a buffer for metadata (not data) update.
+ * jbd2_journal_get_write_access() - notify intent to modify a buffer
+ * for metadata (not data) update.
* @handle: transaction to add buffer modifications to
* @bh: bh to be used for metadata writes
*
@@ -1224,7 +1225,7 @@ int jbd2_journal_get_write_access(handle_t *handle, struct buffer_head *bh)
* unlocked buffer beforehand. */
/**
- * int jbd2_journal_get_create_access () - notify intent to use newly created bh
+ * jbd2_journal_get_create_access () - notify intent to use newly created bh
* @handle: transaction to new buffer to
* @bh: new buffer.
*
@@ -1304,7 +1305,7 @@ int jbd2_journal_get_create_access(handle_t *handle, struct buffer_head *bh)
}
/**
- * int jbd2_journal_get_undo_access() - Notify intent to modify metadata with
+ * jbd2_journal_get_undo_access() - Notify intent to modify metadata with
* non-rewindable consequences
* @handle: transaction
* @bh: buffer to undo
@@ -1381,7 +1382,7 @@ int jbd2_journal_get_undo_access(handle_t *handle, struct buffer_head *bh)
}
/**
- * void jbd2_journal_set_triggers() - Add triggers for commit writeout
+ * jbd2_journal_set_triggers() - Add triggers for commit writeout
* @bh: buffer to trigger on
* @type: struct jbd2_buffer_trigger_type containing the trigger(s).
*
@@ -1423,7 +1424,7 @@ void jbd2_buffer_abort_trigger(struct journal_head *jh,
}
/**
- * int jbd2_journal_dirty_metadata() - mark a buffer as containing dirty metadata
+ * jbd2_journal_dirty_metadata() - mark a buffer as containing dirty metadata
* @handle: transaction to add buffer to.
* @bh: buffer to mark
*
@@ -1591,7 +1592,7 @@ int jbd2_journal_dirty_metadata(handle_t *handle, struct buffer_head *bh)
}
/**
- * void jbd2_journal_forget() - bforget() for potentially-journaled buffers.
+ * jbd2_journal_forget() - bforget() for potentially-journaled buffers.
* @handle: transaction handle
* @bh: bh to 'forget'
*
@@ -1760,7 +1761,7 @@ int jbd2_journal_forget(handle_t *handle, struct buffer_head *bh)
}
/**
- * int jbd2_journal_stop() - complete a transaction
+ * jbd2_journal_stop() - complete a transaction
* @handle: transaction to complete.
*
* All done for a particular handle.
@@ -2078,7 +2079,7 @@ __journal_try_to_free_buffer(journal_t *journal, struct buffer_head *bh)
}
/**
- * int jbd2_journal_try_to_free_buffers() - try to free page buffers.
+ * jbd2_journal_try_to_free_buffers() - try to free page buffers.
* @journal: journal for operation
* @page: to try and free
*
@@ -2409,7 +2410,7 @@ static int journal_unmap_buffer(journal_t *journal, struct buffer_head *bh,
}
/**
- * void jbd2_journal_invalidatepage()
+ * jbd2_journal_invalidatepage()
* @journal: journal to use for flush...
* @page: page to flush
* @offset: start of the range to invalidate
diff --git a/include/linux/jbd2.h b/include/linux/jbd2.h
index 3c5f76ce88f1..17bed9684cba 100644
--- a/include/linux/jbd2.h
+++ b/include/linux/jbd2.h
@@ -397,7 +397,7 @@ static inline void jbd_unlock_bh_journal_head(struct buffer_head *bh)
#define JI_WAIT_DATA (1 << __JI_WAIT_DATA)
/**
- * struct jbd_inode - The jbd_inode type is the structure linking inodes in
+ * struct jbd2_inode - The jbd_inode type is the structure linking inodes in
* ordered mode present in a transaction so that we can sync them during commit.
*/
struct jbd2_inode {
--
2.26.2
A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/connector.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/linux/connector.h b/include/linux/connector.h
index cb732643471b..6bdb56662675 100644
--- a/include/linux/connector.h
+++ b/include/linux/connector.h
@@ -99,7 +99,7 @@ void cn_del_callback(struct cb_id *id);
int cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 group, gfp_t gfp_mask);
/**
- * cn_netlink_send_mult - Sends message to the specified groups.
+ * cn_netlink_send - Sends message to the specified groups.
*
* @msg: message header(with attached data).
* @portid: destination port.
--
2.26.2
Some identifiers have different names between their prototypes
and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/pci/p2pdma.c | 10 +++++-----
drivers/pci/pci-driver.c | 4 ++--
drivers/pci/pci.c | 2 +-
drivers/pci/probe.c | 4 ++--
drivers/pci/slot.c | 5 +++--
5 files changed, 13 insertions(+), 12 deletions(-)
diff --git a/drivers/pci/p2pdma.c b/drivers/pci/p2pdma.c
index de1c331dbed4..bace04145c5f 100644
--- a/drivers/pci/p2pdma.c
+++ b/drivers/pci/p2pdma.c
@@ -609,7 +609,7 @@ bool pci_has_p2pmem(struct pci_dev *pdev)
EXPORT_SYMBOL_GPL(pci_has_p2pmem);
/**
- * pci_p2pmem_find - find a peer-to-peer DMA memory device compatible with
+ * pci_p2pmem_find_many - find a peer-to-peer DMA memory device compatible with
* the specified list of clients and shortest distance (as determined
* by pci_p2pmem_dma())
* @clients: array of devices to check (NULL-terminated)
@@ -674,7 +674,7 @@ struct pci_dev *pci_p2pmem_find_many(struct device **clients, int num_clients)
EXPORT_SYMBOL_GPL(pci_p2pmem_find_many);
/**
- * pci_alloc_p2p_mem - allocate peer-to-peer DMA memory
+ * pci_alloc_p2pmem - allocate peer-to-peer DMA memory
* @pdev: the device to allocate memory from
* @size: number of bytes to allocate
*
@@ -727,7 +727,7 @@ void pci_free_p2pmem(struct pci_dev *pdev, void *addr, size_t size)
EXPORT_SYMBOL_GPL(pci_free_p2pmem);
/**
- * pci_virt_to_bus - return the PCI bus address for a given virtual
+ * pci_p2pmem_virt_to_bus - return the PCI bus address for a given virtual
* address obtained with pci_alloc_p2pmem()
* @pdev: the device the memory was allocated from
* @addr: address of the memory that was allocated
@@ -859,7 +859,7 @@ static int __pci_p2pdma_map_sg(struct pci_p2pdma_pagemap *p2p_pgmap,
}
/**
- * pci_p2pdma_map_sg - map a PCI peer-to-peer scatterlist for DMA
+ * pci_p2pdma_map_sg_attrs - map a PCI peer-to-peer scatterlist for DMA
* @dev: device doing the DMA request
* @sg: scatter list to map
* @nents: elements in the scatterlist
@@ -896,7 +896,7 @@ int pci_p2pdma_map_sg_attrs(struct device *dev, struct scatterlist *sg,
EXPORT_SYMBOL_GPL(pci_p2pdma_map_sg_attrs);
/**
- * pci_p2pdma_unmap_sg - unmap a PCI peer-to-peer scatterlist that was
+ * pci_p2pdma_unmap_sg_attrs - unmap a PCI peer-to-peer scatterlist that was
* mapped with pci_p2pdma_map_sg()
* @dev: device doing the DMA request
* @sg: scatter list to map
diff --git a/drivers/pci/pci-driver.c b/drivers/pci/pci-driver.c
index 8b587fc97f7b..591ab353844a 100644
--- a/drivers/pci/pci-driver.c
+++ b/drivers/pci/pci-driver.c
@@ -90,7 +90,7 @@ static void pci_free_dynids(struct pci_driver *drv)
}
/**
- * store_new_id - sysfs frontend to pci_add_dynid()
+ * new_id_store - sysfs frontend to pci_add_dynid()
* @driver: target device driver
* @buf: buffer for scanning device ID data
* @count: input size
@@ -158,7 +158,7 @@ static ssize_t new_id_store(struct device_driver *driver, const char *buf,
static DRIVER_ATTR_WO(new_id);
/**
- * store_remove_id - remove a PCI device ID from this driver
+ * remove_id_store - remove a PCI device ID from this driver
* @driver: target device driver
* @buf: buffer for scanning device ID data
* @count: input size
diff --git a/drivers/pci/pci.c b/drivers/pci/pci.c
index 6d4d5a2f923d..8b9bea8ba751 100644
--- a/drivers/pci/pci.c
+++ b/drivers/pci/pci.c
@@ -3480,7 +3480,7 @@ bool pci_acs_enabled(struct pci_dev *pdev, u16 acs_flags)
}
/**
- * pci_acs_path_enable - test ACS flags from start to end in a hierarchy
+ * pci_acs_path_enabled - test ACS flags from start to end in a hierarchy
* @start: starting downstream device
* @end: ending upstream device or NULL to search to the root bus
* @acs_flags: required flags
diff --git a/drivers/pci/probe.c b/drivers/pci/probe.c
index 4289030b0fff..eb1ec037f9e7 100644
--- a/drivers/pci/probe.c
+++ b/drivers/pci/probe.c
@@ -165,7 +165,7 @@ static inline unsigned long decode_bar(struct pci_dev *dev, u32 bar)
#define PCI_COMMAND_DECODE_ENABLE (PCI_COMMAND_MEMORY | PCI_COMMAND_IO)
/**
- * pci_read_base - Read a PCI BAR
+ * __pci_read_base - Read a PCI BAR
* @dev: the PCI device
* @type: type of the BAR
* @res: resource buffer to be filled in
@@ -1612,7 +1612,7 @@ static bool pci_ext_cfg_is_aliased(struct pci_dev *dev)
}
/**
- * pci_cfg_space_size - Get the configuration space size of the PCI device
+ * pci_cfg_space_size_ext - Get the configuration space size of the PCI device
* @dev: PCI device
*
* Regular PCI devices have 256 bytes, but PCI-X 2 and PCI Express devices
diff --git a/drivers/pci/slot.c b/drivers/pci/slot.c
index 3861505741e6..bcc8b12ce5da 100644
--- a/drivers/pci/slot.c
+++ b/drivers/pci/slot.c
@@ -323,7 +323,7 @@ EXPORT_SYMBOL_GPL(pci_destroy_slot);
#if defined(CONFIG_HOTPLUG_PCI) || defined(CONFIG_HOTPLUG_PCI_MODULE)
#include <linux/pci_hotplug.h>
/**
- * pci_hp_create_link - create symbolic link to the hotplug driver module.
+ * pci_hp_create_module_link - create symbolic link to the hotplug driver module.
* @pci_slot: struct pci_slot
*
* Helper function for pci_hotplug_core.c to create symbolic link to
@@ -349,7 +349,8 @@ void pci_hp_create_module_link(struct pci_slot *pci_slot)
EXPORT_SYMBOL_GPL(pci_hp_create_module_link);
/**
- * pci_hp_remove_link - remove symbolic link to the hotplug driver module.
+ * pci_hp_remove_module_link - remove symbolic link to the hotplug driver
+ * module.
* @pci_slot: struct pci_slot
*
* Helper function for pci_hotplug_core.c to remove symbolic link to
--
2.26.2
Probaly this was due to a cut and paste issue.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/rapidio/rio.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/rapidio/rio.c b/drivers/rapidio/rio.c
index 606986c5ba2c..16b59b472b3d 100644
--- a/drivers/rapidio/rio.c
+++ b/drivers/rapidio/rio.c
@@ -749,7 +749,7 @@ int rio_map_outb_region(struct rio_mport *mport, u16 destid, u64 rbase,
EXPORT_SYMBOL_GPL(rio_map_outb_region);
/**
- * rio_unmap_inb_region -- Unmap the inbound memory region
+ * rio_unmap_outb_region -- Unmap the inbound memory region
* @mport: Master port
* @destid: destination id mapping points to
* @rstart: RIO base address window translates to
--
2.26.2
Fix the name of the enum on its kernel-doc markup:
enum slim_ch_aux_fmt -> enum slim_ch_aux_bit_fmt
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/slimbus/slimbus.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/slimbus/slimbus.h b/drivers/slimbus/slimbus.h
index c73035915f1d..00a7f112574b 100644
--- a/drivers/slimbus/slimbus.h
+++ b/drivers/slimbus/slimbus.h
@@ -244,7 +244,7 @@ enum slim_ch_data_fmt {
};
/**
- * enum slim_ch_aux_fmt: SLIMbus channel Aux Field format IDs according to
+ * enum slim_ch_aux_bit_fmt: SLIMbus channel Aux Field format IDs according to
* Table 63 of SLIMbus Spec 2.0
* @SLIM_CH_AUX_FMT_NOT_APPLICABLE: Undefined
* @SLIM_CH_AUX_FMT_ZCUV_TUNNEL_IEC60958: ZCUV for tunneling IEC60958
--
2.26.2
typo:
kauditd_print_skb -> kauditd_printk_skb
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
kernel/audit.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/kernel/audit.c b/kernel/audit.c
index 68cee3bc8cfe..0be42cac086b 100644
--- a/kernel/audit.c
+++ b/kernel/audit.c
@@ -523,7 +523,7 @@ static int auditd_set(struct pid *pid, u32 portid, struct net *net)
}
/**
- * kauditd_print_skb - Print the audit record to the ring buffer
+ * kauditd_printk_skb - Print the audit record to the ring buffer
* @skb: audit record
*
* Whatever the reason, this packet may not make it to the auditd connection
--
2.26.2
class_create is actually defined at the header. Fix the
markup there and add a new one at the right place.
While here, also fix some markups for functions that have
different names between their prototypes and kernel-doc
comments.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/base/class.c | 2 +-
drivers/base/devres.c | 2 +-
drivers/base/firmware_loader/fallback.c | 2 +-
include/linux/device/class.h | 14 ++++++++++++++
4 files changed, 17 insertions(+), 3 deletions(-)
diff --git a/drivers/base/class.c b/drivers/base/class.c
index c3451481194e..7476f393df97 100644
--- a/drivers/base/class.c
+++ b/drivers/base/class.c
@@ -210,7 +210,7 @@ static void class_create_release(struct class *cls)
}
/**
- * class_create - create a struct class structure
+ * __class_create - create a struct class structure
* @owner: pointer to the module that is to "own" this struct class
* @name: pointer to a string for the name of this class.
* @key: the lock_class_key for this class; used by mutex lock debugging
diff --git a/drivers/base/devres.c b/drivers/base/devres.c
index 586e9a75c840..fb9d5289a620 100644
--- a/drivers/base/devres.c
+++ b/drivers/base/devres.c
@@ -149,7 +149,7 @@ void * __devres_alloc_node(dr_release_t release, size_t size, gfp_t gfp, int nid
EXPORT_SYMBOL_GPL(__devres_alloc_node);
#else
/**
- * devres_alloc - Allocate device resource data
+ * devres_alloc_node - Allocate device resource data
* @release: Release function devres will be associated with
* @size: Allocation size
* @gfp: Allocation flags
diff --git a/drivers/base/firmware_loader/fallback.c b/drivers/base/firmware_loader/fallback.c
index 4dec4b79ae06..91899d185e31 100644
--- a/drivers/base/firmware_loader/fallback.c
+++ b/drivers/base/firmware_loader/fallback.c
@@ -128,7 +128,7 @@ static ssize_t timeout_show(struct class *class, struct class_attribute *attr,
}
/**
- * firmware_timeout_store() - set number of seconds to wait for firmware
+ * timeout_store() - set number of seconds to wait for firmware
* @class: device class pointer
* @attr: device attribute pointer
* @buf: buffer to scan for timeout value
diff --git a/include/linux/device/class.h b/include/linux/device/class.h
index e8d470c457d1..e61ec5502019 100644
--- a/include/linux/device/class.h
+++ b/include/linux/device/class.h
@@ -256,6 +256,20 @@ extern void class_destroy(struct class *cls);
/* This is a #define to keep the compiler from merging different
* instances of the __key variable */
+
+/**
+ * class_create - create a struct class structure
+ * @owner: pointer to the module that is to "own" this struct class
+ * @name: pointer to a string for the name of this class.
+ *
+ * This is used to create a struct class pointer that can then be used
+ * in calls to device_create().
+ *
+ * Returns &struct class pointer on success, or ERR_PTR() on error.
+ *
+ * Note, the pointer created here is to be destroyed when finished by
+ * making a call to class_destroy().
+ */
#define class_create(owner, name) \
({ \
static struct lock_class_key __key; \
--
2.26.2
The kernel-doc markup inside share.c is actually for
__parport_register_driver. The actual goal seems to be
to document parport_register_driver().
So, fix the existing markup and add a new one.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/parport/share.c | 2 +-
include/linux/parport.h | 31 +++++++++++++++++++++++++++++++
2 files changed, 32 insertions(+), 1 deletion(-)
diff --git a/drivers/parport/share.c b/drivers/parport/share.c
index 7fec4fefe151..62f8407923d4 100644
--- a/drivers/parport/share.c
+++ b/drivers/parport/share.c
@@ -243,7 +243,7 @@ static int port_detect(struct device *dev, void *dev_drv)
}
/**
- * parport_register_driver - register a parallel port device driver
+ * __parport_register_driver - register a parallel port device driver
* @drv: structure describing the driver
* @owner: owner module of drv
* @mod_name: module name string
diff --git a/include/linux/parport.h b/include/linux/parport.h
index 1fb508c19e83..f981f794c850 100644
--- a/include/linux/parport.h
+++ b/include/linux/parport.h
@@ -297,6 +297,37 @@ int __must_check __parport_register_driver(struct parport_driver *,
* parport_register_driver must be a macro so that KBUILD_MODNAME can
* be expanded
*/
+
+/**
+ * parport_register_driver - register a parallel port device driver
+ * @driver: structure describing the driver
+ *
+ * This can be called by a parallel port device driver in order
+ * to receive notifications about ports being found in the
+ * system, as well as ports no longer available.
+ *
+ * If devmodel is true then the new device model is used
+ * for registration.
+ *
+ * The @driver structure is allocated by the caller and must not be
+ * deallocated until after calling parport_unregister_driver().
+ *
+ * If using the non device model:
+ * The driver's attach() function may block. The port that
+ * attach() is given will be valid for the duration of the
+ * callback, but if the driver wants to take a copy of the
+ * pointer it must call parport_get_port() to do so. Calling
+ * parport_register_device() on that port will do this for you.
+ *
+ * The driver's detach() function may block. The port that
+ * detach() is given will be valid for the duration of the
+ * callback, but if the driver wants to take a copy of the
+ * pointer it must call parport_get_port() to do so.
+ *
+ *
+ * Returns 0 on success. The non device model will always succeeds.
+ * but the new device model can fail and will return the error code.
+ **/
#define parport_register_driver(driver) \
__parport_register_driver(driver, THIS_MODULE, KBUILD_MODNAME)
--
2.26.2
Some functions have different names between their prototypes
and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/net/phy/mdio_bus.c | 2 +-
drivers/net/phy/phy-c45.c | 2 +-
drivers/net/phy/phy.c | 2 +-
drivers/net/phy/phy_device.c | 2 +-
drivers/net/phy/phylink.c | 2 +-
5 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/drivers/net/phy/mdio_bus.c b/drivers/net/phy/mdio_bus.c
index 757e950fb745..e59067c64e97 100644
--- a/drivers/net/phy/mdio_bus.c
+++ b/drivers/net/phy/mdio_bus.c
@@ -472,7 +472,7 @@ static inline void of_mdiobus_link_mdiodev(struct mii_bus *mdio,
#endif
/**
- * mdiobus_create_device_from_board_info - create a full MDIO device given
+ * mdiobus_create_device - create a full MDIO device given
* a mdio_board_info structure
* @bus: MDIO bus to create the devices on
* @bi: mdio_board_info structure describing the devices
diff --git a/drivers/net/phy/phy-c45.c b/drivers/net/phy/phy-c45.c
index bd11e62bfdfe..077f2929c45e 100644
--- a/drivers/net/phy/phy-c45.c
+++ b/drivers/net/phy/phy-c45.c
@@ -9,7 +9,7 @@
#include <linux/phy.h>
/**
- * genphy_c45_setup_forced - configures a forced speed
+ * genphy_c45_pma_setup_forced - configures a forced speed
* @phydev: target phy_device struct
*/
int genphy_c45_pma_setup_forced(struct phy_device *phydev)
diff --git a/drivers/net/phy/phy.c b/drivers/net/phy/phy.c
index 35525a671400..71ed2596acf5 100644
--- a/drivers/net/phy/phy.c
+++ b/drivers/net/phy/phy.c
@@ -489,7 +489,7 @@ void phy_queue_state_machine(struct phy_device *phydev, unsigned long jiffies)
EXPORT_SYMBOL(phy_queue_state_machine);
/**
- * phy_queue_state_machine - Trigger the state machine to run now
+ * phy_trigger_machine - Trigger the state machine to run now
*
* @phydev: the phy_device struct
*/
diff --git a/drivers/net/phy/phy_device.c b/drivers/net/phy/phy_device.c
index 5dab6be6fc38..ea5d5fb42d01 100644
--- a/drivers/net/phy/phy_device.c
+++ b/drivers/net/phy/phy_device.c
@@ -2735,7 +2735,7 @@ static int phy_get_int_delay_property(struct device *dev, const char *name)
#endif
/**
- * phy_get_delay_index - returns the index of the internal delay
+ * phy_get_internal_delay - returns the index of the internal delay
* @phydev: phy_device struct
* @dev: pointer to the devices device struct
* @delay_values: array of delays the PHY supports
diff --git a/drivers/net/phy/phylink.c b/drivers/net/phy/phylink.c
index fe2296fdda19..1318ccb62bd7 100644
--- a/drivers/net/phy/phylink.c
+++ b/drivers/net/phy/phylink.c
@@ -1649,7 +1649,7 @@ int phylink_ethtool_set_pauseparam(struct phylink *pl,
EXPORT_SYMBOL_GPL(phylink_ethtool_set_pauseparam);
/**
- * phylink_ethtool_get_eee_err() - read the energy efficient ethernet error
+ * phylink_get_eee_err() - read the energy efficient ethernet error
* counter
* @pl: a pointer to a &struct phylink returned from phylink_create().
*
--
2.26.2
Some identifiers have different names between their prototypes
and the kernel-doc markup.
Others need to be fixed, as kernel-doc markups should use this format:
identifier - description
In the specific case of __sta_info_flush(), add a documentation
for sta_info_flush(), as this one is the one used outside
sta_info.c.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/net/cfg80211.h | 9 +++++----
include/net/mac80211.h | 7 ++++---
net/mac80211/sta_info.h | 9 ++++++++-
3 files changed, 17 insertions(+), 8 deletions(-)
diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 661edfc8722e..d5ab8d99739f 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -1444,7 +1444,7 @@ int cfg80211_check_station_change(struct wiphy *wiphy,
enum cfg80211_station_type statype);
/**
- * enum station_info_rate_flags - bitrate info flags
+ * enum rate_info_flags - bitrate info flags
*
* Used by the driver to indicate the specific rate transmission
* type for 802.11n transmissions.
@@ -1517,7 +1517,7 @@ struct rate_info {
};
/**
- * enum station_info_rate_flags - bitrate info flags
+ * enum bss_param_flags - bitrate info flags
*
* Used by the driver to indicate the specific rate transmission
* type for 802.11n transmissions.
@@ -6467,7 +6467,8 @@ void cfg80211_ibss_joined(struct net_device *dev, const u8 *bssid,
struct ieee80211_channel *channel, gfp_t gfp);
/**
- * cfg80211_notify_new_candidate - notify cfg80211 of a new mesh peer candidate
+ * cfg80211_notify_new_peer_candidate - notify cfg80211 of a new mesh peer
+ * candidate
*
* @dev: network device
* @macaddr: the MAC address of the new candidate
@@ -7606,7 +7607,7 @@ u32 cfg80211_calculate_bitrate(struct rate_info *rate);
void cfg80211_unregister_wdev(struct wireless_dev *wdev);
/**
- * struct cfg80211_ft_event - FT Information Elements
+ * struct cfg80211_ft_event_params - FT Information Elements
* @ies: FT IEs
* @ies_len: length of the FT IE in bytes
* @target_ap: target AP's MAC address
diff --git a/include/net/mac80211.h b/include/net/mac80211.h
index e8e295dae744..dcdba96814a2 100644
--- a/include/net/mac80211.h
+++ b/include/net/mac80211.h
@@ -3311,7 +3311,7 @@ enum ieee80211_roc_type {
};
/**
- * enum ieee80211_reconfig_complete_type - reconfig type
+ * enum ieee80211_reconfig_type - reconfig type
*
* This enum is used by the reconfig_complete() callback to indicate what
* reconfiguration type was completed.
@@ -6334,7 +6334,8 @@ bool ieee80211_tx_prepare_skb(struct ieee80211_hw *hw,
int band, struct ieee80211_sta **sta);
/**
- * Sanity-check and parse the radiotap header of injected frames
+ * ieee80211_parse_tx_radiotap - Sanity-check and parse the radiotap header
+ * of injected frames
* @skb: packet injected by userspace
* @dev: the &struct device of this 802.11 device
*/
@@ -6389,7 +6390,7 @@ int ieee80211_parse_p2p_noa(const struct ieee80211_p2p_noa_attr *attr,
void ieee80211_update_p2p_noa(struct ieee80211_noa_data *data, u32 tsf);
/**
- * ieee80211_tdls_oper - request userspace to perform a TDLS operation
+ * ieee80211_tdls_oper_request - request userspace to perform a TDLS operation
* @vif: virtual interface
* @peer: the peer's destination address
* @oper: the requested TDLS operation
diff --git a/net/mac80211/sta_info.h b/net/mac80211/sta_info.h
index 00ae81e9e1a1..7afd07636b81 100644
--- a/net/mac80211/sta_info.h
+++ b/net/mac80211/sta_info.h
@@ -785,7 +785,7 @@ int sta_info_init(struct ieee80211_local *local);
void sta_info_stop(struct ieee80211_local *local);
/**
- * sta_info_flush - flush matching STA entries from the STA table
+ * __sta_info_flush - flush matching STA entries from the STA table
*
* Returns the number of removed STA entries.
*
@@ -794,6 +794,13 @@ void sta_info_stop(struct ieee80211_local *local);
*/
int __sta_info_flush(struct ieee80211_sub_if_data *sdata, bool vlans);
+/**
+ * sta_info_flush - flush matching STA entries from the STA table
+ *
+ * Returns the number of removed STA entries.
+ *
+ * @sdata: sdata to remove all stations from
+ */
static inline int sta_info_flush(struct ieee80211_sub_if_data *sdata)
{
return __sta_info_flush(sdata, false);
--
2.26.2
It sounds that there were function renames. Update the kernel-doc
markups accordingly.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/pnp/core.c | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/drivers/pnp/core.c b/drivers/pnp/core.c
index 3bf18d718975..a50ab002e9e4 100644
--- a/drivers/pnp/core.c
+++ b/drivers/pnp/core.c
@@ -51,7 +51,7 @@ static void pnp_remove_protocol(struct pnp_protocol *protocol)
}
/**
- * pnp_protocol_register - adds a pnp protocol to the pnp layer
+ * pnp_register_protocol - adds a pnp protocol to the pnp layer
* @protocol: pointer to the corresponding pnp_protocol structure
*
* Ex protocols: ISAPNP, PNPBIOS, etc
@@ -91,7 +91,7 @@ int pnp_register_protocol(struct pnp_protocol *protocol)
}
/**
- * pnp_protocol_unregister - removes a pnp protocol from the pnp layer
+ * pnp_unregister_protocol - removes a pnp protocol from the pnp layer
* @protocol: pointer to the corresponding pnp_protocol structure
*/
void pnp_unregister_protocol(struct pnp_protocol *protocol)
--
2.26.2
The definitions for (devm_)uio_register_device should be
at the header file, as the macros are there. The ones
inside uio.c refer, instead, to __(devm_)uio_register_device.
Update them and add new kernel-doc markups for the macros.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/uio/uio.c | 4 ++--
include/linux/uio_driver.h | 16 ++++++++++++++++
2 files changed, 18 insertions(+), 2 deletions(-)
diff --git a/drivers/uio/uio.c b/drivers/uio/uio.c
index 6dca744e39e9..01b349c1b923 100644
--- a/drivers/uio/uio.c
+++ b/drivers/uio/uio.c
@@ -906,7 +906,7 @@ static void uio_device_release(struct device *dev)
}
/**
- * uio_register_device - register a new userspace IO device
+ * __uio_register_device - register a new userspace IO device
* @owner: module that creates the new device
* @parent: parent device
* @info: UIO device capabilities
@@ -1002,7 +1002,7 @@ static void devm_uio_unregister_device(struct device *dev, void *res)
}
/**
- * devm_uio_register_device - Resource managed uio_register_device()
+ * __devm_uio_register_device - Resource managed uio_register_device()
* @owner: module that creates the new device
* @parent: parent device
* @info: UIO device capabilities
diff --git a/include/linux/uio_driver.h b/include/linux/uio_driver.h
index 54bf6b118401..47c5962b876b 100644
--- a/include/linux/uio_driver.h
+++ b/include/linux/uio_driver.h
@@ -117,6 +117,14 @@ extern int __must_check
struct uio_info *info);
/* use a define to avoid include chaining to get THIS_MODULE */
+
+/**
+ * uio_register_device - register a new userspace IO device
+ * @parent: parent device
+ * @info: UIO device capabilities
+ *
+ * returns zero on success or a negative error code.
+ */
#define uio_register_device(parent, info) \
__uio_register_device(THIS_MODULE, parent, info)
@@ -129,6 +137,14 @@ extern int __must_check
struct uio_info *info);
/* use a define to avoid include chaining to get THIS_MODULE */
+
+/**
+ * devm_uio_register_device - Resource managed uio_register_device()
+ * @parent: parent device
+ * @info: UIO device capabilities
+ *
+ * returns zero on success or a negative error code.
+ */
#define devm_uio_register_device(parent, info) \
__devm_uio_register_device(THIS_MODULE, parent, info)
--
2.26.2
Some functions have different names between their prototypes
and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/ata/libata-core.c | 2 +-
drivers/ata/libata-eh.c | 2 +-
drivers/ata/libata-scsi.c | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/drivers/ata/libata-core.c b/drivers/ata/libata-core.c
index f546a5761c4f..61c762961ca8 100644
--- a/drivers/ata/libata-core.c
+++ b/drivers/ata/libata-core.c
@@ -5616,7 +5616,7 @@ int ata_host_start(struct ata_host *host)
EXPORT_SYMBOL_GPL(ata_host_start);
/**
- * ata_sas_host_init - Initialize a host struct for sas (ipr, libsas)
+ * ata_host_init - Initialize a host struct for sas (ipr, libsas)
* @host: host to initialize
* @dev: device host is attached to
* @ops: port_ops
diff --git a/drivers/ata/libata-eh.c b/drivers/ata/libata-eh.c
index d912eaa65c94..b6f92050e60c 100644
--- a/drivers/ata/libata-eh.c
+++ b/drivers/ata/libata-eh.c
@@ -1115,7 +1115,7 @@ void ata_eh_freeze_port(struct ata_port *ap)
EXPORT_SYMBOL_GPL(ata_eh_freeze_port);
/**
- * ata_port_thaw_port - EH helper to thaw port
+ * ata_eh_thaw_port - EH helper to thaw port
* @ap: ATA port to thaw
*
* Thaw frozen port @ap.
diff --git a/drivers/ata/libata-scsi.c b/drivers/ata/libata-scsi.c
index 70431912dc63..48b8934970f3 100644
--- a/drivers/ata/libata-scsi.c
+++ b/drivers/ata/libata-scsi.c
@@ -1003,7 +1003,7 @@ void ata_scsi_sdev_config(struct scsi_device *sdev)
}
/**
- * atapi_drain_needed - Check whether data transfer may overflow
+ * ata_scsi_dma_need_drain - Check whether data transfer may overflow
* @rq: request to be checked
*
* ATAPI commands which transfer variable length data to host
--
2.26.2
Kernel-doc markups should use this format:
identifier - description
Fix some issues on mm files:
1) The definition for get_user_pages_locked() doesn't follow
it. Also, it expects a short descrpition at the header,
followed by a long one, after the parameters. Fix it.
2) Kernel-doc requires that a kernel-doc markup to be immediatly
below the function prototype, as otherwise it will rename it.
So, move get_pfnblock_flags_mask() description to the right
place.
3) Make invalidate_mapping_pagevec() to also follow the
expected kernel-doc format.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
mm/gup.c | 24 +++++++++++++-----------
mm/page_alloc.c | 16 ++++++++--------
mm/truncate.c | 10 ++++++++--
3 files changed, 29 insertions(+), 21 deletions(-)
diff --git a/mm/gup.c b/mm/gup.c
index 102877ed77a4..3dc7c0fe9231 100644
--- a/mm/gup.c
+++ b/mm/gup.c
@@ -1926,7 +1926,19 @@ long get_user_pages(unsigned long start, unsigned long nr_pages,
EXPORT_SYMBOL(get_user_pages);
/**
- * get_user_pages_locked() is suitable to replace the form:
+ * get_user_pages_locked() - variant of get_user_pages()
+ *
+ * @start: starting user address
+ * @nr_pages: number of pages from start to pin
+ * @gup_flags: flags modifying lookup behaviour
+ * @pages: array that receives pointers to the pages pinned.
+ * Should be at least nr_pages long. Or NULL, if caller
+ * only intends to ensure the pages are faulted in.
+ * @locked: pointer to lock flag indicating whether lock is held and
+ * subsequently whether VM_FAULT_RETRY functionality can be
+ * utilised. Lock must initially be held.
+ *
+ * It is suitable to replace the form:
*
* mmap_read_lock(mm);
* do_something()
@@ -1942,16 +1954,6 @@ EXPORT_SYMBOL(get_user_pages);
* if (locked)
* mmap_read_unlock(mm);
*
- * @start: starting user address
- * @nr_pages: number of pages from start to pin
- * @gup_flags: flags modifying lookup behaviour
- * @pages: array that receives pointers to the pages pinned.
- * Should be at least nr_pages long. Or NULL, if caller
- * only intends to ensure the pages are faulted in.
- * @locked: pointer to lock flag indicating whether lock is held and
- * subsequently whether VM_FAULT_RETRY functionality can be
- * utilised. Lock must initially be held.
- *
* We can leverage the VM_FAULT_RETRY functionality in the page fault
* paths better by using either get_user_pages_locked() or
* get_user_pages_unlocked().
diff --git a/mm/page_alloc.c b/mm/page_alloc.c
index 23f5066bd4a5..c94094ce1621 100644
--- a/mm/page_alloc.c
+++ b/mm/page_alloc.c
@@ -495,14 +495,6 @@ static inline int pfn_to_bitidx(struct page *page, unsigned long pfn)
return (pfn >> pageblock_order) * NR_PAGEBLOCK_BITS;
}
-/**
- * get_pfnblock_flags_mask - Return the requested group of flags for the pageblock_nr_pages block of pages
- * @page: The page within the block of interest
- * @pfn: The target page frame number
- * @mask: mask of bits that the caller is interested in
- *
- * Return: pageblock_bits flags
- */
static __always_inline
unsigned long __get_pfnblock_flags_mask(struct page *page,
unsigned long pfn,
@@ -521,6 +513,14 @@ unsigned long __get_pfnblock_flags_mask(struct page *page,
return (word >> bitidx) & mask;
}
+/**
+ * get_pfnblock_flags_mask - Return the requested group of flags for the pageblock_nr_pages block of pages
+ * @page: The page within the block of interest
+ * @pfn: The target page frame number
+ * @mask: mask of bits that the caller is interested in
+ *
+ * Return: pageblock_bits flags
+ */
unsigned long get_pfnblock_flags_mask(struct page *page, unsigned long pfn,
unsigned long mask)
{
diff --git a/mm/truncate.c b/mm/truncate.c
index 18cec39a9f53..58fa634cf4f8 100644
--- a/mm/truncate.c
+++ b/mm/truncate.c
@@ -637,9 +637,15 @@ unsigned long invalidate_mapping_pages(struct address_space *mapping,
EXPORT_SYMBOL(invalidate_mapping_pages);
/**
- * This helper is similar with the above one, except that it accounts for pages
- * that are likely on a pagevec and count them in @nr_pagevec, which will used by
+ * invalidate_mapping_pagevec - This helper is similar with
+ * invalidate_mapping_pages(), except that it accounts for pages tat are
+ * likely on a pagevec and count them in @nr_pagevec, which will used by
* the caller.
+ *
+ * @mapping: the address_space which holds the pages to invalidate
+ * @start: the offset 'from' which to invalidate
+ * @end: the offset 'to' which to invalidate (inclusive)
+ *
*/
void invalidate_mapping_pagevec(struct address_space *mapping,
pgoff_t start, pgoff_t end, unsigned long *nr_pagevec)
--
2.26.2
Some functions have different names between their prototypes
and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c | 2 +-
drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 2 +-
include/uapi/drm/amdgpu_drm.h | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
index df110afa97bf..a5f73a267fe5 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
@@ -2166,7 +2166,7 @@ struct amdgpu_bo_va *amdgpu_vm_bo_add(struct amdgpu_device *adev,
/**
- * amdgpu_vm_bo_insert_mapping - insert a new mapping
+ * amdgpu_vm_bo_insert_map - insert a new mapping
*
* @adev: amdgpu_device pointer
* @bo_va: bo_va to store the address
diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
index 0c6b7c5ecfec..795bad307497 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
@@ -528,7 +528,7 @@ int amdgpu_vram_mgr_alloc_sgt(struct amdgpu_device *adev,
}
/**
- * amdgpu_vram_mgr_alloc_sgt - allocate and fill a sg table
+ * amdgpu_vram_mgr_free_sgt - allocate and fill a sg table
*
* @adev: amdgpu device pointer
* @sgt: sg table to free
diff --git a/include/uapi/drm/amdgpu_drm.h b/include/uapi/drm/amdgpu_drm.h
index c5ff2b275fcd..791a1d597d2a 100644
--- a/include/uapi/drm/amdgpu_drm.h
+++ b/include/uapi/drm/amdgpu_drm.h
@@ -667,7 +667,7 @@ struct drm_amdgpu_cs_chunk_data {
};
};
-/**
+/*
* Query h/w info: Flag that this is integrated (a.h.a. fusion) GPU
*
*/
--
2.26.2
Some identifiers have different names between their prototypes
and the kernel-doc markup.
In the specific case of netif_subqueue_stopped(), keep the
current markup for __netif_subqueue_stopped(), adding a
new one for netif_subqueue_stopped().
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/netdevice.h | 11 +++++++++--
1 file changed, 9 insertions(+), 2 deletions(-)
diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
index 964b494b0e8d..db79ab7580dd 100644
--- a/include/linux/netdevice.h
+++ b/include/linux/netdevice.h
@@ -1490,7 +1490,7 @@ struct net_device_ops {
};
/**
- * enum net_device_priv_flags - &struct net_device priv_flags
+ * enum netdev_priv_flags - &struct net_device priv_flags
*
* These are the &struct net_device, they are only set internally
* by drivers and used in the kernel. These flags are invisible to
@@ -3576,7 +3576,7 @@ static inline void netif_stop_subqueue(struct net_device *dev, u16 queue_index)
}
/**
- * netif_subqueue_stopped - test status of subqueue
+ * __netif_subqueue_stopped - test status of subqueue
* @dev: network device
* @queue_index: sub queue index
*
@@ -3590,6 +3590,13 @@ static inline bool __netif_subqueue_stopped(const struct net_device *dev,
return netif_tx_queue_stopped(txq);
}
+/**
+ * netif_subqueue_stopped - test status of subqueue
+ * @dev: network device
+ * @skb: sub queue buffer pointer
+ *
+ * Check individual transmit queue of a device with multiple transmit queues.
+ */
static inline bool netif_subqueue_stopped(const struct net_device *dev,
struct sk_buff *skb)
{
--
2.26.2
dm_comressor_info -> dm_compressor_info
The kernel-doc markup is right, but the struct itself
and their references contain a typo.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 2 +-
drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h | 6 +++---
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
index bb1bc7f5d149..48ec0535d92f 100644
--- a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
+++ b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
@@ -583,7 +583,7 @@ static void amdgpu_dm_fbc_init(struct drm_connector *connector)
{
struct drm_device *dev = connector->dev;
struct amdgpu_device *adev = drm_to_adev(dev);
- struct dm_comressor_info *compressor = &adev->dm.compressor;
+ struct dm_compressor_info *compressor = &adev->dm.compressor;
struct amdgpu_dm_connector *aconn = to_amdgpu_dm_connector(connector);
struct drm_display_mode *mode;
unsigned long max_size = 0;
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 34f6369bf51f..a8a0e8cb1a11 100644
--- a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
+++ b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
@@ -86,7 +86,7 @@ struct irq_list_head {
* @bo_ptr: Pointer to the buffer object
* @gpu_addr: MMIO gpu addr
*/
-struct dm_comressor_info {
+struct dm_compressor_info {
void *cpu_addr;
struct amdgpu_bo *bo_ptr;
uint64_t gpu_addr;
@@ -148,7 +148,7 @@ struct amdgpu_dm_backlight_caps {
* @soc_bounding_box: SOC bounding box values provided by gpu_info FW
* @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
+ * @compressor: Frame buffer compression buffer. See &struct dm_compressor_info
* @force_timing_sync: set via debugfs. When set, indicates that all connected
* displays will be forced to synchronize.
*/
@@ -324,7 +324,7 @@ struct amdgpu_display_manager {
struct drm_atomic_state *cached_state;
struct dc_state *cached_dc_state;
- struct dm_comressor_info compressor;
+ struct dm_compressor_info compressor;
const struct firmware *fw_dmcu;
uint32_t dmcu_fw_version;
--
2.26.2
Kernel-doc markup should use this format:
identifier - description
Also, some enums are using wrong names at the kernel-doc
markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/edac/edac_device.h | 11 +++++------
include/linux/edac.h | 4 ++--
2 files changed, 7 insertions(+), 8 deletions(-)
diff --git a/drivers/edac/edac_device.h b/drivers/edac/edac_device.h
index c4c0e0bdce14..f90cbbb2ff73 100644
--- a/drivers/edac/edac_device.h
+++ b/drivers/edac/edac_device.h
@@ -258,7 +258,7 @@ extern struct edac_device_ctl_info *edac_device_alloc_ctl_info(
extern void edac_device_free_ctl_info(struct edac_device_ctl_info *ctl_info);
/**
- * edac_device_add_device: Insert the 'edac_dev' structure into the
+ * edac_device_add_device - Insert the 'edac_dev' structure into the
* edac_device global list and create sysfs entries associated with
* edac_device structure.
*
@@ -271,9 +271,8 @@ extern void edac_device_free_ctl_info(struct edac_device_ctl_info *ctl_info);
extern int edac_device_add_device(struct edac_device_ctl_info *edac_dev);
/**
- * edac_device_del_device:
- * Remove sysfs entries for specified edac_device structure and
- * then remove edac_device structure from global list
+ * edac_device_del_device - Remove sysfs entries for specified edac_device
+ * structure and then remove edac_device structure from global list
*
* @dev:
* Pointer to struct &device representing the edac device
@@ -286,7 +285,7 @@ extern int edac_device_add_device(struct edac_device_ctl_info *edac_dev);
extern struct edac_device_ctl_info *edac_device_del_device(struct device *dev);
/**
- * Log correctable errors.
+ * edac_device_handle_ce_count - Log correctable errors.
*
* @edac_dev: pointer to struct &edac_device_ctl_info
* @inst_nr: number of the instance where the CE error happened
@@ -299,7 +298,7 @@ void edac_device_handle_ce_count(struct edac_device_ctl_info *edac_dev,
const char *msg);
/**
- * Log uncorrectable errors.
+ * edac_device_handle_ue_count - Log uncorrectable errors.
*
* @edac_dev: pointer to struct &edac_device_ctl_info
* @inst_nr: number of the instance where the CE error happened
diff --git a/include/linux/edac.h b/include/linux/edac.h
index 15e8f3d8a895..52d7487f6bd4 100644
--- a/include/linux/edac.h
+++ b/include/linux/edac.h
@@ -229,7 +229,7 @@ enum mem_type {
#define MEM_FLAG_NVDIMM BIT(MEM_NVDIMM)
/**
- * enum edac-type - Error Detection and Correction capabilities and mode
+ * enum edac_type - Error Detection and Correction capabilities and mode
* @EDAC_UNKNOWN: Unknown if ECC is available
* @EDAC_NONE: Doesn't support ECC
* @EDAC_RESERVED: Reserved ECC type
@@ -309,7 +309,7 @@ enum scrub_type {
#define OP_OFFLINE 0x300
/**
- * enum edac_mc_layer - memory controller hierarchy layer
+ * enum edac_mc_layer_type - memory controller hierarchy layer
*
* @EDAC_MC_LAYER_BRANCH: memory layer is named "branch"
* @EDAC_MC_LAYER_CHANNEL: memory layer is named "channel"
--
2.26.2
The include/linux/genalloc.h file defined this typedef:
typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
Because it has a type composite of two words (unsigned long),
the parser gets the typedef name wrong:
.. c:macro:: long
**Typedef**: Allocation callback function type definition
Fix the regex in order to accept composite types when
defining a typedef for a function pointer.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
scripts/kernel-doc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..311d213ee74d 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1438,7 +1438,7 @@ sub dump_typedef($$) {
$x =~ s@/\*.*?\*/@@gos; # strip comments.
# Parse function prototypes
- if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+ if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
# Function typedefs
--
2.26.2
Two markups are at the wrong place. Kernel-doc only
support having the comment just before the identifier.
Also, some identifiers have different names between their
prototypes and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
fs/dcache.c | 72 +++++++++++++++++++++++++--------------------------
fs/inode.c | 4 +--
fs/seq_file.c | 5 ++--
fs/super.c | 12 ++++-----
4 files changed, 47 insertions(+), 46 deletions(-)
diff --git a/fs/dcache.c b/fs/dcache.c
index ea0485861d93..6eabb48a49fc 100644
--- a/fs/dcache.c
+++ b/fs/dcache.c
@@ -456,23 +456,6 @@ static void d_lru_shrink_move(struct list_lru_one *lru, struct dentry *dentry,
list_lru_isolate_move(lru, &dentry->d_lru, list);
}
-/**
- * d_drop - drop a dentry
- * @dentry: dentry to drop
- *
- * d_drop() unhashes the entry from the parent dentry hashes, so that it won't
- * be found through a VFS lookup any more. Note that this is different from
- * deleting the dentry - d_delete will try to mark the dentry negative if
- * possible, giving a successful _negative_ lookup, while d_drop will
- * just make the cache lookup fail.
- *
- * d_drop() is used mainly for stuff that wants to invalidate a dentry for some
- * reason (NFS timeouts or autofs deletes).
- *
- * __d_drop requires dentry->d_lock
- * ___d_drop doesn't mark dentry as "unhashed"
- * (dentry->d_hash.pprev will be LIST_POISON2, not NULL).
- */
static void ___d_drop(struct dentry *dentry)
{
struct hlist_bl_head *b;
@@ -501,6 +484,23 @@ void __d_drop(struct dentry *dentry)
}
EXPORT_SYMBOL(__d_drop);
+/**
+ * d_drop - drop a dentry
+ * @dentry: dentry to drop
+ *
+ * d_drop() unhashes the entry from the parent dentry hashes, so that it won't
+ * be found through a VFS lookup any more. Note that this is different from
+ * deleting the dentry - d_delete will try to mark the dentry negative if
+ * possible, giving a successful _negative_ lookup, while d_drop will
+ * just make the cache lookup fail.
+ *
+ * d_drop() is used mainly for stuff that wants to invalidate a dentry for some
+ * reason (NFS timeouts or autofs deletes).
+ *
+ * __d_drop requires dentry->d_lock
+ * ___d_drop doesn't mark dentry as "unhashed"
+ * (dentry->d_hash.pprev will be LIST_POISON2, not NULL).
+ */
void d_drop(struct dentry *dentry)
{
spin_lock(&dentry->d_lock);
@@ -989,6 +989,25 @@ struct dentry *d_find_any_alias(struct inode *inode)
}
EXPORT_SYMBOL(d_find_any_alias);
+static struct dentry *__d_find_alias(struct inode *inode)
+{
+ struct dentry *alias;
+
+ if (S_ISDIR(inode->i_mode))
+ return __d_find_any_alias(inode);
+
+ hlist_for_each_entry(alias, &inode->i_dentry, d_u.d_alias) {
+ spin_lock(&alias->d_lock);
+ if (!d_unhashed(alias)) {
+ __dget_dlock(alias);
+ spin_unlock(&alias->d_lock);
+ return alias;
+ }
+ spin_unlock(&alias->d_lock);
+ }
+ return NULL;
+}
+
/**
* d_find_alias - grab a hashed alias of inode
* @inode: inode in question
@@ -1003,25 +1022,6 @@ EXPORT_SYMBOL(d_find_any_alias);
* If the inode has an IS_ROOT, DCACHE_DISCONNECTED alias, then prefer
* any other hashed alias over that one.
*/
-static struct dentry *__d_find_alias(struct inode *inode)
-{
- struct dentry *alias;
-
- if (S_ISDIR(inode->i_mode))
- return __d_find_any_alias(inode);
-
- hlist_for_each_entry(alias, &inode->i_dentry, d_u.d_alias) {
- spin_lock(&alias->d_lock);
- if (!d_unhashed(alias)) {
- __dget_dlock(alias);
- spin_unlock(&alias->d_lock);
- return alias;
- }
- spin_unlock(&alias->d_lock);
- }
- return NULL;
-}
-
struct dentry *d_find_alias(struct inode *inode)
{
struct dentry *de = NULL;
diff --git a/fs/inode.c b/fs/inode.c
index 9d78c37b00b8..aad3dcf2e259 100644
--- a/fs/inode.c
+++ b/fs/inode.c
@@ -1496,7 +1496,7 @@ struct inode *find_inode_rcu(struct super_block *sb, unsigned long hashval,
EXPORT_SYMBOL(find_inode_rcu);
/**
- * find_inode_by_rcu - Find an inode in the inode cache
+ * find_inode_by_ino_rcu - Find an inode in the inode cache
* @sb: Super block of file system to search
* @ino: The inode number to match
*
@@ -1778,7 +1778,7 @@ static int update_time(struct inode *inode, struct timespec64 *time, int flags)
}
/**
- * touch_atime - update the access time
+ * atime_needs_update - update the access time
* @path: the &struct path to update
* @inode: inode to update
*
diff --git a/fs/seq_file.c b/fs/seq_file.c
index 31219c1db17d..f0b933179a74 100644
--- a/fs/seq_file.c
+++ b/fs/seq_file.c
@@ -653,7 +653,8 @@ void seq_puts(struct seq_file *m, const char *s)
EXPORT_SYMBOL(seq_puts);
/**
- * A helper routine for putting decimal numbers without rich format of printf().
+ * seq_put_decimal_ull_width - A helper routine for putting decimal numbers
+ * without rich format of printf().
* only 'unsigned long long' is supported.
* @m: seq_file identifying the buffer to which data should be written
* @delimiter: a string which is printed before the number
@@ -1028,7 +1029,7 @@ struct hlist_node *seq_hlist_next_rcu(void *v,
EXPORT_SYMBOL(seq_hlist_next_rcu);
/**
- * seq_hlist_start_precpu - start an iteration of a percpu hlist array
+ * seq_hlist_start_percpu - start an iteration of a percpu hlist array
* @head: pointer to percpu array of struct hlist_heads
* @cpu: pointer to cpu "cursor"
* @pos: start position of sequence
diff --git a/fs/super.c b/fs/super.c
index a51c2083cd6b..3f7a4c10ef0a 100644
--- a/fs/super.c
+++ b/fs/super.c
@@ -1820,12 +1820,6 @@ int freeze_super(struct super_block *sb)
}
EXPORT_SYMBOL(freeze_super);
-/**
- * thaw_super -- unlock filesystem
- * @sb: the super to thaw
- *
- * Unlocks the filesystem and marks it writeable again after freeze_super().
- */
static int thaw_super_locked(struct super_block *sb)
{
int error;
@@ -1861,6 +1855,12 @@ static int thaw_super_locked(struct super_block *sb)
return 0;
}
+/**
+ * thaw_super -- unlock filesystem
+ * @sb: the super to thaw
+ *
+ * Unlocks the filesystem and marks it writeable again after freeze_super().
+ */
int thaw_super(struct super_block *sb)
{
down_write(&sb->s_umount);
--
2.26.2
A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
lib/crc7.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/lib/crc7.c b/lib/crc7.c
index 6a848d73e804..3848e313b722 100644
--- a/lib/crc7.c
+++ b/lib/crc7.c
@@ -51,7 +51,7 @@ const u8 crc7_be_syndrome_table[256] = {
EXPORT_SYMBOL(crc7_be_syndrome_table);
/**
- * crc7 - update the CRC7 for the data buffer
+ * crc7_be - update the CRC7 for the data buffer
* @crc: previous CRC7 value
* @buffer: data pointer
* @len: number of bytes in the buffer
--
2.26.2
spi_split_tranfers_maxsize -> spi_split_transfers_maxsize
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/spi/spi.c | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/drivers/spi/spi.c b/drivers/spi/spi.c
index 0cab239d8e7f..22679c8645db 100644
--- a/drivers/spi/spi.c
+++ b/drivers/spi/spi.c
@@ -3193,9 +3193,9 @@ static int __spi_split_transfer_maxsize(struct spi_controller *ctlr,
}
/**
- * spi_split_tranfers_maxsize - split spi transfers into multiple transfers
- * when an individual transfer exceeds a
- * certain size
+ * spi_split_transfers_maxsize - split spi transfers into multiple transfers
+ * when an individual transfer exceeds a
+ * certain size
* @ctlr: the @spi_controller for this transfer
* @msg: the @spi_message to transform
* @maxsize: the maximum when to apply this
--
2.26.2
It seems that the function was renamed. kernel-doc markup
should follow it.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/regulator/core.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c
index a4ffd71696da..79d00e7039d9 100644
--- a/drivers/regulator/core.c
+++ b/drivers/regulator/core.c
@@ -5529,7 +5529,7 @@ void regulator_set_drvdata(struct regulator *regulator, void *data)
EXPORT_SYMBOL_GPL(regulator_set_drvdata);
/**
- * regulator_get_id - get regulator ID
+ * rdev_get_id - get regulator ID
* @rdev: regulator
*/
int rdev_get_id(struct regulator_dev *rdev)
--
2.26.2
Some identifiers have different names between their prototypes
and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/mtd/nand/raw/nand_bbt.c | 2 +-
include/linux/mtd/rawnand.h | 3 ++-
2 files changed, 3 insertions(+), 2 deletions(-)
diff --git a/drivers/mtd/nand/raw/nand_bbt.c b/drivers/mtd/nand/raw/nand_bbt.c
index 344a24fd2ca8..dced32a126d9 100644
--- a/drivers/mtd/nand/raw/nand_bbt.c
+++ b/drivers/mtd/nand/raw/nand_bbt.c
@@ -1087,7 +1087,7 @@ static int nand_update_bbt(struct nand_chip *this, loff_t offs)
}
/**
- * mark_bbt_regions - [GENERIC] mark the bad block table regions
+ * mark_bbt_region - [GENERIC] mark the bad block table regions
* @this: the NAND device
* @td: bad block table descriptor
*
diff --git a/include/linux/mtd/rawnand.h b/include/linux/mtd/rawnand.h
index aac07940de09..ace1ce70f5e4 100644
--- a/include/linux/mtd/rawnand.h
+++ b/include/linux/mtd/rawnand.h
@@ -1286,7 +1286,8 @@ static inline bool nand_is_slc(struct nand_chip *chip)
}
/**
- * Check if the opcode's address should be sent only on the lower 8 bits
+ * nand_opcode_8bits - Check if the opcode's address should be sent only on the
+ * lower 8 bits
* @command: opcode to check
*/
static inline int nand_opcode_8bits(unsigned int command)
--
2.26.2
Some identifiers have different names between their prototypes
and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/vme/vme.c | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/drivers/vme/vme.c b/drivers/vme/vme.c
index b398293980b6..bb4fed52f74d 100644
--- a/drivers/vme/vme.c
+++ b/drivers/vme/vme.c
@@ -73,7 +73,7 @@ static struct vme_bridge *find_bridge(struct vme_resource *resource)
}
/**
- * vme_free_consistent - Allocate contiguous memory.
+ * vme_alloc_consistent - Allocate contiguous memory.
* @resource: Pointer to VME resource.
* @size: Size of allocation required.
* @dma: Pointer to variable to store physical address of allocation.
@@ -647,7 +647,7 @@ int vme_master_get(struct vme_resource *resource, int *enabled,
EXPORT_SYMBOL(vme_master_get);
/**
- * vme_master_write - Read data from VME space into a buffer.
+ * vme_master_read - Read data from VME space into a buffer.
* @resource: Pointer to VME master resource.
* @buf: Pointer to buffer where data should be transferred.
* @count: Number of bytes to transfer.
--
2.26.2
A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/hsi/hsi_core.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/hsi/hsi_core.c b/drivers/hsi/hsi_core.c
index 47f0208aa7c3..c3fb5beb846e 100644
--- a/drivers/hsi/hsi_core.c
+++ b/drivers/hsi/hsi_core.c
@@ -352,7 +352,7 @@ static void hsi_port_release(struct device *dev)
}
/**
- * hsi_unregister_port - Unregister an HSI port
+ * hsi_port_unregister_clients - Unregister an HSI port
* @port: The HSI port to unregister
*/
void hsi_port_unregister_clients(struct hsi_port *port)
--
2.26.2
Kernel-doc markup should use this format:
identifier - description
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
arch/x86/kernel/cpu/mtrr/mtrr.c | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/arch/x86/kernel/cpu/mtrr/mtrr.c b/arch/x86/kernel/cpu/mtrr/mtrr.c
index 6a80f36b5d59..08a30c8e9431 100644
--- a/arch/x86/kernel/cpu/mtrr/mtrr.c
+++ b/arch/x86/kernel/cpu/mtrr/mtrr.c
@@ -813,7 +813,8 @@ void mtrr_ap_init(void)
}
/**
- * Save current fixed-range MTRR state of the first cpu in cpu_online_mask.
+ * mtrr_save_state - Save current fixed-range MTRR state of the first
+ * cpu in cpu_online_mask.
*/
void mtrr_save_state(void)
{
--
2.26.2
A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/misc/mei/bus.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/misc/mei/bus.c b/drivers/misc/mei/bus.c
index 9cdaa7f3af23..04b904e3a56a 100644
--- a/drivers/misc/mei/bus.c
+++ b/drivers/misc/mei/bus.c
@@ -1037,7 +1037,7 @@ static struct mei_cl_device *mei_cl_bus_dev_alloc(struct mei_device *bus,
}
/**
- * mei_cl_dev_setup - setup me client device
+ * mei_cl_bus_dev_setup - setup me client device
* run fix up routines and set the device name
*
* @bus: mei device
--
2.26.2
Kernel-doc only supports having the comment just before
the identifier.
The markup for init_completion is actually for
__init_completion.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Thats said, IMHO, it would make sense to simply
rename __init_completion() to init_completion() and drop
this define:
#define init_completion(x) __init_completion(x)
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/completion.h | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
diff --git a/include/linux/completion.h b/include/linux/completion.h
index bf8e77001f18..ff354918dbf4 100644
--- a/include/linux/completion.h
+++ b/include/linux/completion.h
@@ -29,6 +29,14 @@ struct completion {
};
#define init_completion_map(x, m) __init_completion(x)
+
+/**
+ * init_completion - Initialize a dynamically allocated completion
+ * @x: pointer to completion structure that is to be initialized
+ *
+ * This macro will initialize a dynamically created completion
+ * structure.
+ */
#define init_completion(x) __init_completion(x)
static inline void complete_acquire(struct completion *x) {}
static inline void complete_release(struct completion *x) {}
@@ -76,7 +84,7 @@ static inline void complete_release(struct completion *x) {}
#endif
/**
- * init_completion - Initialize a dynamically allocated completion
+ * __init_completion - Initialize a dynamically allocated completion
* @x: pointer to completion structure that is to be initialized
*
* This inline function will initialize a dynamically created completion
--
2.26.2
A kernel-doc markup should start with the identifier on its
first line.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/drm/drm_print.h | 20 +++++++++++++++++---
1 file changed, 17 insertions(+), 3 deletions(-)
diff --git a/include/drm/drm_print.h b/include/drm/drm_print.h
index 1c9417430d08..f32d179e139d 100644
--- a/include/drm/drm_print.h
+++ b/include/drm/drm_print.h
@@ -338,7 +338,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category,
const char *format, ...);
/**
- * Error output.
+ * DRM_DEV_ERROR() - Error output.
*
* @dev: device pointer
* @fmt: printf() like format string.
@@ -347,10 +347,12 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category,
drm_dev_printk(dev, KERN_ERR, "*ERROR* " fmt, ##__VA_ARGS__)
/**
- * Rate limited error output. Like DRM_ERROR() but won't flood the log.
+ * DRM_DEV_ERROR_RATELIMITED() - Rate limited error output.
*
* @dev: device pointer
* @fmt: printf() like format string.
+ *
+ * Like DRM_ERROR() but won't flood the log.
*/
#define DRM_DEV_ERROR_RATELIMITED(dev, fmt, ...) \
({ \
@@ -375,15 +377,27 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category,
})
/**
- * Debug output.
+ * DRM_DEV_DEBUG() - Debug output for generic drm code
*
* @dev: device pointer
* @fmt: printf() like format string.
*/
#define DRM_DEV_DEBUG(dev, fmt, ...) \
drm_dev_dbg(dev, DRM_UT_CORE, fmt, ##__VA_ARGS__)
+/**
+ * DRM_DEV_DEBUG_DRIVER() - Debug output for vendor specific part of the driver
+ *
+ * @dev: device pointer
+ * @fmt: printf() like format string.
+ */
#define DRM_DEV_DEBUG_DRIVER(dev, fmt, ...) \
drm_dev_dbg(dev, DRM_UT_DRIVER, fmt, ##__VA_ARGS__)
+/**
+ * DRM_DEV_DEBUG_KMS() - Debug output for modesetting code
+ *
+ * @dev: device pointer
+ * @fmt: printf() like format string.
+ */
#define DRM_DEV_DEBUG_KMS(dev, fmt, ...) \
drm_dev_dbg(dev, DRM_UT_KMS, fmt, ##__VA_ARGS__)
--
2.26.2
The kernel-doc markups on this file are weird: they don't
follow what's specified at:
Documentation/doc-guide/kernel-doc.rst
In particular, markups should use this format:
identifier - description
and not this:
identifier(args)
The way the definitions are inside this file cause the
parser to completely miss the identifier name of each
function.
This prevents improving the script to do some needed validation
tests.
Address this part. Yet, furter changes are needed in order
for it to fully follow the specs.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
tools/testing/selftests/kselftest_harness.h | 66 ++++++++++-----------
1 file changed, 33 insertions(+), 33 deletions(-)
diff --git a/tools/testing/selftests/kselftest_harness.h b/tools/testing/selftests/kselftest_harness.h
index f19804df244c..665d04f3b802 100644
--- a/tools/testing/selftests/kselftest_harness.h
+++ b/tools/testing/selftests/kselftest_harness.h
@@ -79,7 +79,7 @@
#endif
/**
- * TH_LOG(fmt, ...)
+ * TH_LOG()
*
* @fmt: format string
* @...: optional arguments
@@ -113,7 +113,7 @@
__FILE__, __LINE__, _metadata->name, ##__VA_ARGS__)
/**
- * SKIP(statement, fmt, ...)
+ * SKIP()
*
* @statement: statement to run after reporting SKIP
* @fmt: format string
@@ -136,7 +136,7 @@
} while (0)
/**
- * TEST(test_name) - Defines the test function and creates the registration
+ * TEST() - Defines the test function and creates the registration
* stub
*
* @test_name: test name
@@ -155,7 +155,7 @@
#define TEST(test_name) __TEST_IMPL(test_name, -1)
/**
- * TEST_SIGNAL(test_name, signal)
+ * TEST_SIGNAL()
*
* @test_name: test name
* @signal: signal number
@@ -195,7 +195,7 @@
struct __test_metadata __attribute__((unused)) *_metadata)
/**
- * FIXTURE_DATA(datatype_name) - Wraps the struct name so we have one less
+ * FIXTURE_DATA() - Wraps the struct name so we have one less
* argument to pass around
*
* @datatype_name: datatype name
@@ -212,7 +212,7 @@
#define FIXTURE_DATA(datatype_name) struct _test_data_##datatype_name
/**
- * FIXTURE(fixture_name) - Called once per fixture to setup the data and
+ * FIXTURE() - Called once per fixture to setup the data and
* register
*
* @fixture_name: fixture name
@@ -239,7 +239,7 @@
FIXTURE_DATA(fixture_name)
/**
- * FIXTURE_SETUP(fixture_name) - Prepares the setup function for the fixture.
+ * FIXTURE_SETUP() - Prepares the setup function for the fixture.
* *_metadata* is included so that EXPECT_* and ASSERT_* work correctly.
*
* @fixture_name: fixture name
@@ -265,7 +265,7 @@
__attribute__((unused)) *variant)
/**
- * FIXTURE_TEARDOWN(fixture_name)
+ * FIXTURE_TEARDOWN()
* *_metadata* is included so that EXPECT_* and ASSERT_* work correctly.
*
* @fixture_name: fixture name
@@ -286,7 +286,7 @@
FIXTURE_DATA(fixture_name) __attribute__((unused)) *self)
/**
- * FIXTURE_VARIANT(fixture_name) - Optionally called once per fixture
+ * FIXTURE_VARIANT() - Optionally called once per fixture
* to declare fixture variant
*
* @fixture_name: fixture name
@@ -305,7 +305,7 @@
#define FIXTURE_VARIANT(fixture_name) struct _fixture_variant_##fixture_name
/**
- * FIXTURE_VARIANT_ADD(fixture_name, variant_name) - Called once per fixture
+ * FIXTURE_VARIANT_ADD() - Called once per fixture
* variant to setup and register the data
*
* @fixture_name: fixture name
@@ -339,7 +339,7 @@
_##fixture_name##_##variant_name##_variant =
/**
- * TEST_F(fixture_name, test_name) - Emits test registration and helpers for
+ * TEST_F() - Emits test registration and helpers for
* fixture-based test cases
*
* @fixture_name: fixture name
@@ -432,7 +432,7 @@
*/
/**
- * ASSERT_EQ(expected, seen)
+ * ASSERT_EQ()
*
* @expected: expected value
* @seen: measured value
@@ -443,7 +443,7 @@
__EXPECT(expected, #expected, seen, #seen, ==, 1)
/**
- * ASSERT_NE(expected, seen)
+ * ASSERT_NE()
*
* @expected: expected value
* @seen: measured value
@@ -454,7 +454,7 @@
__EXPECT(expected, #expected, seen, #seen, !=, 1)
/**
- * ASSERT_LT(expected, seen)
+ * ASSERT_LT()
*
* @expected: expected value
* @seen: measured value
@@ -465,7 +465,7 @@
__EXPECT(expected, #expected, seen, #seen, <, 1)
/**
- * ASSERT_LE(expected, seen)
+ * ASSERT_LE()
*
* @expected: expected value
* @seen: measured value
@@ -476,7 +476,7 @@
__EXPECT(expected, #expected, seen, #seen, <=, 1)
/**
- * ASSERT_GT(expected, seen)
+ * ASSERT_GT()
*
* @expected: expected value
* @seen: measured value
@@ -487,7 +487,7 @@
__EXPECT(expected, #expected, seen, #seen, >, 1)
/**
- * ASSERT_GE(expected, seen)
+ * ASSERT_GE()
*
* @expected: expected value
* @seen: measured value
@@ -498,7 +498,7 @@
__EXPECT(expected, #expected, seen, #seen, >=, 1)
/**
- * ASSERT_NULL(seen)
+ * ASSERT_NULL()
*
* @seen: measured value
*
@@ -508,7 +508,7 @@
__EXPECT(NULL, "NULL", seen, #seen, ==, 1)
/**
- * ASSERT_TRUE(seen)
+ * ASSERT_TRUE()
*
* @seen: measured value
*
@@ -518,7 +518,7 @@
__EXPECT(0, "0", seen, #seen, !=, 1)
/**
- * ASSERT_FALSE(seen)
+ * ASSERT_FALSE()
*
* @seen: measured value
*
@@ -528,7 +528,7 @@
__EXPECT(0, "0", seen, #seen, ==, 1)
/**
- * ASSERT_STREQ(expected, seen)
+ * ASSERT_STREQ()
*
* @expected: expected value
* @seen: measured value
@@ -539,7 +539,7 @@
__EXPECT_STR(expected, seen, ==, 1)
/**
- * ASSERT_STRNE(expected, seen)
+ * ASSERT_STRNE()
*
* @expected: expected value
* @seen: measured value
@@ -550,7 +550,7 @@
__EXPECT_STR(expected, seen, !=, 1)
/**
- * EXPECT_EQ(expected, seen)
+ * EXPECT_EQ()
*
* @expected: expected value
* @seen: measured value
@@ -561,7 +561,7 @@
__EXPECT(expected, #expected, seen, #seen, ==, 0)
/**
- * EXPECT_NE(expected, seen)
+ * EXPECT_NE()
*
* @expected: expected value
* @seen: measured value
@@ -572,7 +572,7 @@
__EXPECT(expected, #expected, seen, #seen, !=, 0)
/**
- * EXPECT_LT(expected, seen)
+ * EXPECT_LT()
*
* @expected: expected value
* @seen: measured value
@@ -583,7 +583,7 @@
__EXPECT(expected, #expected, seen, #seen, <, 0)
/**
- * EXPECT_LE(expected, seen)
+ * EXPECT_LE()
*
* @expected: expected value
* @seen: measured value
@@ -594,7 +594,7 @@
__EXPECT(expected, #expected, seen, #seen, <=, 0)
/**
- * EXPECT_GT(expected, seen)
+ * EXPECT_GT()
*
* @expected: expected value
* @seen: measured value
@@ -605,7 +605,7 @@
__EXPECT(expected, #expected, seen, #seen, >, 0)
/**
- * EXPECT_GE(expected, seen)
+ * EXPECT_GE()
*
* @expected: expected value
* @seen: measured value
@@ -616,7 +616,7 @@
__EXPECT(expected, #expected, seen, #seen, >=, 0)
/**
- * EXPECT_NULL(seen)
+ * EXPECT_NULL()
*
* @seen: measured value
*
@@ -626,7 +626,7 @@
__EXPECT(NULL, "NULL", seen, #seen, ==, 0)
/**
- * EXPECT_TRUE(seen)
+ * EXPECT_TRUE()
*
* @seen: measured value
*
@@ -636,7 +636,7 @@
__EXPECT(0, "0", seen, #seen, !=, 0)
/**
- * EXPECT_FALSE(seen)
+ * EXPECT_FALSE()
*
* @seen: measured value
*
@@ -646,7 +646,7 @@
__EXPECT(0, "0", seen, #seen, ==, 0)
/**
- * EXPECT_STREQ(expected, seen)
+ * EXPECT_STREQ()
*
* @expected: expected value
* @seen: measured value
@@ -657,7 +657,7 @@
__EXPECT_STR(expected, seen, ==, 0)
/**
- * EXPECT_STRNE(expected, seen)
+ * EXPECT_STRNE()
*
* @expected: expected value
* @seen: measured value
--
2.26.2
Kernel-doc markups should use this format:
identifier - description
There is a common comment marked, instead, with kernel-doc
notation.
Some identifiers have different names between their prototypes
and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/sound/core.h | 3 ++-
include/sound/pcm.h | 4 ++--
include/uapi/sound/compress_offload.h | 2 +-
sound/core/control.c | 4 ++--
sound/core/pcm_dmaengine.c | 3 ++-
sound/core/pcm_lib.c | 2 +-
sound/core/pcm_native.c | 4 ++--
sound/soc/soc-core.c | 2 +-
sound/soc/soc-dapm.c | 2 +-
9 files changed, 14 insertions(+), 12 deletions(-)
diff --git a/include/sound/core.h b/include/sound/core.h
index 381a010a1bd4..0462c577d7a3 100644
--- a/include/sound/core.h
+++ b/include/sound/core.h
@@ -332,7 +332,8 @@ void __snd_printk(unsigned int level, const char *file, int line,
#define snd_BUG() WARN(1, "BUG?\n")
/**
- * Suppress high rates of output when CONFIG_SND_DEBUG is enabled.
+ * snd_printd_ratelimit - Suppress high rates of output when
+ * CONFIG_SND_DEBUG is enabled.
*/
#define snd_printd_ratelimit() printk_ratelimit()
diff --git a/include/sound/pcm.h b/include/sound/pcm.h
index 2ba5df2c9e23..2336bf9243e1 100644
--- a/include/sound/pcm.h
+++ b/include/sound/pcm.h
@@ -1284,8 +1284,8 @@ snd_pcm_sgbuf_get_ptr(struct snd_pcm_substream *substream, unsigned int ofs)
}
/**
- * snd_pcm_sgbuf_chunk_size - Compute the max size that fits within the contig.
- * page from the given size
+ * snd_pcm_sgbuf_get_chunk_size - Compute the max size that fits within the
+ * contig. page from the given size
* @substream: PCM substream
* @ofs: byte offset
* @size: byte size to examine
diff --git a/include/uapi/sound/compress_offload.h b/include/uapi/sound/compress_offload.h
index 7184265c0b0d..9555f31c8425 100644
--- a/include/uapi/sound/compress_offload.h
+++ b/include/uapi/sound/compress_offload.h
@@ -144,7 +144,7 @@ struct snd_compr_metadata {
__u32 value[8];
} __attribute__((packed, aligned(4)));
-/**
+/*
* compress path ioctl definitions
* SNDRV_COMPRESS_GET_CAPS: Query capability of DSP
* SNDRV_COMPRESS_GET_CODEC_CAPS: Query capability of a codec
diff --git a/sound/core/control.c b/sound/core/control.c
index 421ddc76f264..4373de42a5a0 100644
--- a/sound/core/control.c
+++ b/sound/core/control.c
@@ -1925,8 +1925,8 @@ EXPORT_SYMBOL(snd_ctl_unregister_ioctl);
#ifdef CONFIG_COMPAT
/**
- * snd_ctl_unregister_ioctl - de-register the device-specific compat 32bit
- * control-ioctls
+ * snd_ctl_unregister_ioctl_compat - de-register the device-specific compat
+ * 32bit control-ioctls
* @fcn: ioctl callback function to unregister
*/
int snd_ctl_unregister_ioctl_compat(snd_kctl_ioctl_func_t fcn)
diff --git a/sound/core/pcm_dmaengine.c b/sound/core/pcm_dmaengine.c
index 4d059ff2b2e4..4d0e8fe535a1 100644
--- a/sound/core/pcm_dmaengine.c
+++ b/sound/core/pcm_dmaengine.c
@@ -356,7 +356,8 @@ int snd_dmaengine_pcm_close(struct snd_pcm_substream *substream)
EXPORT_SYMBOL_GPL(snd_dmaengine_pcm_close);
/**
- * snd_dmaengine_pcm_release_chan_close - Close a dmaengine based PCM substream and release channel
+ * snd_dmaengine_pcm_close_release_chan - Close a dmaengine based PCM
+ * substream and release channel
* @substream: PCM substream
*
* Releases the DMA channel associated with the PCM substream.
diff --git a/sound/core/pcm_lib.c b/sound/core/pcm_lib.c
index d531e1bc2b81..bda3514c7b2d 100644
--- a/sound/core/pcm_lib.c
+++ b/sound/core/pcm_lib.c
@@ -490,7 +490,7 @@ void snd_pcm_set_ops(struct snd_pcm *pcm, int direction,
EXPORT_SYMBOL(snd_pcm_set_ops);
/**
- * snd_pcm_sync - set the PCM sync id
+ * snd_pcm_set_sync - set the PCM sync id
* @substream: the pcm substream
*
* Sets the PCM sync identifier for the card.
diff --git a/sound/core/pcm_native.c b/sound/core/pcm_native.c
index 9e0b2d73faf6..47b155a49226 100644
--- a/sound/core/pcm_native.c
+++ b/sound/core/pcm_native.c
@@ -112,7 +112,7 @@ void snd_pcm_stream_lock(struct snd_pcm_substream *substream)
EXPORT_SYMBOL_GPL(snd_pcm_stream_lock);
/**
- * snd_pcm_stream_lock - Unlock the PCM stream
+ * snd_pcm_stream_unlock - Unlock the PCM stream
* @substream: PCM substream
*
* This unlocks the PCM stream that has been locked via snd_pcm_stream_lock().
@@ -595,7 +595,7 @@ static void snd_pcm_sync_stop(struct snd_pcm_substream *substream)
}
/**
- * snd_pcm_hw_param_choose - choose a configuration defined by @params
+ * snd_pcm_hw_params_choose - choose a configuration defined by @params
* @pcm: PCM instance
* @params: the hw_params instance
*
diff --git a/sound/soc/soc-core.c b/sound/soc/soc-core.c
index ea3986a46c12..05a085f6dc7c 100644
--- a/sound/soc/soc-core.c
+++ b/sound/soc/soc-core.c
@@ -2341,7 +2341,7 @@ struct snd_soc_dai *snd_soc_register_dai(struct snd_soc_component *component,
}
/**
- * snd_soc_unregister_dai - Unregister DAIs from the ASoC core
+ * snd_soc_unregister_dais - Unregister DAIs from the ASoC core
*
* @component: The component for which the DAIs should be unregistered
*/
diff --git a/sound/soc/soc-dapm.c b/sound/soc/soc-dapm.c
index 980f2c330b87..7f87b449f950 100644
--- a/sound/soc/soc-dapm.c
+++ b/sound/soc/soc-dapm.c
@@ -1276,7 +1276,7 @@ static int is_connected_input_ep(struct snd_soc_dapm_widget *widget,
}
/**
- * snd_soc_dapm_get_connected_widgets - query audio path and it's widgets.
+ * snd_soc_dapm_dai_get_connected_widgets - query audio path and it's widgets.
* @dai: the soc DAI.
* @stream: stream direction.
* @list: list of active widgets for this stream.
--
2.26.2
Kernel-doc currently expects that the kernel-doc markup to come
just before the function/enum/struct/union/typedef prototype.
Yet, if it find things like:
/**
* refcount_add - add a value to a refcount
* @i: the value to add to the refcount
* @r: the refcount
*/
static inline void __refcount_add(int i, refcount_t *r, int *oldp);
static inline void refcount_add(int i, refcount_t *r);
Kernel-doc will do the wrong thing:
foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add'
.. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp)
add a value to a refcount
**Parameters**
``int i``
the value to add to the refcount
``refcount_t *r``
the refcount
``int *oldp``
*undescribed*
Basically, it will document "__refcount_add" with the kernel-doc
markup for refcount_add.
If both functions have the same arguments, this won't even
produce any warning!
Add a logic to check if the kernel-doc identifier matches the actual
name of the C function or data structure that will be documented.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
scripts/kernel-doc | 62 ++++++++++++++++++++++++++++++++++------------
1 file changed, 46 insertions(+), 16 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 311d213ee74d..1371cd45f78b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -382,6 +382,9 @@ my $inline_doc_state;
# 'function', 'struct', 'union', 'enum', 'typedef'
my $decl_type;
+# Name of the kernel-doc identifier for non-DOC markups
+my $identifier;
+
my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
my $doc_end = '\*/';
my $doc_com = '\s*\*\s*';
@@ -1203,6 +1206,11 @@ sub dump_struct($$) {
$declaration_name = $2;
my $members = $3;
+ if ($identifier ne $declaration_name) {
+ print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
+ return;
+ }
+
# ignore members marked private:
$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
$members =~ s/\/\*\s*private:.*//gosi;
@@ -1391,6 +1399,11 @@ sub dump_enum($$) {
}
if ($declaration_name) {
+ if ($identifier ne $declaration_name) {
+ print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
+ return;
+ }
+
my %_members;
$members =~ s/\s+$//;
@@ -1446,6 +1459,11 @@ sub dump_typedef($$) {
$declaration_name = $2;
my $args = $3;
+ if ($identifier ne $declaration_name) {
+ print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+ return;
+ }
+
create_parameterlist($args, ',', $file, $declaration_name);
output_declaration($declaration_name,
@@ -1472,6 +1490,11 @@ sub dump_typedef($$) {
if ($x =~ /typedef.*\s+(\w+)\s*;/) {
$declaration_name = $1;
+ if ($identifier ne $declaration_name) {
+ print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+ return;
+ }
+
output_declaration($declaration_name,
'typedef',
{'typedef' => $declaration_name,
@@ -1791,6 +1814,11 @@ sub dump_function($$) {
return;
}
+ if ($identifier ne $declaration_name) {
+ print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
+ return;
+ }
+
my $prms = join " ", @parameterlist;
check_sections($file, $declaration_name, "function", $sectcheck, $prms);
@@ -1873,6 +1901,7 @@ sub tracepoint_munge($) {
"$prototype\n";
} else {
$prototype = "static inline void trace_$tracepointname($tracepointargs)";
+ $identifier = "trace_$identifier";
}
}
@@ -2036,7 +2065,6 @@ sub process_normal() {
#
sub process_name($$) {
my $file = shift;
- my $identifier;
my $descr;
if (/$doc_block/o) {
@@ -2049,12 +2077,19 @@ sub process_name($$) {
} else {
$section = $1;
}
- }
- elsif (/$doc_decl/o) {
+ } elsif (/$doc_decl/o) {
$identifier = $1;
- if (/\s*([\w\s]+?)(\(\))?\s*-/) {
+ if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
$identifier = $1;
}
+ if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
+ $decl_type = $1;
+ $identifier = $2;
+ } else {
+ $decl_type = 'function';
+ $identifier =~ s/^define\s+//;
+ }
+ $identifier =~ s/\s+$//;
$state = STATE_BODY;
# if there's no @param blocks need to set up default section
@@ -2062,7 +2097,7 @@ sub process_name($$) {
$contents = "";
$section = $section_default;
$new_start_line = $. + 1;
- if (/-(.*)/) {
+ if (/[-:](.*)/) {
# strip leading/trailing/multiple spaces
$descr= $1;
$descr =~ s/^\s*//;
@@ -2080,20 +2115,15 @@ sub process_name($$) {
++$warnings;
}
- if ($identifier =~ m/^struct\b/) {
- $decl_type = 'struct';
- } elsif ($identifier =~ m/^union\b/) {
- $decl_type = 'union';
- } elsif ($identifier =~ m/^enum\b/) {
- $decl_type = 'enum';
- } elsif ($identifier =~ m/^typedef\b/) {
- $decl_type = 'typedef';
- } else {
- $decl_type = 'function';
+ if ($identifier eq "") {
+ print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
+ print STDERR $_;
+ ++$warnings;
+ $state = STATE_NORMAL;
}
if ($verbose) {
- print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
+ print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
}
} else {
print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
--
2.26.2
Kernel-doc markups should use this format:
identifier - description
While here, fix a kernel-doc tag that was using, instead,
a normal comment block.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
kernel/resource.c | 24 ++++++++++++++----------
1 file changed, 14 insertions(+), 10 deletions(-)
diff --git a/kernel/resource.c b/kernel/resource.c
index 3ae2f56cc79d..9738920abdca 100644
--- a/kernel/resource.c
+++ b/kernel/resource.c
@@ -320,9 +320,8 @@ int release_resource(struct resource *old)
EXPORT_SYMBOL(release_resource);
/**
- * Finds the lowest iomem resource that covers part of [@start..@end]. The
- * caller must specify @start, @end, @flags, and @desc (which may be
- * IORES_DESC_NONE).
+ * find_next_iomem_res - Finds the lowest iomem resource that covers part of
+ * [@start..@end].
*
* If a resource is found, returns 0 and @*res is overwritten with the part
* of the resource that's within [@start..@end]; if none is found, returns
@@ -337,6 +336,9 @@ EXPORT_SYMBOL(release_resource);
* @desc: descriptor the resource must have
* @first_lvl: walk only the first level children, if set
* @res: return ptr, if resource found
+ *
+ * The caller must specify @start, @end, @flags, and @desc
+ * (which may be IORES_DESC_NONE).
*/
static int find_next_iomem_res(resource_size_t start, resource_size_t end,
unsigned long flags, unsigned long desc,
@@ -416,11 +418,9 @@ static int __walk_iomem_res_desc(resource_size_t start, resource_size_t end,
}
/**
- * Walks through iomem resources and calls func() with matching resource
- * ranges. This walks through whole tree and not just first level children.
- * All the memory ranges which overlap start,end and also match flags and
- * desc are valid candidates.
- *
+ * walk_iomem_res_desc - Walks through iomem resources and calls func()
+ * with matching resource ranges.
+ * *
* @desc: I/O resource descriptor. Use IORES_DESC_NONE to skip @desc check.
* @flags: I/O resource flags
* @start: start addr
@@ -428,6 +428,10 @@ static int __walk_iomem_res_desc(resource_size_t start, resource_size_t end,
* @arg: function argument for the callback @func
* @func: callback function that is called for each qualifying resource area
*
+ * This walks through whole tree and not just first level children.
+ * All the memory ranges which overlap start,end and also match flags and
+ * desc are valid candidates.
+ *
* NOTE: For a new descriptor search, define a new IORES_DESC in
* <linux/ioport.h> and set it in 'desc' of a target resource entry.
*/
@@ -1372,9 +1376,9 @@ static bool system_ram_resources_mergeable(struct resource *r1,
!r1->child && !r2->child;
}
-/*
+/**
* merge_system_ram_resource - mark the System RAM resource mergeable and try to
- * merge it with adjacent, mergeable resources
+ * merge it with adjacent, mergeable resources
* @res: resource descriptor
*
* This interface is intended for memory hotplug, whereby lots of contiguous
--
2.26.2
clk_get_duty_cycle -> clk_get_scaled_duty_cycle
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/clk.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/linux/clk.h b/include/linux/clk.h
index 7fd6a1febcf4..5f8d5f4931c0 100644
--- a/include/linux/clk.h
+++ b/include/linux/clk.h
@@ -150,7 +150,7 @@ int clk_get_phase(struct clk *clk);
int clk_set_duty_cycle(struct clk *clk, unsigned int num, unsigned int den);
/**
- * clk_get_duty_cycle - return the duty cycle ratio of a clock signal
+ * clk_get_scaled_duty_cycle - return the duty cycle ratio of a clock signal
* @clk: clock signal source
* @scale: scaling factor to be applied to represent the ratio as an integer
*
--
2.26.2
The documented typedef just after the kernel-doc markup
is named "refcount_struct".
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/refcount.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/linux/refcount.h b/include/linux/refcount.h
index 497990c69b0b..8f431b0e69e4 100644
--- a/include/linux/refcount.h
+++ b/include/linux/refcount.h
@@ -101,7 +101,7 @@
struct mutex;
/**
- * struct refcount_t - variant of atomic_t specialized for reference counts
+ * struct refcount_struct - variant of atomic_t specialized for reference counts
* @refs: atomic_t counter field
*
* The counter saturates at REFCOUNT_SATURATED and will not move once
--
2.26.2
hlist_add_behing -> hlist_add_behind
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/list.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/linux/list.h b/include/linux/list.h
index a18c87b63376..f72a7a778722 100644
--- a/include/linux/list.h
+++ b/include/linux/list.h
@@ -901,7 +901,7 @@ static inline void hlist_add_before(struct hlist_node *n,
}
/**
- * hlist_add_behing - add a new entry after the one specified
+ * hlist_add_behind - add a new entry after the one specified
* @n: new entry to be added
* @prev: hlist node to add it after, which must be non-NULL
*/
--
2.26.2
A kernel-doc markup can't be mixed with a random comment,
as it causes parsing problems.
While here, change an invalid kernel-doc markup into
a common comment.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/gpu/drm/amd/amdgpu/amdgpu_device.c | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
index f8785bdec79c..1d4b54950528 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
@@ -239,9 +239,11 @@ bool amdgpu_device_supports_baco(struct drm_device *dev)
return amdgpu_asic_supports_baco(adev);
}
+/*
+ * VRAM access helper functions
+ */
+
/**
- * VRAM access helper functions.
- *
* amdgpu_device_vram_access - read/write a buffer in vram
*
* @adev: amdgpu_device pointer
@@ -4497,7 +4499,7 @@ int amdgpu_device_gpu_recover(struct amdgpu_device *adev,
bool need_emergency_restart = false;
bool audio_suspended = false;
- /**
+ /*
* Special case: RAS triggered and full reset isn't supported
*/
need_emergency_restart = amdgpu_ras_need_emergency_restart(adev);
--
2.26.2
Am 23.10.20 um 18:32 schrieb Mauro Carvalho Chehab:
> Some functions have different names between their prototypes
> and the kernel-doc markup.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Acked-by: Christian König <[email protected]>
> ---
> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c | 2 +-
> drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 2 +-
> include/uapi/drm/amdgpu_drm.h | 2 +-
> 3 files changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> index df110afa97bf..a5f73a267fe5 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> @@ -2166,7 +2166,7 @@ struct amdgpu_bo_va *amdgpu_vm_bo_add(struct amdgpu_device *adev,
>
>
> /**
> - * amdgpu_vm_bo_insert_mapping - insert a new mapping
> + * amdgpu_vm_bo_insert_map - insert a new mapping
> *
> * @adev: amdgpu_device pointer
> * @bo_va: bo_va to store the address
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> index 0c6b7c5ecfec..795bad307497 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> @@ -528,7 +528,7 @@ int amdgpu_vram_mgr_alloc_sgt(struct amdgpu_device *adev,
> }
>
> /**
> - * amdgpu_vram_mgr_alloc_sgt - allocate and fill a sg table
> + * amdgpu_vram_mgr_free_sgt - allocate and fill a sg table
> *
> * @adev: amdgpu device pointer
> * @sgt: sg table to free
> diff --git a/include/uapi/drm/amdgpu_drm.h b/include/uapi/drm/amdgpu_drm.h
> index c5ff2b275fcd..791a1d597d2a 100644
> --- a/include/uapi/drm/amdgpu_drm.h
> +++ b/include/uapi/drm/amdgpu_drm.h
> @@ -667,7 +667,7 @@ struct drm_amdgpu_cs_chunk_data {
> };
> };
>
> -/**
> +/*
> * Query h/w info: Flag that this is integrated (a.h.a. fusion) GPU
> *
> */
On Fri, Oct 23, 2020 at 06:33:42PM +0200, Mauro Carvalho Chehab wrote:
> The kernel-doc markups on this file are weird: they don't
> follow what's specified at:
>
> Documentation/doc-guide/kernel-doc.rst
>
> In particular, markups should use this format:
> identifier - description
>
> and not this:
> identifier(args)
>
> The way the definitions are inside this file cause the
> parser to completely miss the identifier name of each
> function.
>
> This prevents improving the script to do some needed validation
> tests.
>
> Address this part. Yet, furter changes are needed in order
> for it to fully follow the specs.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> tools/testing/selftests/kselftest_harness.h | 66 ++++++++++-----------
> 1 file changed, 33 insertions(+), 33 deletions(-)
>
> diff --git a/tools/testing/selftests/kselftest_harness.h b/tools/testing/selftests/kselftest_harness.h
> index f19804df244c..665d04f3b802 100644
> --- a/tools/testing/selftests/kselftest_harness.h
> +++ b/tools/testing/selftests/kselftest_harness.h
> @@ -79,7 +79,7 @@
> #endif
>
> /**
> - * TH_LOG(fmt, ...)
> + * TH_LOG()
> *
> * @fmt: format string
> * @...: optional arguments
Hmmm. Yeah, this does need fixing, but I don't want to lose the
"examples". Some have stuff like this before the description:
* .. code-block:: c
*
* TH_LOG(format, ...)
which retains it, but many don't. Can you add the code-block:: c
sections where they're missing so this doesn't lose the syntax hints
when just looking at the header file alone.
-Kees
> @@ -113,7 +113,7 @@
> __FILE__, __LINE__, _metadata->name, ##__VA_ARGS__)
>
> /**
> - * SKIP(statement, fmt, ...)
> + * SKIP()
> *
> * @statement: statement to run after reporting SKIP
> * @fmt: format string
> @@ -136,7 +136,7 @@
> } while (0)
>
> /**
> - * TEST(test_name) - Defines the test function and creates the registration
> + * TEST() - Defines the test function and creates the registration
> * stub
> *
> * @test_name: test name
> @@ -155,7 +155,7 @@
> #define TEST(test_name) __TEST_IMPL(test_name, -1)
>
> /**
> - * TEST_SIGNAL(test_name, signal)
> + * TEST_SIGNAL()
> *
> * @test_name: test name
> * @signal: signal number
> @@ -195,7 +195,7 @@
> struct __test_metadata __attribute__((unused)) *_metadata)
>
> /**
> - * FIXTURE_DATA(datatype_name) - Wraps the struct name so we have one less
> + * FIXTURE_DATA() - Wraps the struct name so we have one less
> * argument to pass around
> *
> * @datatype_name: datatype name
> @@ -212,7 +212,7 @@
> #define FIXTURE_DATA(datatype_name) struct _test_data_##datatype_name
>
> /**
> - * FIXTURE(fixture_name) - Called once per fixture to setup the data and
> + * FIXTURE() - Called once per fixture to setup the data and
> * register
> *
> * @fixture_name: fixture name
> @@ -239,7 +239,7 @@
> FIXTURE_DATA(fixture_name)
>
> /**
> - * FIXTURE_SETUP(fixture_name) - Prepares the setup function for the fixture.
> + * FIXTURE_SETUP() - Prepares the setup function for the fixture.
> * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly.
> *
> * @fixture_name: fixture name
> @@ -265,7 +265,7 @@
> __attribute__((unused)) *variant)
>
> /**
> - * FIXTURE_TEARDOWN(fixture_name)
> + * FIXTURE_TEARDOWN()
> * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly.
> *
> * @fixture_name: fixture name
> @@ -286,7 +286,7 @@
> FIXTURE_DATA(fixture_name) __attribute__((unused)) *self)
>
> /**
> - * FIXTURE_VARIANT(fixture_name) - Optionally called once per fixture
> + * FIXTURE_VARIANT() - Optionally called once per fixture
> * to declare fixture variant
> *
> * @fixture_name: fixture name
> @@ -305,7 +305,7 @@
> #define FIXTURE_VARIANT(fixture_name) struct _fixture_variant_##fixture_name
>
> /**
> - * FIXTURE_VARIANT_ADD(fixture_name, variant_name) - Called once per fixture
> + * FIXTURE_VARIANT_ADD() - Called once per fixture
> * variant to setup and register the data
> *
> * @fixture_name: fixture name
> @@ -339,7 +339,7 @@
> _##fixture_name##_##variant_name##_variant =
>
> /**
> - * TEST_F(fixture_name, test_name) - Emits test registration and helpers for
> + * TEST_F() - Emits test registration and helpers for
> * fixture-based test cases
> *
> * @fixture_name: fixture name
> @@ -432,7 +432,7 @@
> */
>
> /**
> - * ASSERT_EQ(expected, seen)
> + * ASSERT_EQ()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -443,7 +443,7 @@
> __EXPECT(expected, #expected, seen, #seen, ==, 1)
>
> /**
> - * ASSERT_NE(expected, seen)
> + * ASSERT_NE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -454,7 +454,7 @@
> __EXPECT(expected, #expected, seen, #seen, !=, 1)
>
> /**
> - * ASSERT_LT(expected, seen)
> + * ASSERT_LT()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -465,7 +465,7 @@
> __EXPECT(expected, #expected, seen, #seen, <, 1)
>
> /**
> - * ASSERT_LE(expected, seen)
> + * ASSERT_LE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -476,7 +476,7 @@
> __EXPECT(expected, #expected, seen, #seen, <=, 1)
>
> /**
> - * ASSERT_GT(expected, seen)
> + * ASSERT_GT()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -487,7 +487,7 @@
> __EXPECT(expected, #expected, seen, #seen, >, 1)
>
> /**
> - * ASSERT_GE(expected, seen)
> + * ASSERT_GE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -498,7 +498,7 @@
> __EXPECT(expected, #expected, seen, #seen, >=, 1)
>
> /**
> - * ASSERT_NULL(seen)
> + * ASSERT_NULL()
> *
> * @seen: measured value
> *
> @@ -508,7 +508,7 @@
> __EXPECT(NULL, "NULL", seen, #seen, ==, 1)
>
> /**
> - * ASSERT_TRUE(seen)
> + * ASSERT_TRUE()
> *
> * @seen: measured value
> *
> @@ -518,7 +518,7 @@
> __EXPECT(0, "0", seen, #seen, !=, 1)
>
> /**
> - * ASSERT_FALSE(seen)
> + * ASSERT_FALSE()
> *
> * @seen: measured value
> *
> @@ -528,7 +528,7 @@
> __EXPECT(0, "0", seen, #seen, ==, 1)
>
> /**
> - * ASSERT_STREQ(expected, seen)
> + * ASSERT_STREQ()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -539,7 +539,7 @@
> __EXPECT_STR(expected, seen, ==, 1)
>
> /**
> - * ASSERT_STRNE(expected, seen)
> + * ASSERT_STRNE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -550,7 +550,7 @@
> __EXPECT_STR(expected, seen, !=, 1)
>
> /**
> - * EXPECT_EQ(expected, seen)
> + * EXPECT_EQ()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -561,7 +561,7 @@
> __EXPECT(expected, #expected, seen, #seen, ==, 0)
>
> /**
> - * EXPECT_NE(expected, seen)
> + * EXPECT_NE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -572,7 +572,7 @@
> __EXPECT(expected, #expected, seen, #seen, !=, 0)
>
> /**
> - * EXPECT_LT(expected, seen)
> + * EXPECT_LT()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -583,7 +583,7 @@
> __EXPECT(expected, #expected, seen, #seen, <, 0)
>
> /**
> - * EXPECT_LE(expected, seen)
> + * EXPECT_LE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -594,7 +594,7 @@
> __EXPECT(expected, #expected, seen, #seen, <=, 0)
>
> /**
> - * EXPECT_GT(expected, seen)
> + * EXPECT_GT()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -605,7 +605,7 @@
> __EXPECT(expected, #expected, seen, #seen, >, 0)
>
> /**
> - * EXPECT_GE(expected, seen)
> + * EXPECT_GE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -616,7 +616,7 @@
> __EXPECT(expected, #expected, seen, #seen, >=, 0)
>
> /**
> - * EXPECT_NULL(seen)
> + * EXPECT_NULL()
> *
> * @seen: measured value
> *
> @@ -626,7 +626,7 @@
> __EXPECT(NULL, "NULL", seen, #seen, ==, 0)
>
> /**
> - * EXPECT_TRUE(seen)
> + * EXPECT_TRUE()
> *
> * @seen: measured value
> *
> @@ -636,7 +636,7 @@
> __EXPECT(0, "0", seen, #seen, !=, 0)
>
> /**
> - * EXPECT_FALSE(seen)
> + * EXPECT_FALSE()
> *
> * @seen: measured value
> *
> @@ -646,7 +646,7 @@
> __EXPECT(0, "0", seen, #seen, ==, 0)
>
> /**
> - * EXPECT_STREQ(expected, seen)
> + * EXPECT_STREQ()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -657,7 +657,7 @@
> __EXPECT_STR(expected, seen, ==, 0)
>
> /**
> - * EXPECT_STRNE(expected, seen)
> + * EXPECT_STRNE()
> *
> * @expected: expected value
> * @seen: measured value
> --
> 2.26.2
>
--
Kees Cook
On Fri, Oct 23, 2020 at 06:33:36PM +0200, Mauro Carvalho Chehab wrote:
> The documented typedef just after the kernel-doc markup
> is named "refcount_struct".
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> include/linux/refcount.h | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/include/linux/refcount.h b/include/linux/refcount.h
> index 497990c69b0b..8f431b0e69e4 100644
> --- a/include/linux/refcount.h
> +++ b/include/linux/refcount.h
> @@ -101,7 +101,7 @@
> struct mutex;
>
> /**
> - * struct refcount_t - variant of atomic_t specialized for reference counts
> + * struct refcount_struct - variant of atomic_t specialized for reference counts
Hm, this is a weird one. Yes, it's actually "struct refcount_struct",
but the usage should be refcount_t (through the typedef). I'm not sure
what the right way to document this is.
-Kees
> * @refs: atomic_t counter field
> *
> * The counter saturates at REFCOUNT_SATURATED and will not move once
> --
> 2.26.2
>
--
Kees Cook
On Fri, Oct 23, 2020 at 06:33:24PM +0200, Mauro Carvalho Chehab wrote:
> The documented struct is psz_head and not psz_buffer.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Kees Cook <[email protected]>
--
Kees Cook
On Fri, 23 Oct 2020 18:32:48 +0200
Mauro Carvalho Chehab <[email protected]> wrote:
> The include/linux/genalloc.h file defined this typedef:
>
> typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
>
> Because it has a type composite of two words (unsigned long),
> the parser gets the typedef name wrong:
>
> .. c:macro:: long
>
> **Typedef**: Allocation callback function type definition
>
> Fix the regex in order to accept composite types when
> defining a typedef for a function pointer.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> scripts/kernel-doc | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 99cd8418ff8a..311d213ee74d 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1438,7 +1438,7 @@ sub dump_typedef($$) {
> $x =~ s@/\*.*?\*/@@gos; # strip comments.
>
> # Parse function prototypes
> - if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> + if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
I sure wish we could find a way to make all these regexes more
understandable and maintainable. Reviewing a change like this is ... fun.
Anyway, it seems to work, but it does now include trailing whitespace in
the type portion. So, for example, from include/linux/xarray.h:
typedef void (*xa_update_node_t)(struct xa_node *node);
The type is parsed as "void " where it was "void" before. The only ill
effect I can see is that some non-breaking spaces get inserted into the
HTML output, but perhaps it's worth stripping off that trailing space
anyway?
Thanks,
jon
On Fri, Oct 23, 2020 at 06:33:41PM +0200, Mauro Carvalho Chehab wrote:
> /**
> - * This helper is similar with the above one, except that it accounts for pages
> - * that are likely on a pagevec and count them in @nr_pagevec, which will used by
> + * invalidate_mapping_pagevec - This helper is similar with
> + * invalidate_mapping_pages(), except that it accounts for pages tat are
You introduced a typo here, s/tat/that/
> + * likely on a pagevec and count them in @nr_pagevec, which will used by
... and while you're touching this paragraph, s/will used/will be used/
and s/similar with/similar to/
> * the caller.
> + *
> + * @mapping: the address_space which holds the pages to invalidate
> + * @start: the offset 'from' which to invalidate
> + * @end: the offset 'to' which to invalidate (inclusive)
> + *
> */
> void invalidate_mapping_pagevec(struct address_space *mapping,
> pgoff_t start, pgoff_t end, unsigned long *nr_pagevec)
> --
> 2.26.2
>
>
On Fri, 2020-10-23 at 11:22 -0600, Jonathan Corbet wrote:
> On Fri, 23 Oct 2020 18:32:48 +0200
> Mauro Carvalho Chehab <[email protected]> wrote:
>
> > The include/linux/genalloc.h file defined this typedef:
> >
> > typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
[]
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
[]
> > ?????# Parse function prototypes
> > - if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > + if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
>
> I sure wish we could find a way to make all these regexes more
> understandable and maintainable. Reviewing a change like this is ... fun.
Perhaps using some of the checkpatch regex definitions like:
$Type
$Ident
$balanced_parens
would help improve readability.
And the regex above doesn't quite work for spacing after typedef.
The regex should allow space between the open parenthesis and the *
typedef <Type> ( * <Ident> ) (args...);
And this regex does not find typedefs that use another typedef as <Ident> like:
arch/s390/include/asm/debug.h:typedef int (debug_header_proc_t) (debug_info_t *id,
On 10/23/20 10:32 AM, Mauro Carvalho Chehab wrote:
> Fix a typo:
> blk_mq_run_hw_queue -> blk_mq_run_hw_queues
Applied, thanks.
--
Jens Axboe
On 10/23/20 10:32 AM, Mauro Carvalho Chehab wrote:
> Some functions have different names between their prototypes
> and the kernel-doc markup.
Applied, thanks.
--
Jens Axboe
On Fri, 23 Oct 2020 18:32:47 +0200 Mauro Carvalho Chehab wrote:
> @maintainers: feel free to pick the patches and
> apply them directly on your trees, as all patches on
> this series are independent from the other ones.
Sorry Mauro, can I hassle you for resending 18-20 as a separate series
or just loose patches to netdev?
We got a bunch of checks run on all submissions and when folks CC only
a slice of a series to netdev the CI bot thinks the series is incomplete
and doesn't pick it up :(
On Fri, Oct 23, 2020 at 11:12:40AM -0700, Jakub Kicinski wrote:
> On Fri, 23 Oct 2020 18:32:47 +0200 Mauro Carvalho Chehab wrote:
> > @maintainers: feel free to pick the patches and
> > apply them directly on your trees, as all patches on
> > this series are independent from the other ones.
> Sorry Mauro, can I hassle you for resending 18-20 as a separate series
> or just loose patches to netdev?
> We got a bunch of checks run on all submissions and when folks CC only
> a slice of a series to netdev the CI bot thinks the series is incomplete
> and doesn't pick it up :(
FWIW something similar with patches for different trees sent separately
would also be helpful for my automation.
On Fri, Oct 23, 2020 at 06:33:35PM +0200, Mauro Carvalho Chehab wrote:
> Kernel-doc markups should use this format:
> identifier - description
Acked-by: Mark Brown <[email protected]>
Applied. Thanks!
Alex
On Fri, Oct 23, 2020 at 12:33 PM Mauro Carvalho Chehab
<[email protected]> wrote:
>
> dm_comressor_info -> dm_compressor_info
>
> The kernel-doc markup is right, but the struct itself
> and their references contain a typo.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 2 +-
> drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h | 6 +++---
> 2 files changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
> index bb1bc7f5d149..48ec0535d92f 100644
> --- a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
> +++ b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
> @@ -583,7 +583,7 @@ static void amdgpu_dm_fbc_init(struct drm_connector *connector)
> {
> struct drm_device *dev = connector->dev;
> struct amdgpu_device *adev = drm_to_adev(dev);
> - struct dm_comressor_info *compressor = &adev->dm.compressor;
> + struct dm_compressor_info *compressor = &adev->dm.compressor;
> struct amdgpu_dm_connector *aconn = to_amdgpu_dm_connector(connector);
> struct drm_display_mode *mode;
> unsigned long max_size = 0;
> 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 34f6369bf51f..a8a0e8cb1a11 100644
> --- a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
> +++ b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
> @@ -86,7 +86,7 @@ struct irq_list_head {
> * @bo_ptr: Pointer to the buffer object
> * @gpu_addr: MMIO gpu addr
> */
> -struct dm_comressor_info {
> +struct dm_compressor_info {
> void *cpu_addr;
> struct amdgpu_bo *bo_ptr;
> uint64_t gpu_addr;
> @@ -148,7 +148,7 @@ struct amdgpu_dm_backlight_caps {
> * @soc_bounding_box: SOC bounding box values provided by gpu_info FW
> * @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
> + * @compressor: Frame buffer compression buffer. See &struct dm_compressor_info
> * @force_timing_sync: set via debugfs. When set, indicates that all connected
> * displays will be forced to synchronize.
> */
> @@ -324,7 +324,7 @@ struct amdgpu_display_manager {
> struct drm_atomic_state *cached_state;
> struct dc_state *cached_dc_state;
>
> - struct dm_comressor_info compressor;
> + struct dm_compressor_info compressor;
>
> const struct firmware *fw_dmcu;
> uint32_t dmcu_fw_version;
> --
> 2.26.2
>
> _______________________________________________
> amd-gfx mailing list
> [email protected]
> https://lists.freedesktop.org/mailman/listinfo/amd-gfx
A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/iio/trigger.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/linux/iio/trigger.h b/include/linux/iio/trigger.h
index cad8325903f9..f930c4ccf378 100644
--- a/include/linux/iio/trigger.h
+++ b/include/linux/iio/trigger.h
@@ -97,7 +97,7 @@ static inline struct iio_trigger *iio_trigger_get(struct iio_trigger *trig)
}
/**
- * iio_device_set_drvdata() - Set trigger driver data
+ * iio_trigger_set_drvdata() - Set trigger driver data
* @trig: IIO trigger structure
* @data: Driver specific data
*
--
2.26.2
The hrtimer_get_remaining() markup is documenting, instead,
__hrtimer_get_remaining(), as it is placed at the C file.
In order to properly document it, a kernel-doc markup is
needed together with the function prototype. So, add a
new one, while preserving the existing one, just fixing
the function name.
The hrtimer_is_queued prototype has a typo: it is using
'=' character instead of '-' to split:
identifier - description
as required by kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/hrtimer.h | 6 +++++-
kernel/time/hrtimer.c | 2 +-
2 files changed, 6 insertions(+), 2 deletions(-)
diff --git a/include/linux/hrtimer.h b/include/linux/hrtimer.h
index 107cedd7019a..bb5e7b0a4274 100644
--- a/include/linux/hrtimer.h
+++ b/include/linux/hrtimer.h
@@ -447,6 +447,10 @@ static inline void hrtimer_restart(struct hrtimer *timer)
/* Query timers: */
extern ktime_t __hrtimer_get_remaining(const struct hrtimer *timer, bool adjust);
+/**
+ * hrtimer_get_remaining - get remaining time for the timer
+ * @timer: the timer to read
+ */
static inline ktime_t hrtimer_get_remaining(const struct hrtimer *timer)
{
return __hrtimer_get_remaining(timer, false);
@@ -458,7 +462,7 @@ extern u64 hrtimer_next_event_without(const struct hrtimer *exclude);
extern bool hrtimer_active(const struct hrtimer *timer);
/**
- * hrtimer_is_queued = check, whether the timer is on one of the queues
+ * hrtimer_is_queued - check, whether the timer is on one of the queues
* @timer: Timer to check
*
* Returns: True if the timer is queued, false otherwise
diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
index 3624b9b5835d..61c39ff68439 100644
--- a/kernel/time/hrtimer.c
+++ b/kernel/time/hrtimer.c
@@ -1289,7 +1289,7 @@ int hrtimer_cancel(struct hrtimer *timer)
EXPORT_SYMBOL_GPL(hrtimer_cancel);
/**
- * hrtimer_get_remaining - get remaining time for the timer
+ * __hrtimer_get_remaining - get remaining time for the timer
* @timer: the timer to read
* @adjust: adjust relative timers when CONFIG_TIME_LOW_RES=y
*/
--
2.26.2
Some identifiers have different names between their prototypes
and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/video/fbdev/core/fbcmap.c | 2 +-
drivers/video/hdmi.c | 3 ++-
2 files changed, 3 insertions(+), 2 deletions(-)
diff --git a/drivers/video/fbdev/core/fbcmap.c b/drivers/video/fbdev/core/fbcmap.c
index e5ae33c1a8e8..757d5c3f620b 100644
--- a/drivers/video/fbdev/core/fbcmap.c
+++ b/drivers/video/fbdev/core/fbcmap.c
@@ -76,7 +76,7 @@ static const struct fb_cmap default_16_colors = {
/**
- * fb_alloc_cmap - allocate a colormap
+ * fb_alloc_cmap_gfp - allocate a colormap
* @cmap: frame buffer colormap structure
* @len: length of @cmap
* @transp: boolean, 1 if there is transparency, 0 otherwise
diff --git a/drivers/video/hdmi.c b/drivers/video/hdmi.c
index b7a1d6fae90d..e44b7cec95fd 100644
--- a/drivers/video/hdmi.c
+++ b/drivers/video/hdmi.c
@@ -1688,7 +1688,8 @@ static int hdmi_audio_infoframe_unpack(struct hdmi_audio_infoframe *frame,
}
/**
- * hdmi_vendor_infoframe_unpack() - unpack binary buffer to a HDMI vendor infoframe
+ * hdmi_vendor_any_infoframe_unpack() - unpack binary buffer to a HDMI
+ * vendor infoframe
* @frame: HDMI Vendor infoframe
* @buffer: source buffer
* @size: size of buffer
--
2.26.2
Some identifiers have different names between their prototypes
and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/memblock.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/include/linux/memblock.h b/include/linux/memblock.h
index ef131255cedc..95fe3cb71c54 100644
--- a/include/linux/memblock.h
+++ b/include/linux/memblock.h
@@ -272,7 +272,7 @@ void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone,
unsigned long *out_spfn,
unsigned long *out_epfn);
/**
- * for_each_free_mem_range_in_zone - iterate through zone specific free
+ * for_each_free_mem_pfn_range_in_zone - iterate through zone specific free
* memblock areas
* @i: u64 used as loop variable
* @zone: zone in which all of the memory blocks reside
@@ -292,7 +292,7 @@ void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone,
__next_mem_pfn_range_in_zone(&i, zone, p_start, p_end))
/**
- * for_each_free_mem_range_in_zone_from - iterate through zone specific
+ * for_each_free_mem_pfn_range_in_zone_from - iterate through zone specific
* free memblock areas from a given point
* @i: u64 used as loop variable
* @zone: zone in which all of the memory blocks reside
--
2.26.2
There is a common comment marked, instead, with kernel-doc
notation.
Also, some identifiers have different names between their
prototypes and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/usb/dwc3/core.c | 2 +-
drivers/usb/dwc3/core.h | 2 +-
drivers/usb/gadget/composite.c | 2 +-
drivers/usb/typec/mux.c | 2 +-
include/linux/usb/composite.h | 2 +-
5 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/drivers/usb/dwc3/core.c b/drivers/usb/dwc3/core.c
index bdf0925da6b6..841daec70b6e 100644
--- a/drivers/usb/dwc3/core.c
+++ b/drivers/usb/dwc3/core.c
@@ -1,5 +1,5 @@
// SPDX-License-Identifier: GPL-2.0
-/**
+/*
* core.c - DesignWare USB3 DRD Controller Core file
*
* Copyright (C) 2010-2011 Texas Instruments Incorporated - https://www.ti.com
diff --git a/drivers/usb/dwc3/core.h b/drivers/usb/dwc3/core.h
index 74323b10a64a..2f95f08ca511 100644
--- a/drivers/usb/dwc3/core.h
+++ b/drivers/usb/dwc3/core.h
@@ -1277,7 +1277,7 @@ struct dwc3_event_type {
#define DWC3_DEPEVT_EPCMDCMPLT 0x07
/**
- * struct dwc3_event_depvt - Device Endpoint Events
+ * struct dwc3_event_depevt - Device Endpoint Events
* @one_bit: indicates this is an endpoint event (not used)
* @endpoint_number: number of the endpoint
* @endpoint_event: The event we have:
diff --git a/drivers/usb/gadget/composite.c b/drivers/usb/gadget/composite.c
index 05b176c82cc5..c6d455f2bb92 100644
--- a/drivers/usb/gadget/composite.c
+++ b/drivers/usb/gadget/composite.c
@@ -1245,7 +1245,7 @@ int usb_string_id(struct usb_composite_dev *cdev)
EXPORT_SYMBOL_GPL(usb_string_id);
/**
- * usb_string_ids() - allocate unused string IDs in batch
+ * usb_string_ids_tab() - allocate unused string IDs in batch
* @cdev: the device whose string descriptor IDs are being allocated
* @str: an array of usb_string objects to assign numbers to
* Context: single threaded during gadget setup
diff --git a/drivers/usb/typec/mux.c b/drivers/usb/typec/mux.c
index b069a5122aaa..cf720e944aaa 100644
--- a/drivers/usb/typec/mux.c
+++ b/drivers/usb/typec/mux.c
@@ -71,7 +71,7 @@ struct typec_switch *fwnode_typec_switch_get(struct fwnode_handle *fwnode)
EXPORT_SYMBOL_GPL(fwnode_typec_switch_get);
/**
- * typec_put_switch - Release USB Type-C orientation switch
+ * typec_switch_put - Release USB Type-C orientation switch
* @sw: USB Type-C orientation switch
*
* Decrement reference count for @sw.
diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 2040696d75b6..a2d229ab63ba 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -437,7 +437,7 @@ static inline struct usb_composite_driver *to_cdriver(
#define OS_STRING_IDX 0xEE
/**
- * struct usb_composite_device - represents one composite usb gadget
+ * struct usb_composite_dev - represents one composite usb gadget
* @gadget: read-only, abstracts the gadget's usb peripheral controller
* @req: used for control responses; buffer is pre-allocated
* @os_desc_req: used for OS descriptors responses; buffer is pre-allocated
--
2.26.2
There are some common comments marked, instead, with kernel-doc
notation, which won't work.
While here, rename an identifier, in order to match the
function prototype below kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/firmware/intel/stratix10-svc-client.h | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/include/linux/firmware/intel/stratix10-svc-client.h b/include/linux/firmware/intel/stratix10-svc-client.h
index a93d85932eb9..ebc295647581 100644
--- a/include/linux/firmware/intel/stratix10-svc-client.h
+++ b/include/linux/firmware/intel/stratix10-svc-client.h
@@ -6,7 +6,7 @@
#ifndef __STRATIX10_SVC_CLIENT_H
#define __STRATIX10_SVC_CLIENT_H
-/**
+/*
* Service layer driver supports client names
*
* fpga: for FPGA configuration
@@ -15,7 +15,7 @@
#define SVC_CLIENT_FPGA "fpga"
#define SVC_CLIENT_RSU "rsu"
-/**
+/*
* Status of the sent command, in bit number
*
* SVC_STATUS_OK:
@@ -50,7 +50,7 @@
#define SVC_STATUS_ERROR 5
#define SVC_STATUS_NO_SUPPORT 6
-/**
+/*
* Flag bit for COMMAND_RECONFIG
*
* COMMAND_RECONFIG_FLAG_PARTIAL:
@@ -58,7 +58,7 @@
*/
#define COMMAND_RECONFIG_FLAG_PARTIAL 1
-/**
+/*
* Timeout settings for service clients:
* timeout value used in Stratix10 FPGA manager driver.
* timeout value used in RSU driver
@@ -218,7 +218,7 @@ void stratix10_svc_free_memory(struct stratix10_svc_chan *chan, void *kaddr);
int stratix10_svc_send(struct stratix10_svc_chan *chan, void *msg);
/**
- * intel_svc_done() - complete service request
+ * stratix10_svc_done() - complete service request
* @chan: service channel assigned to the client
*
* This function is used by service client to inform service layer that
--
2.26.2
If you have the opportunity, I would prefer to capitalize the subject
to follow the drivers/pci convention, e.g.,
PCI: Fix ...
On Fri, Oct 23, 2020 at 06:33:10PM +0200, Mauro Carvalho Chehab wrote:
> Some identifiers have different names between their prototypes
> and the kernel-doc markup.
How did you find these? I build with "make W=1", which finds some
kernel-doc errors, but it didn't find these. If there's a scanner for
these, I could fix things like this before merging them.
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
I'd be happy to take this myself, but if you want to merge the whole
series together:
Acked-by: Bjorn Helgaas <[email protected]>
> ---
> drivers/pci/p2pdma.c | 10 +++++-----
> drivers/pci/pci-driver.c | 4 ++--
> drivers/pci/pci.c | 2 +-
> drivers/pci/probe.c | 4 ++--
> drivers/pci/slot.c | 5 +++--
> 5 files changed, 13 insertions(+), 12 deletions(-)
>
> diff --git a/drivers/pci/p2pdma.c b/drivers/pci/p2pdma.c
> index de1c331dbed4..bace04145c5f 100644
> --- a/drivers/pci/p2pdma.c
> +++ b/drivers/pci/p2pdma.c
> @@ -609,7 +609,7 @@ bool pci_has_p2pmem(struct pci_dev *pdev)
> EXPORT_SYMBOL_GPL(pci_has_p2pmem);
>
> /**
> - * pci_p2pmem_find - find a peer-to-peer DMA memory device compatible with
> + * pci_p2pmem_find_many - find a peer-to-peer DMA memory device compatible with
> * the specified list of clients and shortest distance (as determined
> * by pci_p2pmem_dma())
> * @clients: array of devices to check (NULL-terminated)
> @@ -674,7 +674,7 @@ struct pci_dev *pci_p2pmem_find_many(struct device **clients, int num_clients)
> EXPORT_SYMBOL_GPL(pci_p2pmem_find_many);
>
> /**
> - * pci_alloc_p2p_mem - allocate peer-to-peer DMA memory
> + * pci_alloc_p2pmem - allocate peer-to-peer DMA memory
> * @pdev: the device to allocate memory from
> * @size: number of bytes to allocate
> *
> @@ -727,7 +727,7 @@ void pci_free_p2pmem(struct pci_dev *pdev, void *addr, size_t size)
> EXPORT_SYMBOL_GPL(pci_free_p2pmem);
>
> /**
> - * pci_virt_to_bus - return the PCI bus address for a given virtual
> + * pci_p2pmem_virt_to_bus - return the PCI bus address for a given virtual
> * address obtained with pci_alloc_p2pmem()
> * @pdev: the device the memory was allocated from
> * @addr: address of the memory that was allocated
> @@ -859,7 +859,7 @@ static int __pci_p2pdma_map_sg(struct pci_p2pdma_pagemap *p2p_pgmap,
> }
>
> /**
> - * pci_p2pdma_map_sg - map a PCI peer-to-peer scatterlist for DMA
> + * pci_p2pdma_map_sg_attrs - map a PCI peer-to-peer scatterlist for DMA
> * @dev: device doing the DMA request
> * @sg: scatter list to map
> * @nents: elements in the scatterlist
> @@ -896,7 +896,7 @@ int pci_p2pdma_map_sg_attrs(struct device *dev, struct scatterlist *sg,
> EXPORT_SYMBOL_GPL(pci_p2pdma_map_sg_attrs);
>
> /**
> - * pci_p2pdma_unmap_sg - unmap a PCI peer-to-peer scatterlist that was
> + * pci_p2pdma_unmap_sg_attrs - unmap a PCI peer-to-peer scatterlist that was
> * mapped with pci_p2pdma_map_sg()
> * @dev: device doing the DMA request
> * @sg: scatter list to map
> diff --git a/drivers/pci/pci-driver.c b/drivers/pci/pci-driver.c
> index 8b587fc97f7b..591ab353844a 100644
> --- a/drivers/pci/pci-driver.c
> +++ b/drivers/pci/pci-driver.c
> @@ -90,7 +90,7 @@ static void pci_free_dynids(struct pci_driver *drv)
> }
>
> /**
> - * store_new_id - sysfs frontend to pci_add_dynid()
> + * new_id_store - sysfs frontend to pci_add_dynid()
> * @driver: target device driver
> * @buf: buffer for scanning device ID data
> * @count: input size
> @@ -158,7 +158,7 @@ static ssize_t new_id_store(struct device_driver *driver, const char *buf,
> static DRIVER_ATTR_WO(new_id);
>
> /**
> - * store_remove_id - remove a PCI device ID from this driver
> + * remove_id_store - remove a PCI device ID from this driver
> * @driver: target device driver
> * @buf: buffer for scanning device ID data
> * @count: input size
> diff --git a/drivers/pci/pci.c b/drivers/pci/pci.c
> index 6d4d5a2f923d..8b9bea8ba751 100644
> --- a/drivers/pci/pci.c
> +++ b/drivers/pci/pci.c
> @@ -3480,7 +3480,7 @@ bool pci_acs_enabled(struct pci_dev *pdev, u16 acs_flags)
> }
>
> /**
> - * pci_acs_path_enable - test ACS flags from start to end in a hierarchy
> + * pci_acs_path_enabled - test ACS flags from start to end in a hierarchy
> * @start: starting downstream device
> * @end: ending upstream device or NULL to search to the root bus
> * @acs_flags: required flags
> diff --git a/drivers/pci/probe.c b/drivers/pci/probe.c
> index 4289030b0fff..eb1ec037f9e7 100644
> --- a/drivers/pci/probe.c
> +++ b/drivers/pci/probe.c
> @@ -165,7 +165,7 @@ static inline unsigned long decode_bar(struct pci_dev *dev, u32 bar)
> #define PCI_COMMAND_DECODE_ENABLE (PCI_COMMAND_MEMORY | PCI_COMMAND_IO)
>
> /**
> - * pci_read_base - Read a PCI BAR
> + * __pci_read_base - Read a PCI BAR
> * @dev: the PCI device
> * @type: type of the BAR
> * @res: resource buffer to be filled in
> @@ -1612,7 +1612,7 @@ static bool pci_ext_cfg_is_aliased(struct pci_dev *dev)
> }
>
> /**
> - * pci_cfg_space_size - Get the configuration space size of the PCI device
> + * pci_cfg_space_size_ext - Get the configuration space size of the PCI device
> * @dev: PCI device
> *
> * Regular PCI devices have 256 bytes, but PCI-X 2 and PCI Express devices
> diff --git a/drivers/pci/slot.c b/drivers/pci/slot.c
> index 3861505741e6..bcc8b12ce5da 100644
> --- a/drivers/pci/slot.c
> +++ b/drivers/pci/slot.c
> @@ -323,7 +323,7 @@ EXPORT_SYMBOL_GPL(pci_destroy_slot);
> #if defined(CONFIG_HOTPLUG_PCI) || defined(CONFIG_HOTPLUG_PCI_MODULE)
> #include <linux/pci_hotplug.h>
> /**
> - * pci_hp_create_link - create symbolic link to the hotplug driver module.
> + * pci_hp_create_module_link - create symbolic link to the hotplug driver module.
> * @pci_slot: struct pci_slot
> *
> * Helper function for pci_hotplug_core.c to create symbolic link to
> @@ -349,7 +349,8 @@ void pci_hp_create_module_link(struct pci_slot *pci_slot)
> EXPORT_SYMBOL_GPL(pci_hp_create_module_link);
>
> /**
> - * pci_hp_remove_link - remove symbolic link to the hotplug driver module.
> + * pci_hp_remove_module_link - remove symbolic link to the hotplug driver
> + * module.
> * @pci_slot: struct pci_slot
> *
> * Helper function for pci_hotplug_core.c to remove symbolic link to
> --
> 2.26.2
>
On Fri, Oct 23, 2020 at 06:33:33PM +0200, Mauro Carvalho Chehab wrote:
> hlist_add_behing -> hlist_add_behind
Reviewed-by: Andy Shevchenko <[email protected]>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> include/linux/list.h | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/include/linux/list.h b/include/linux/list.h
> index a18c87b63376..f72a7a778722 100644
> --- a/include/linux/list.h
> +++ b/include/linux/list.h
> @@ -901,7 +901,7 @@ static inline void hlist_add_before(struct hlist_node *n,
> }
>
> /**
> - * hlist_add_behing - add a new entry after the one specified
> + * hlist_add_behind - add a new entry after the one specified
> * @n: new entry to be added
> * @prev: hlist node to add it after, which must be non-NULL
> */
> --
> 2.26.2
>
--
With Best Regards,
Andy Shevchenko
On Fri, 23 Oct 2020 21:39:07 +0200
Peter Zijlstra <[email protected]> wrote:
> > > /**
> > > - * struct refcount_t - variant of atomic_t specialized for reference counts
> > > + * struct refcount_struct - variant of atomic_t specialized for reference counts
> >
> > Hm, this is a weird one. Yes, it's actually "struct refcount_struct",
> > but the usage should be refcount_t (through the typedef). I'm not sure
> > what the right way to document this is.
>
> Yeah, this is wrong. If this is due to a kernel doc warning, the kernel
> doc machinery is wrong *again*.
...except that, since refcount_t is a typedef, "struct refcount_t" doesn't
actually exist. Whether it works properly after doing s/struct// remains
to be seen...
jon
On Fri, Oct 23, 2020 at 10:40:09AM -0700, Kees Cook wrote:
> On Fri, Oct 23, 2020 at 06:33:36PM +0200, Mauro Carvalho Chehab wrote:
> > The documented typedef just after the kernel-doc markup
> > is named "refcount_struct".
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> > include/linux/refcount.h | 2 +-
> > 1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/include/linux/refcount.h b/include/linux/refcount.h
> > index 497990c69b0b..8f431b0e69e4 100644
> > --- a/include/linux/refcount.h
> > +++ b/include/linux/refcount.h
> > @@ -101,7 +101,7 @@
> > struct mutex;
> >
> > /**
> > - * struct refcount_t - variant of atomic_t specialized for reference counts
> > + * struct refcount_struct - variant of atomic_t specialized for reference counts
>
> Hm, this is a weird one. Yes, it's actually "struct refcount_struct",
> but the usage should be refcount_t (through the typedef). I'm not sure
> what the right way to document this is.
Yeah, this is wrong. If this is due to a kernel doc warning, the kernel
doc machinery is wrong *again*.
Hi Mauro,
I love your patch! Perhaps something to improve:
[auto build test WARNING on next-20201023]
[cannot apply to linuxtv-media/master sound/for-next pci/next mkp-scsi/for-next scsi/for-next linus/master v5.9 v5.9-rc8 v5.9-rc7 v5.9]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch]
url: https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20201024-004025
base: 9695c4ff26459ff5bfe25c7d6179e4c9c00e1363
config: riscv-randconfig-r002-20201024 (attached as .config)
compiler: clang version 12.0.0 (https://github.com/llvm/llvm-project 147b9497e79a98a8614b2b5eb4ba653b44f6b6f0)
reproduce (this is a W=1 build):
wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
chmod +x ~/bin/make.cross
# install riscv cross compiling tool for clang build
# apt-get install binutils-riscv64-linux-gnu
# https://github.com/0day-ci/linux/commit/002bbfc5a97ce37daf3c570e0edd28fa0c7de5b8
git remote add linux-review https://github.com/0day-ci/linux
git fetch --no-tags linux-review Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20201024-004025
git checkout 002bbfc5a97ce37daf3c570e0edd28fa0c7de5b8
# save the attached .config to linux build tree
COMPILER_INSTALL_PATH=$HOME/0day COMPILER=clang make.cross ARCH=riscv
If you fix the issue, kindly add following tag as appropriate
Reported-by: kernel test robot <[email protected]>
All warnings (new ones prefixed by >>):
>> drivers/clk/analogbits/wrpll-cln28hpc.c:223: warning: expecting prototype for wrpll_configure(). Prototype was for wrpll_configure_for_rate() instead
vim +223 drivers/clk/analogbits/wrpll-cln28hpc.c
7b9487a9a5c41ce Paul Walmsley 2019-04-30 199
7b9487a9a5c41ce Paul Walmsley 2019-04-30 200 /**
7b9487a9a5c41ce Paul Walmsley 2019-04-30 201 * wrpll_configure() - compute PLL configuration for a target rate
7b9487a9a5c41ce Paul Walmsley 2019-04-30 202 * @c: ptr to a struct wrpll_cfg record to write into
7b9487a9a5c41ce Paul Walmsley 2019-04-30 203 * @target_rate: target PLL output clock rate (post-Q-divider)
7b9487a9a5c41ce Paul Walmsley 2019-04-30 204 * @parent_rate: PLL input refclk rate (pre-R-divider)
7b9487a9a5c41ce Paul Walmsley 2019-04-30 205 *
7b9487a9a5c41ce Paul Walmsley 2019-04-30 206 * Compute the appropriate PLL signal configuration values and store
7b9487a9a5c41ce Paul Walmsley 2019-04-30 207 * in PLL context @c. PLL reprogramming is not glitchless, so the
7b9487a9a5c41ce Paul Walmsley 2019-04-30 208 * caller should switch any downstream logic to a different clock
7b9487a9a5c41ce Paul Walmsley 2019-04-30 209 * source or clock-gate it before presenting these values to the PLL
7b9487a9a5c41ce Paul Walmsley 2019-04-30 210 * configuration signals.
7b9487a9a5c41ce Paul Walmsley 2019-04-30 211 *
7b9487a9a5c41ce Paul Walmsley 2019-04-30 212 * The caller must pass this function a pre-initialized struct
7b9487a9a5c41ce Paul Walmsley 2019-04-30 213 * wrpll_cfg record: either initialized to zero (with the
7b9487a9a5c41ce Paul Walmsley 2019-04-30 214 * exception of the .name and .flags fields) or read from the PLL.
7b9487a9a5c41ce Paul Walmsley 2019-04-30 215 *
7b9487a9a5c41ce Paul Walmsley 2019-04-30 216 * Context: Any context. Caller must protect the memory pointed to by @c
7b9487a9a5c41ce Paul Walmsley 2019-04-30 217 * from simultaneous access or modification.
7b9487a9a5c41ce Paul Walmsley 2019-04-30 218 *
7b9487a9a5c41ce Paul Walmsley 2019-04-30 219 * Return: 0 upon success; anything else upon failure.
7b9487a9a5c41ce Paul Walmsley 2019-04-30 220 */
7b9487a9a5c41ce Paul Walmsley 2019-04-30 221 int wrpll_configure_for_rate(struct wrpll_cfg *c, u32 target_rate,
7b9487a9a5c41ce Paul Walmsley 2019-04-30 222 unsigned long parent_rate)
7b9487a9a5c41ce Paul Walmsley 2019-04-30 @223 {
7b9487a9a5c41ce Paul Walmsley 2019-04-30 224 unsigned long ratio;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 225 u64 target_vco_rate, delta, best_delta, f_pre_div, vco, vco_pre;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 226 u32 best_f, f, post_divr_freq;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 227 u8 fbdiv, divq, best_r, r;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 228 int range;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 229
7b9487a9a5c41ce Paul Walmsley 2019-04-30 230 if (c->flags == 0) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30 231 WARN(1, "%s called with uninitialized PLL config", __func__);
7b9487a9a5c41ce Paul Walmsley 2019-04-30 232 return -EINVAL;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 233 }
7b9487a9a5c41ce Paul Walmsley 2019-04-30 234
7b9487a9a5c41ce Paul Walmsley 2019-04-30 235 /* Initialize rounding data if it hasn't been initialized already */
7b9487a9a5c41ce Paul Walmsley 2019-04-30 236 if (parent_rate != c->parent_rate) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30 237 if (__wrpll_update_parent_rate(c, parent_rate)) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30 238 pr_err("%s: PLL input rate is out of range\n",
7b9487a9a5c41ce Paul Walmsley 2019-04-30 239 __func__);
7b9487a9a5c41ce Paul Walmsley 2019-04-30 240 return -ERANGE;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 241 }
7b9487a9a5c41ce Paul Walmsley 2019-04-30 242 }
7b9487a9a5c41ce Paul Walmsley 2019-04-30 243
7b9487a9a5c41ce Paul Walmsley 2019-04-30 244 c->flags &= ~WRPLL_FLAGS_RESET_MASK;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 245
7b9487a9a5c41ce Paul Walmsley 2019-04-30 246 /* Put the PLL into bypass if the user requests the parent clock rate */
7b9487a9a5c41ce Paul Walmsley 2019-04-30 247 if (target_rate == parent_rate) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30 248 c->flags |= WRPLL_FLAGS_BYPASS_MASK;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 249 return 0;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 250 }
7b9487a9a5c41ce Paul Walmsley 2019-04-30 251
7b9487a9a5c41ce Paul Walmsley 2019-04-30 252 c->flags &= ~WRPLL_FLAGS_BYPASS_MASK;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 253
7b9487a9a5c41ce Paul Walmsley 2019-04-30 254 /* Calculate the Q shift and target VCO rate */
7b9487a9a5c41ce Paul Walmsley 2019-04-30 255 divq = __wrpll_calc_divq(target_rate, &target_vco_rate);
7b9487a9a5c41ce Paul Walmsley 2019-04-30 256 if (!divq)
7b9487a9a5c41ce Paul Walmsley 2019-04-30 257 return -1;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 258 c->divq = divq;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 259
7b9487a9a5c41ce Paul Walmsley 2019-04-30 260 /* Precalculate the pre-Q divider target ratio */
7b9487a9a5c41ce Paul Walmsley 2019-04-30 261 ratio = div64_u64((target_vco_rate << ROUND_SHIFT), parent_rate);
7b9487a9a5c41ce Paul Walmsley 2019-04-30 262
7b9487a9a5c41ce Paul Walmsley 2019-04-30 263 fbdiv = __wrpll_calc_fbdiv(c);
7b9487a9a5c41ce Paul Walmsley 2019-04-30 264 best_r = 0;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 265 best_f = 0;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 266 best_delta = MAX_VCO_FREQ;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 267
7b9487a9a5c41ce Paul Walmsley 2019-04-30 268 /*
7b9487a9a5c41ce Paul Walmsley 2019-04-30 269 * Consider all values for R which land within
7b9487a9a5c41ce Paul Walmsley 2019-04-30 270 * [MIN_POST_DIVR_FREQ, MAX_POST_DIVR_FREQ]; prefer smaller R
7b9487a9a5c41ce Paul Walmsley 2019-04-30 271 */
7b9487a9a5c41ce Paul Walmsley 2019-04-30 272 for (r = c->init_r; r <= c->max_r; ++r) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30 273 f_pre_div = ratio * r;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 274 f = (f_pre_div + (1 << ROUND_SHIFT)) >> ROUND_SHIFT;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 275 f >>= (fbdiv - 1);
7b9487a9a5c41ce Paul Walmsley 2019-04-30 276
7b9487a9a5c41ce Paul Walmsley 2019-04-30 277 post_divr_freq = div_u64(parent_rate, r);
7b9487a9a5c41ce Paul Walmsley 2019-04-30 278 vco_pre = fbdiv * post_divr_freq;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 279 vco = vco_pre * f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 280
7b9487a9a5c41ce Paul Walmsley 2019-04-30 281 /* Ensure rounding didn't take us out of range */
7b9487a9a5c41ce Paul Walmsley 2019-04-30 282 if (vco > target_vco_rate) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30 283 --f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 284 vco = vco_pre * f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 285 } else if (vco < MIN_VCO_FREQ) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30 286 ++f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 287 vco = vco_pre * f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 288 }
7b9487a9a5c41ce Paul Walmsley 2019-04-30 289
7b9487a9a5c41ce Paul Walmsley 2019-04-30 290 delta = abs(target_rate - vco);
7b9487a9a5c41ce Paul Walmsley 2019-04-30 291 if (delta < best_delta) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30 292 best_delta = delta;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 293 best_r = r;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 294 best_f = f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 295 }
7b9487a9a5c41ce Paul Walmsley 2019-04-30 296 }
7b9487a9a5c41ce Paul Walmsley 2019-04-30 297
7b9487a9a5c41ce Paul Walmsley 2019-04-30 298 c->divr = best_r - 1;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 299 c->divf = best_f - 1;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 300
7b9487a9a5c41ce Paul Walmsley 2019-04-30 301 post_divr_freq = div_u64(parent_rate, best_r);
7b9487a9a5c41ce Paul Walmsley 2019-04-30 302
7b9487a9a5c41ce Paul Walmsley 2019-04-30 303 /* Pick the best PLL jitter filter */
7b9487a9a5c41ce Paul Walmsley 2019-04-30 304 range = __wrpll_calc_filter_range(post_divr_freq);
7b9487a9a5c41ce Paul Walmsley 2019-04-30 305 if (range < 0)
7b9487a9a5c41ce Paul Walmsley 2019-04-30 306 return range;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 307 c->range = range;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 308
7b9487a9a5c41ce Paul Walmsley 2019-04-30 309 return 0;
7b9487a9a5c41ce Paul Walmsley 2019-04-30 310 }
7b9487a9a5c41ce Paul Walmsley 2019-04-30 311
---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/[email protected]
On Fri, Oct 23, 2020 at 06:33:33PM +0200, Mauro Carvalho Chehab wrote:
> hlist_add_behing -> hlist_add_behind
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Acked-by: Paul E. McKenney <[email protected]>
> ---
> include/linux/list.h | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/include/linux/list.h b/include/linux/list.h
> index a18c87b63376..f72a7a778722 100644
> --- a/include/linux/list.h
> +++ b/include/linux/list.h
> @@ -901,7 +901,7 @@ static inline void hlist_add_before(struct hlist_node *n,
> }
>
> /**
> - * hlist_add_behing - add a new entry after the one specified
> + * hlist_add_behind - add a new entry after the one specified
> * @n: new entry to be added
> * @prev: hlist node to add it after, which must be non-NULL
> */
> --
> 2.26.2
>
On Fri, Oct 23, 2020 at 06:33:05PM +0200, Mauro Carvalho Chehab wrote:
> Some functions have different names between their prototypes
> and the kernel-doc markup.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> drivers/net/phy/mdio_bus.c | 2 +-
> drivers/net/phy/phy-c45.c | 2 +-
> drivers/net/phy/phy.c | 2 +-
> drivers/net/phy/phy_device.c | 2 +-
> drivers/net/phy/phylink.c | 2 +-
> 5 files changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/drivers/net/phy/mdio_bus.c b/drivers/net/phy/mdio_bus.c
> index 757e950fb745..e59067c64e97 100644
> --- a/drivers/net/phy/mdio_bus.c
> +++ b/drivers/net/phy/mdio_bus.c
> @@ -472,7 +472,7 @@ static inline void of_mdiobus_link_mdiodev(struct mii_bus *mdio,
> #endif
>
> /**
> - * mdiobus_create_device_from_board_info - create a full MDIO device given
> + * mdiobus_create_device - create a full MDIO device given
> * a mdio_board_info structure
> * @bus: MDIO bus to create the devices on
> * @bi: mdio_board_info structure describing the devices
Hi Mauro
If you need to repost, could you make use of:
-U<n>
--unified=<n>
Generate diffs with <n> lines of context instead of the usual three.
to increase the number of lines of context. Often three lines is not
enough to include the function declaration in the patch, so i need to
go look at the sources to do a review.
Reviewed-by: Andrew Lunn <[email protected]>
Andrew
Applied. Thanks!
Alex
On Fri, Oct 23, 2020 at 12:51 PM Christian König
<[email protected]> wrote:
>
> Am 23.10.20 um 18:32 schrieb Mauro Carvalho Chehab:
> > Some functions have different names between their prototypes
> > and the kernel-doc markup.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>
> Acked-by: Christian König <[email protected]>
>
> > ---
> > drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c | 2 +-
> > drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 2 +-
> > include/uapi/drm/amdgpu_drm.h | 2 +-
> > 3 files changed, 3 insertions(+), 3 deletions(-)
> >
> > diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> > index df110afa97bf..a5f73a267fe5 100644
> > --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> > +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> > @@ -2166,7 +2166,7 @@ struct amdgpu_bo_va *amdgpu_vm_bo_add(struct amdgpu_device *adev,
> >
> >
> > /**
> > - * amdgpu_vm_bo_insert_mapping - insert a new mapping
> > + * amdgpu_vm_bo_insert_map - insert a new mapping
> > *
> > * @adev: amdgpu_device pointer
> > * @bo_va: bo_va to store the address
> > diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> > index 0c6b7c5ecfec..795bad307497 100644
> > --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> > +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> > @@ -528,7 +528,7 @@ int amdgpu_vram_mgr_alloc_sgt(struct amdgpu_device *adev,
> > }
> >
> > /**
> > - * amdgpu_vram_mgr_alloc_sgt - allocate and fill a sg table
> > + * amdgpu_vram_mgr_free_sgt - allocate and fill a sg table
> > *
> > * @adev: amdgpu device pointer
> > * @sgt: sg table to free
> > diff --git a/include/uapi/drm/amdgpu_drm.h b/include/uapi/drm/amdgpu_drm.h
> > index c5ff2b275fcd..791a1d597d2a 100644
> > --- a/include/uapi/drm/amdgpu_drm.h
> > +++ b/include/uapi/drm/amdgpu_drm.h
> > @@ -667,7 +667,7 @@ struct drm_amdgpu_cs_chunk_data {
> > };
> > };
> >
> > -/**
> > +/*
> > * Query h/w info: Flag that this is integrated (a.h.a. fusion) GPU
> > *
> > */
>
> _______________________________________________
> amd-gfx mailing list
> [email protected]
> https://lists.freedesktop.org/mailman/listinfo/amd-gfx
Hi Mauro,
I love your patch! Perhaps something to improve:
[auto build test WARNING on next-20201023]
[cannot apply to linuxtv-media/master sound/for-next pci/next mkp-scsi/for-next scsi/for-next linus/master v5.9 v5.9-rc8 v5.9-rc7 v5.9]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch]
url: https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20201024-004025
base: 9695c4ff26459ff5bfe25c7d6179e4c9c00e1363
config: arm-randconfig-r005-20201024 (attached as .config)
compiler: arm-linux-gnueabi-gcc (GCC) 9.3.0
reproduce (this is a W=1 build):
wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
chmod +x ~/bin/make.cross
# https://github.com/0day-ci/linux/commit/002bbfc5a97ce37daf3c570e0edd28fa0c7de5b8
git remote add linux-review https://github.com/0day-ci/linux
git fetch --no-tags linux-review Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20201024-004025
git checkout 002bbfc5a97ce37daf3c570e0edd28fa0c7de5b8
# save the attached .config to linux build tree
COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-9.3.0 make.cross ARCH=arm
If you fix the issue, kindly add following tag as appropriate
Reported-by: kernel test robot <[email protected]>
All warnings (new ones prefixed by >>):
arch/arm/mm/init.c:538: warning: Function parameter or member 'perms' not described in 'update_sections_early'
arch/arm/mm/init.c:538: warning: Function parameter or member 'n' not described in 'update_sections_early'
>> arch/arm/mm/init.c:538: warning: expecting prototype for update_sections_early intended to be called only through stop_machine(). Prototype was for update_sections_early() instead
--
>> drivers/ata/pata_legacy.c:606: warning: expecting prototype for opt82c465mv_qc_issue(). Prototype was for opti82c46x_qc_issue() instead
drivers/ata/pata_legacy.c:933: warning: Function parameter or member 'probe' not described in 'legacy_init_one'
drivers/ata/pata_legacy.c:933: warning: Excess function parameter 'pl' description in 'legacy_init_one'
drivers/ata/pata_legacy.c:1024: warning: Function parameter or member 'primary' not described in 'legacy_check_special_cases'
drivers/ata/pata_legacy.c:1024: warning: Function parameter or member 'secondary' not described in 'legacy_check_special_cases'
drivers/ata/pata_legacy.c:1024: warning: Excess function parameter 'master' description in 'legacy_check_special_cases'
drivers/ata/pata_legacy.c:1024: warning: Excess function parameter 'master' description in 'legacy_check_special_cases'
--
>> drivers/irqchip/irq-ixp4xx.c:259: warning: expecting prototype for ixp4x_irq_setup(). Prototype was for ixp4xx_irq_setup() instead
--
drivers/scsi/pmcraid.c:455: warning: Function parameter or member 'intrs' not described in 'pmcraid_enable_interrupts'
drivers/scsi/pmcraid.c:455: warning: Excess function parameter 'intr' description in 'pmcraid_enable_interrupts'
drivers/scsi/pmcraid.c:543: warning: Function parameter or member '' not described in 'pmcraid_ioa_reset'
>> drivers/scsi/pmcraid.c:543: warning: expecting prototype for pmcraid_bist_done(). Prototype was for pmcraid_ioa_reset() instead
drivers/scsi/pmcraid.c:603: warning: Function parameter or member 't' not described in 'pmcraid_reset_alert_done'
drivers/scsi/pmcraid.c:603: warning: Excess function parameter 'cmd' description in 'pmcraid_reset_alert_done'
drivers/scsi/pmcraid.c:638: warning: Function parameter or member '' not described in 'pmcraid_notify_ioastate'
drivers/scsi/pmcraid.c:638: warning: Function parameter or member 'u32' not described in 'pmcraid_notify_ioastate'
>> drivers/scsi/pmcraid.c:638: warning: expecting prototype for pmcraid_reset_alert(). Prototype was for pmcraid_notify_ioastate() instead
drivers/scsi/pmcraid.c:687: warning: Function parameter or member 't' not described in 'pmcraid_timeout_handler'
drivers/scsi/pmcraid.c:687: warning: Excess function parameter 'cmd' description in 'pmcraid_timeout_handler'
>> drivers/scsi/pmcraid.c:858: warning: expecting prototype for pmcraid_fire_command(). Prototype was for _pmcraid_fire_command() instead
drivers/scsi/pmcraid.c:972: warning: Function parameter or member '' not described in 'pmcraid_querycfg'
>> drivers/scsi/pmcraid.c:972: warning: expecting prototype for pmcraid_get_fwversion_done(). Prototype was for pmcraid_querycfg() instead
drivers/scsi/pmcraid.c:1398: warning: Function parameter or member 'aen_msg' not described in 'pmcraid_notify_aen'
drivers/scsi/pmcraid.c:1398: warning: Function parameter or member 'data_size' not described in 'pmcraid_notify_aen'
drivers/scsi/pmcraid.c:1398: warning: Excess function parameter 'type' description in 'pmcraid_notify_aen'
drivers/scsi/pmcraid.c:1781: warning: Function parameter or member '' not described in 'pmcraid_initiate_reset'
>> drivers/scsi/pmcraid.c:1781: warning: expecting prototype for pmcraid_process_ldn(). Prototype was for pmcraid_initiate_reset() instead
drivers/scsi/pmcraid.c:1887: warning: Function parameter or member '' not described in 'pmcraid_reinit_buffers'
>> drivers/scsi/pmcraid.c:1887: warning: expecting prototype for pmcraid_reset_enable_ioa(). Prototype was for pmcraid_reinit_buffers() instead
drivers/scsi/pmcraid.c:2704: warning: Function parameter or member 'timeout' not described in 'pmcraid_reset_device'
>> drivers/scsi/pmcraid.c:3025: warning: expecting prototype for pmcraid_eh_xxxx_reset_handler(). Prototype was for pmcraid_eh_device_reset_handler() instead
>> drivers/scsi/pmcraid.c:3327: warning: expecting prototype for pmcraid_queuecommand(). Prototype was for pmcraid_queuecommand_lck() instead
drivers/scsi/pmcraid.c:3437: warning: Function parameter or member 'inode' not described in 'pmcraid_chr_open'
drivers/scsi/pmcraid.c:3437: warning: Function parameter or member 'filep' not described in 'pmcraid_chr_open'
>> drivers/scsi/pmcraid.c:3437: warning: expecting prototype for pmcraid_open(). Prototype was for pmcraid_chr_open() instead
drivers/scsi/pmcraid.c:3457: warning: Function parameter or member 'fd' not described in 'pmcraid_chr_fasync'
drivers/scsi/pmcraid.c:3457: warning: Function parameter or member 'filep' not described in 'pmcraid_chr_fasync'
drivers/scsi/pmcraid.c:3457: warning: Function parameter or member 'mode' not described in 'pmcraid_chr_fasync'
>> drivers/scsi/pmcraid.c:3457: warning: expecting prototype for pmcraid_fasync(). Prototype was for pmcraid_chr_fasync() instead
drivers/scsi/pmcraid.c:3574: warning: Function parameter or member 'ioctl_cmd' not described in 'pmcraid_ioctl_passthrough'
drivers/scsi/pmcraid.c:3574: warning: Function parameter or member 'buflen' not described in 'pmcraid_ioctl_passthrough'
drivers/scsi/pmcraid.c:3574: warning: Excess function parameter 'cmd' description in 'pmcraid_ioctl_passthrough'
drivers/scsi/pmcraid.c:3905: warning: Function parameter or member 'filep' not described in 'pmcraid_chr_ioctl'
drivers/scsi/pmcraid.c:3905: warning: Function parameter or member 'cmd' not described in 'pmcraid_chr_ioctl'
drivers/scsi/pmcraid.c:3905: warning: Function parameter or member 'arg' not described in 'pmcraid_chr_ioctl'
>> drivers/scsi/pmcraid.c:3905: warning: expecting prototype for pmcraid_ioctl(). Prototype was for pmcraid_chr_ioctl() instead
drivers/scsi/pmcraid.c:3969: warning: cannot understand function prototype: 'const struct file_operations pmcraid_fops = '
drivers/scsi/pmcraid.c:3993: warning: Function parameter or member 'attr' not described in 'pmcraid_show_log_level'
drivers/scsi/pmcraid.c:4015: warning: Function parameter or member 'attr' not described in 'pmcraid_store_log_level'
drivers/scsi/pmcraid.c:4055: warning: Function parameter or member 'attr' not described in 'pmcraid_show_drv_version'
drivers/scsi/pmcraid.c:4081: warning: Function parameter or member 'attr' not described in 'pmcraid_show_adapter_id'
>> drivers/scsi/pmcraid.c:4081: warning: expecting prototype for pmcraid_show_io_adapter_id(). Prototype was for pmcraid_show_adapter_id() instead
drivers/scsi/pmcraid.c:4600: warning: Function parameter or member 'pinstance' not described in 'pmcraid_allocate_cmd_blocks'
drivers/scsi/pmcraid.c:5153: warning: Function parameter or member 'minor' not described in 'pmcraid_release_minor'
--
drivers/vfio/vfio.c:224: warning: Function parameter or member 'ops' not described in 'vfio_register_iommu_driver'
>> drivers/vfio/vfio.c:224: warning: expecting prototype for IOMMU driver registration(). Prototype was for vfio_register_iommu_driver() instead
drivers/vfio/vfio.c:273: warning: Function parameter or member 'group' not described in 'vfio_alloc_group_minor'
>> drivers/vfio/vfio.c:273: warning: expecting prototype for free(). Prototype was for vfio_alloc_group_minor() instead
drivers/vfio/vfio.c:293: warning: Function parameter or member 'container' not described in 'vfio_container_get'
>> drivers/vfio/vfio.c:293: warning: expecting prototype for Container objects(). Prototype was for vfio_container_get() instead
drivers/vfio/vfio.c:325: warning: Function parameter or member 'iommu_group' not described in 'vfio_create_group'
>> drivers/vfio/vfio.c:325: warning: expecting prototype for Group objects(). Prototype was for vfio_create_group() instead
drivers/vfio/vfio.c:540: warning: Function parameter or member 'group' not described in 'vfio_group_create_device'
drivers/vfio/vfio.c:540: warning: Function parameter or member 'dev' not described in 'vfio_group_create_device'
drivers/vfio/vfio.c:540: warning: Function parameter or member 'ops' not described in 'vfio_group_create_device'
drivers/vfio/vfio.c:540: warning: Function parameter or member 'device_data' not described in 'vfio_group_create_device'
>> drivers/vfio/vfio.c:540: warning: expecting prototype for Device objects(). Prototype was for vfio_group_create_device() instead
drivers/vfio/vfio.c:694: warning: Function parameter or member 'group' not described in 'vfio_group_nb_add_dev'
drivers/vfio/vfio.c:694: warning: Function parameter or member 'dev' not described in 'vfio_group_nb_add_dev'
>> drivers/vfio/vfio.c:694: warning: expecting prototype for Async device support(). Prototype was for vfio_group_nb_add_dev() instead
drivers/vfio/vfio.c:806: warning: Function parameter or member 'dev' not described in 'vfio_add_group_dev'
drivers/vfio/vfio.c:806: warning: Function parameter or member 'ops' not described in 'vfio_add_group_dev'
drivers/vfio/vfio.c:806: warning: Function parameter or member 'device_data' not described in 'vfio_add_group_dev'
>> drivers/vfio/vfio.c:806: warning: expecting prototype for VFIO driver API(). Prototype was for vfio_add_group_dev() instead
drivers/vfio/vfio.c:864: warning: Function parameter or member 'dev' not described in 'vfio_device_get_from_dev'
>> drivers/vfio/vfio.c:864: warning: expecting prototype for Even if the(). Prototype was for vfio_device_get_from_dev() instead
drivers/vfio/vfio.c:1022: warning: Function parameter or member 'container' not described in 'vfio_ioctl_check_extension'
drivers/vfio/vfio.c:1022: warning: Function parameter or member 'arg' not described in 'vfio_ioctl_check_extension'
>> drivers/vfio/vfio.c:1022: warning: expecting prototype for vfio(). Prototype was for vfio_ioctl_check_extension() instead
drivers/vfio/vfio.c:1293: warning: Function parameter or member 'group' not described in '__vfio_group_unset_container'
>> drivers/vfio/vfio.c:1293: warning: expecting prototype for GROUP(). Prototype was for __vfio_group_unset_container() instead
drivers/vfio/vfio.c:1628: warning: Function parameter or member 'inode' not described in 'vfio_device_fops_release'
drivers/vfio/vfio.c:1628: warning: Function parameter or member 'filep' not described in 'vfio_device_fops_release'
>> drivers/vfio/vfio.c:1628: warning: expecting prototype for VFIO Device fd(). Prototype was for vfio_device_fops_release() instead
>> drivers/vfio/vfio.c:1695: warning: wrong kernel-doc identifier on line:
* External user API, exported by symbols to be linked dynamically.
drivers/vfio/vfio.c:1740: warning: wrong kernel-doc identifier on line:
* External user API, exported by symbols to be linked dynamically.
drivers/vfio/vfio.c:1819: warning: Function parameter or member 'caps' not described in 'vfio_info_cap_add'
drivers/vfio/vfio.c:1819: warning: Function parameter or member 'size' not described in 'vfio_info_cap_add'
drivers/vfio/vfio.c:1819: warning: Function parameter or member 'id' not described in 'vfio_info_cap_add'
drivers/vfio/vfio.c:1819: warning: Function parameter or member 'version' not described in 'vfio_info_cap_add'
>> drivers/vfio/vfio.c:1819: warning: expecting prototype for Sub(). Prototype was for vfio_info_cap_add() instead
drivers/vfio/vfio.c:2338: warning: Function parameter or member 'dev' not described in 'vfio_devnode'
drivers/vfio/vfio.c:2338: warning: Function parameter or member 'mode' not described in 'vfio_devnode'
>> drivers/vfio/vfio.c:2338: warning: expecting prototype for class support(). Prototype was for vfio_devnode() instead
--
>> drivers/mmc/core/queue.c:212: warning: expecting prototype for mmc_init_request(). Prototype was for __mmc_init_request() instead
--
>> drivers/crypto/chelsio/chcr_core.c:2: warning: wrong kernel-doc identifier on line:
* This file is part of the Chelsio T4/T5/T6 Ethernet driver for Linux.
--
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: Function parameter or member 'host' not described in 'brcmnand_edu_trans'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: Function parameter or member 'addr' not described in 'brcmnand_edu_trans'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: Function parameter or member 'buf' not described in 'brcmnand_edu_trans'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: Function parameter or member 'len' not described in 'brcmnand_edu_trans'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: Function parameter or member 'cmd' not described in 'brcmnand_edu_trans'
>> drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: expecting prototype for Kick EDU engine(). Prototype was for brcmnand_edu_trans() instead
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'host' not described in 'brcmnand_fill_dma_desc'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'desc' not described in 'brcmnand_fill_dma_desc'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'addr' not described in 'brcmnand_fill_dma_desc'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'buf' not described in 'brcmnand_fill_dma_desc'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'len' not described in 'brcmnand_fill_dma_desc'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'dma_cmd' not described in 'brcmnand_fill_dma_desc'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'begin' not described in 'brcmnand_fill_dma_desc'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'end' not described in 'brcmnand_fill_dma_desc'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'next_desc' not described in 'brcmnand_fill_dma_desc'
>> drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: expecting prototype for You must know the(). Prototype was for brcmnand_fill_dma_desc() instead
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1977: warning: Function parameter or member 'host' not described in 'brcmnand_dma_run'
drivers/mtd/nand/raw/brcmnand/brcmnand.c:1977: warning: Function parameter or member 'desc' not described in 'brcmnand_dma_run'
>> drivers/mtd/nand/raw/brcmnand/brcmnand.c:1977: warning: expecting prototype for with a given DMA descriptor(). Prototype was for brcmnand_dma_run() instead
--
>> drivers/net/wireless/intel/ipw2x00/ipw2100.c:5375: warning: expecting prototype for Set a the wep key(). Prototype was for ipw2100_set_key() instead
>> drivers/net/wireless/intel/ipw2x00/ipw2100.c:6542: warning: expecting prototype for module(). Prototype was for ipw2100_init() instead
>> drivers/net/wireless/intel/ipw2x00/ipw2100.c:6568: warning: expecting prototype for Cleanup ipw2100 driver registration(). Prototype was for ipw2100_exit() instead
--
>> drivers/net/ethernet/chelsio/cxgb4/cxgb4_ptp.c:455: warning: expecting prototype for cxgb4_ptp_remove(). Prototype was for cxgb4_ptp_stop() instead
--
>> drivers/net/ethernet/chelsio/cxgb4/t4_hw.c:7000: warning: expecting prototype for t4_init_cmd(). Prototype was for t4_early_init() instead
>> drivers/net/ethernet/chelsio/cxgb4/t4_hw.c:10241: warning: expecting prototype for t4_set_vf_mac(). Prototype was for t4_set_vf_mac_acl() instead
..
vim +538 arch/arm/mm/init.c
1e6b48116a9504 Kees Cook 2014-04-03 531
11ce4b33aedc65 Grygorii Strashko 2017-04-25 532 /**
11ce4b33aedc65 Grygorii Strashko 2017-04-25 533 * update_sections_early intended to be called only through stop_machine
11ce4b33aedc65 Grygorii Strashko 2017-04-25 534 * framework and executed by only one CPU while all other CPUs will spin and
11ce4b33aedc65 Grygorii Strashko 2017-04-25 535 * wait, so no locking is required in this function.
11ce4b33aedc65 Grygorii Strashko 2017-04-25 536 */
08925c2f124f1b Laura Abbott 2015-11-30 537 static void update_sections_early(struct section_perm perms[], int n)
1e6b48116a9504 Kees Cook 2014-04-03 @538 {
08925c2f124f1b Laura Abbott 2015-11-30 539 struct task_struct *t, *s;
08925c2f124f1b Laura Abbott 2015-11-30 540
08925c2f124f1b Laura Abbott 2015-11-30 541 for_each_process(t) {
08925c2f124f1b Laura Abbott 2015-11-30 542 if (t->flags & PF_KTHREAD)
08925c2f124f1b Laura Abbott 2015-11-30 543 continue;
08925c2f124f1b Laura Abbott 2015-11-30 544 for_each_thread(t, s)
c51bc12d06b3a5 Doug Berger 2019-07-01 545 if (s->mm)
08925c2f124f1b Laura Abbott 2015-11-30 546 set_section_perms(perms, n, true, s->mm);
08925c2f124f1b Laura Abbott 2015-11-30 547 }
08925c2f124f1b Laura Abbott 2015-11-30 548 set_section_perms(perms, n, true, current->active_mm);
08925c2f124f1b Laura Abbott 2015-11-30 549 set_section_perms(perms, n, true, &init_mm);
08925c2f124f1b Laura Abbott 2015-11-30 550 }
08925c2f124f1b Laura Abbott 2015-11-30 551
---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/[email protected]
Em Fri, 23 Oct 2020 13:47:57 -0600
Jonathan Corbet <[email protected]> escreveu:
> On Fri, 23 Oct 2020 21:39:07 +0200
> Peter Zijlstra <[email protected]> wrote:
>
> > > > /**
> > > > - * struct refcount_t - variant of atomic_t specialized for reference counts
> > > > + * struct refcount_struct - variant of atomic_t specialized for reference counts
> > >
> > > Hm, this is a weird one. Yes, it's actually "struct refcount_struct",
> > > but the usage should be refcount_t (through the typedef). I'm not sure
> > > what the right way to document this is.
> >
> > Yeah, this is wrong. If this is due to a kernel doc warning, the kernel
> > doc machinery is wrong *again*.
This issue has nothing to do with warnings. The problem here is that
"struct" is a markup for structs, and not for typedefs.
>
> ...except that, since refcount_t is a typedef, "struct refcount_t" doesn't
> actually exist. Whether it works properly after doing s/struct// remains
> to be seen...
If the intent is to document the struct and its internal fields,
this kernel-doc should work:
/**
* struct refcount_struct - variant of atomic_t specialized for reference counts
* @refs: atomic_t counter field
*
* The counter saturates at REFCOUNT_SATURATED and will not move once
* there. This avoids wrapping the counter and causing 'spurious'
* use-after-free bugs.
*/
Which produces this result:
.. c:struct:: refcount_struct
variant of atomic_t specialized for reference counts
**Definition**
::
struct refcount_struct {
atomic_t refs;
};
**Members**
``refs``
atomic_t counter field
(description)
See, in this case, the identifier is not opaque: its members are
documented at the html (or man) output.
If you want, instead, to document the typedef, this is the
proper way:
/**
* typedef refcount_t - variant of atomic_t specialized for reference counts
*
* The counter saturates at REFCOUNT_SATURATED and will not move once
* there. This avoids wrapping the counter and causing 'spurious'
* use-after-free bugs.
*/
It will handle this one as an opaque type, meaning that it won't be
showing the "refs" field - even if you forget to drop the @refs:
at the markup. The result will be:
.. c:type:: refcount_t
variant of atomic_t specialized for reference counts
(description)
-
If you want both, then you would either split struct and typedef, e. g.
with something like:
/**
* struct refcount_struct - variant of atomic_t specialized for reference counts
* @refs: atomic_t counter field
*
* The counter saturates at REFCOUNT_SATURATED and will not move once
* there. This avoids wrapping the counter and causing 'spurious'
* use-after-free bugs.
*/
struct refcount_struct {
atomic_t refs;
};
/**
* typedef refcount_t - variant of atomic_t specialized for reference counts
* @refs: atomic_t counter field
*
* The counter saturates at REFCOUNT_SATURATED and will not move once
* there. This avoids wrapping the counter and causing 'spurious'
* use-after-free bugs.
*/
typedef struct refcount_struct refcount_t;
Or, you could add the member at the description field. E. g. something
like this:
/**
* typedef refcount_t - variant of atomic_t specialized for reference counts
*
* The counter saturates at REFCOUNT_SATURATED and will not move once
* there. This avoids wrapping the counter and causing 'spurious'
* use-after-free bugs.
*
* Members:
* ``refs``
* atomic_t counter field
*/
typedef struct refcount_struct {
atomic_t refs;
} refcount_t;
If you want to test it, you can run kernel-doc directly, to see how
it will parse it. For ReST output, that's the syntax:
./scripts/kernel-doc --sphinx-version 3 include/linux/refcount.h
Thanks,
Mauro
Em Fri, 23 Oct 2020 12:43:25 -0500
Bjorn Helgaas <[email protected]> escreveu:
> If you have the opportunity, I would prefer to capitalize the subject
> to follow the drivers/pci convention, e.g.,
>
> PCI: Fix ...
Ok. If you want to apply it directly, feel free to change it
at the patch.
Otherwise, I'll do it on a next rebase.
>
> On Fri, Oct 23, 2020 at 06:33:10PM +0200, Mauro Carvalho Chehab wrote:
> > Some identifiers have different names between their prototypes
> > and the kernel-doc markup.
>
> How did you find these? I build with "make W=1", which finds some
> kernel-doc errors, but it didn't find these. If there's a scanner for
> these, I could fix things like this before merging them.
This is a new check. See patch 56/56.
Right now, kernel-doc will just silently ignore the identifier
from kernel-doc markup and use the one defined at the function
or data struct prototype.
Once all the issues gets fixed, patch 56/56 can be merged.
>
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>
> I'd be happy to take this myself, but if you want to merge the whole
> series together:
>
> Acked-by: Bjorn Helgaas <[email protected]>
Either way works for me, although IMO it should be simpler if
you could pick it directly, as it will avoid potential
merge conflicts if such patches go via their usual trees.
>
> > ---
> > drivers/pci/p2pdma.c | 10 +++++-----
> > drivers/pci/pci-driver.c | 4 ++--
> > drivers/pci/pci.c | 2 +-
> > drivers/pci/probe.c | 4 ++--
> > drivers/pci/slot.c | 5 +++--
> > 5 files changed, 13 insertions(+), 12 deletions(-)
> >
> > diff --git a/drivers/pci/p2pdma.c b/drivers/pci/p2pdma.c
> > index de1c331dbed4..bace04145c5f 100644
> > --- a/drivers/pci/p2pdma.c
> > +++ b/drivers/pci/p2pdma.c
> > @@ -609,7 +609,7 @@ bool pci_has_p2pmem(struct pci_dev *pdev)
> > EXPORT_SYMBOL_GPL(pci_has_p2pmem);
> >
> > /**
> > - * pci_p2pmem_find - find a peer-to-peer DMA memory device compatible with
> > + * pci_p2pmem_find_many - find a peer-to-peer DMA memory device compatible with
> > * the specified list of clients and shortest distance (as determined
> > * by pci_p2pmem_dma())
> > * @clients: array of devices to check (NULL-terminated)
> > @@ -674,7 +674,7 @@ struct pci_dev *pci_p2pmem_find_many(struct device **clients, int num_clients)
> > EXPORT_SYMBOL_GPL(pci_p2pmem_find_many);
> >
> > /**
> > - * pci_alloc_p2p_mem - allocate peer-to-peer DMA memory
> > + * pci_alloc_p2pmem - allocate peer-to-peer DMA memory
> > * @pdev: the device to allocate memory from
> > * @size: number of bytes to allocate
> > *
> > @@ -727,7 +727,7 @@ void pci_free_p2pmem(struct pci_dev *pdev, void *addr, size_t size)
> > EXPORT_SYMBOL_GPL(pci_free_p2pmem);
> >
> > /**
> > - * pci_virt_to_bus - return the PCI bus address for a given virtual
> > + * pci_p2pmem_virt_to_bus - return the PCI bus address for a given virtual
> > * address obtained with pci_alloc_p2pmem()
> > * @pdev: the device the memory was allocated from
> > * @addr: address of the memory that was allocated
> > @@ -859,7 +859,7 @@ static int __pci_p2pdma_map_sg(struct pci_p2pdma_pagemap *p2p_pgmap,
> > }
> >
> > /**
> > - * pci_p2pdma_map_sg - map a PCI peer-to-peer scatterlist for DMA
> > + * pci_p2pdma_map_sg_attrs - map a PCI peer-to-peer scatterlist for DMA
> > * @dev: device doing the DMA request
> > * @sg: scatter list to map
> > * @nents: elements in the scatterlist
> > @@ -896,7 +896,7 @@ int pci_p2pdma_map_sg_attrs(struct device *dev, struct scatterlist *sg,
> > EXPORT_SYMBOL_GPL(pci_p2pdma_map_sg_attrs);
> >
> > /**
> > - * pci_p2pdma_unmap_sg - unmap a PCI peer-to-peer scatterlist that was
> > + * pci_p2pdma_unmap_sg_attrs - unmap a PCI peer-to-peer scatterlist that was
> > * mapped with pci_p2pdma_map_sg()
> > * @dev: device doing the DMA request
> > * @sg: scatter list to map
> > diff --git a/drivers/pci/pci-driver.c b/drivers/pci/pci-driver.c
> > index 8b587fc97f7b..591ab353844a 100644
> > --- a/drivers/pci/pci-driver.c
> > +++ b/drivers/pci/pci-driver.c
> > @@ -90,7 +90,7 @@ static void pci_free_dynids(struct pci_driver *drv)
> > }
> >
> > /**
> > - * store_new_id - sysfs frontend to pci_add_dynid()
> > + * new_id_store - sysfs frontend to pci_add_dynid()
> > * @driver: target device driver
> > * @buf: buffer for scanning device ID data
> > * @count: input size
> > @@ -158,7 +158,7 @@ static ssize_t new_id_store(struct device_driver *driver, const char *buf,
> > static DRIVER_ATTR_WO(new_id);
> >
> > /**
> > - * store_remove_id - remove a PCI device ID from this driver
> > + * remove_id_store - remove a PCI device ID from this driver
> > * @driver: target device driver
> > * @buf: buffer for scanning device ID data
> > * @count: input size
> > diff --git a/drivers/pci/pci.c b/drivers/pci/pci.c
> > index 6d4d5a2f923d..8b9bea8ba751 100644
> > --- a/drivers/pci/pci.c
> > +++ b/drivers/pci/pci.c
> > @@ -3480,7 +3480,7 @@ bool pci_acs_enabled(struct pci_dev *pdev, u16 acs_flags)
> > }
> >
> > /**
> > - * pci_acs_path_enable - test ACS flags from start to end in a hierarchy
> > + * pci_acs_path_enabled - test ACS flags from start to end in a hierarchy
> > * @start: starting downstream device
> > * @end: ending upstream device or NULL to search to the root bus
> > * @acs_flags: required flags
> > diff --git a/drivers/pci/probe.c b/drivers/pci/probe.c
> > index 4289030b0fff..eb1ec037f9e7 100644
> > --- a/drivers/pci/probe.c
> > +++ b/drivers/pci/probe.c
> > @@ -165,7 +165,7 @@ static inline unsigned long decode_bar(struct pci_dev *dev, u32 bar)
> > #define PCI_COMMAND_DECODE_ENABLE (PCI_COMMAND_MEMORY | PCI_COMMAND_IO)
> >
> > /**
> > - * pci_read_base - Read a PCI BAR
> > + * __pci_read_base - Read a PCI BAR
> > * @dev: the PCI device
> > * @type: type of the BAR
> > * @res: resource buffer to be filled in
> > @@ -1612,7 +1612,7 @@ static bool pci_ext_cfg_is_aliased(struct pci_dev *dev)
> > }
> >
> > /**
> > - * pci_cfg_space_size - Get the configuration space size of the PCI device
> > + * pci_cfg_space_size_ext - Get the configuration space size of the PCI device
> > * @dev: PCI device
> > *
> > * Regular PCI devices have 256 bytes, but PCI-X 2 and PCI Express devices
> > diff --git a/drivers/pci/slot.c b/drivers/pci/slot.c
> > index 3861505741e6..bcc8b12ce5da 100644
> > --- a/drivers/pci/slot.c
> > +++ b/drivers/pci/slot.c
> > @@ -323,7 +323,7 @@ EXPORT_SYMBOL_GPL(pci_destroy_slot);
> > #if defined(CONFIG_HOTPLUG_PCI) || defined(CONFIG_HOTPLUG_PCI_MODULE)
> > #include <linux/pci_hotplug.h>
> > /**
> > - * pci_hp_create_link - create symbolic link to the hotplug driver module.
> > + * pci_hp_create_module_link - create symbolic link to the hotplug driver module.
> > * @pci_slot: struct pci_slot
> > *
> > * Helper function for pci_hotplug_core.c to create symbolic link to
> > @@ -349,7 +349,8 @@ void pci_hp_create_module_link(struct pci_slot *pci_slot)
> > EXPORT_SYMBOL_GPL(pci_hp_create_module_link);
> >
> > /**
> > - * pci_hp_remove_link - remove symbolic link to the hotplug driver module.
> > + * pci_hp_remove_module_link - remove symbolic link to the hotplug driver
> > + * module.
> > * @pci_slot: struct pci_slot
> > *
> > * Helper function for pci_hotplug_core.c to remove symbolic link to
> > --
> > 2.26.2
> >
Thanks,
Mauro
Em Fri, 23 Oct 2020 11:22:26 -0600
Jonathan Corbet <[email protected]> escreveu:
> On Fri, 23 Oct 2020 18:32:48 +0200
> Mauro Carvalho Chehab <[email protected]> wrote:
>
> > The include/linux/genalloc.h file defined this typedef:
> >
> > typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
> >
> > Because it has a type composite of two words (unsigned long),
> > the parser gets the typedef name wrong:
> >
> > .. c:macro:: long
> >
> > **Typedef**: Allocation callback function type definition
> >
> > Fix the regex in order to accept composite types when
> > defining a typedef for a function pointer.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> > scripts/kernel-doc | 2 +-
> > 1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index 99cd8418ff8a..311d213ee74d 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -1438,7 +1438,7 @@ sub dump_typedef($$) {
> > $x =~ s@/\*.*?\*/@@gos; # strip comments.
> >
> > # Parse function prototypes
> > - if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > + if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
>
> I sure wish we could find a way to make all these regexes more
> understandable and maintainable. Reviewing a change like this is ... fun.
Yeah. Regexes can be take a while to check. Btw, there's a site that
is really cool to check things:
https://regex101.com/
Unfortunately, it doesn't support Perl flavor. So, you may still
need to double-check if Perl will handle the regex the same way[1].
[1] One of the differences I found is with regards to match repetitions
https://perldoc.perl.org/perlrequick#Matching-repetitions
This works on both Python and Perl:
(foo){0,2}
But this only works on Python:
(foo){,2}
>
> Anyway, it seems to work, but it does now include trailing whitespace in
> the type portion. So, for example, from include/linux/xarray.h:
>
> typedef void (*xa_update_node_t)(struct xa_node *node);
>
> The type is parsed as "void " where it was "void" before. The only ill
> effect I can see is that some non-breaking spaces get inserted into the
> HTML output, but perhaps it's worth stripping off that trailing space
> anyway?
Ok, I'll work on a second version addressing it.
Thanks,
Mauro
Thanks Mauro, small fix for iser
On 10/23/2020 7:33 PM, Mauro Carvalho Chehab wrote:
> Some functions have different names between their prototypes
> and the kernel-doc markup.
>
> Others need to be fixed, as kernel-doc markups should use this format:
> identifier - description
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>
> diff --git a/drivers/infiniband/ulp/iser/iscsi_iser.c b/drivers/infiniband/ulp/iser/iscsi_iser.c
> index 3690e28cc7ea..84cebf937680 100644
> --- a/drivers/infiniband/ulp/iser/iscsi_iser.c
> +++ b/drivers/infiniband/ulp/iser/iscsi_iser.c
> @@ -739,7 +739,7 @@ iscsi_iser_set_param(struct iscsi_cls_conn *cls_conn,
> }
>
> /**
> - * iscsi_iser_set_param() - set class connection parameter
> + * iscsi_iser_conn_get_stats() - set class connection parameter
iscsi_iser_conn_get_stats() - get iscsi connection statistics
> * @cls_conn: iscsi class connection
> * @stats: iscsi stats to output
> *
>
On Fri, Oct 23, 2020 at 06:33:34PM +0200, Mauro Carvalho Chehab wrote:
> Some identifiers have different names between their prototypes
> and the kernel-doc markup.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Acked-by: Mike Rapoport <[email protected]>
> ---
> include/linux/memblock.h | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/include/linux/memblock.h b/include/linux/memblock.h
> index ef131255cedc..95fe3cb71c54 100644
> --- a/include/linux/memblock.h
> +++ b/include/linux/memblock.h
> @@ -272,7 +272,7 @@ void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone,
> unsigned long *out_spfn,
> unsigned long *out_epfn);
> /**
> - * for_each_free_mem_range_in_zone - iterate through zone specific free
> + * for_each_free_mem_pfn_range_in_zone - iterate through zone specific free
> * memblock areas
> * @i: u64 used as loop variable
> * @zone: zone in which all of the memory blocks reside
> @@ -292,7 +292,7 @@ void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone,
> __next_mem_pfn_range_in_zone(&i, zone, p_start, p_end))
>
> /**
> - * for_each_free_mem_range_in_zone_from - iterate through zone specific
> + * for_each_free_mem_pfn_range_in_zone_from - iterate through zone specific
> * free memblock areas from a given point
> * @i: u64 used as loop variable
> * @zone: zone in which all of the memory blocks reside
> --
> 2.26.2
>
--
Sincerely yours,
Mike.
On Fri, Oct 23, 2020 at 12:33 PM Mauro Carvalho Chehab
<[email protected]> wrote:
>
> typo:
> kauditd_print_skb -> kauditd_printk_skb
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> kernel/audit.c | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
Looks good to me, nice catch. Would you like me to pull this into the
audit tree or are you intending this to get pulled in as part of the
larger patchset somewhere else?
Acked-by: Paul Moore <[email protected]>
> diff --git a/kernel/audit.c b/kernel/audit.c
> index 68cee3bc8cfe..0be42cac086b 100644
> --- a/kernel/audit.c
> +++ b/kernel/audit.c
> @@ -523,7 +523,7 @@ static int auditd_set(struct pid *pid, u32 portid, struct net *net)
> }
>
> /**
> - * kauditd_print_skb - Print the audit record to the ring buffer
> + * kauditd_printk_skb - Print the audit record to the ring buffer
> * @skb: audit record
> *
> * Whatever the reason, this packet may not make it to the auditd connection
> --
> 2.26.2
--
paul moore
http://www.paul-moore.com
Em Sun, 25 Oct 2020 18:10:44 -0400
Paul Moore <[email protected]> escreveu:
> On Fri, Oct 23, 2020 at 12:33 PM Mauro Carvalho Chehab
> <[email protected]> wrote:
> >
> > typo:
> > kauditd_print_skb -> kauditd_printk_skb
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> > kernel/audit.c | 2 +-
> > 1 file changed, 1 insertion(+), 1 deletion(-)
>
> Looks good to me, nice catch. Would you like me to pull this into the
> audit tree or are you intending this to get pulled in as part of the
> larger patchset somewhere else?
Feel free to apply it directly via audit tree.
>
> Acked-by: Paul Moore <[email protected]>
Thanks!
Mauro
>
> > diff --git a/kernel/audit.c b/kernel/audit.c
> > index 68cee3bc8cfe..0be42cac086b 100644
> > --- a/kernel/audit.c
> > +++ b/kernel/audit.c
> > @@ -523,7 +523,7 @@ static int auditd_set(struct pid *pid, u32 portid, struct net *net)
> > }
> >
> > /**
> > - * kauditd_print_skb - Print the audit record to the ring buffer
> > + * kauditd_printk_skb - Print the audit record to the ring buffer
> > * @skb: audit record
> > *
> > * Whatever the reason, this packet may not make it to the auditd connection
> > --
> > 2.26.2
>
Thanks,
Mauro
Em Fri, 23 Oct 2020 11:22:26 -0600
Jonathan Corbet <[email protected]> escreveu:
> On Fri, 23 Oct 2020 18:32:48 +0200
> Mauro Carvalho Chehab <[email protected]> wrote:
>
> > The include/linux/genalloc.h file defined this typedef:
> >
> > typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
> >
> > Because it has a type composite of two words (unsigned long),
> > the parser gets the typedef name wrong:
> >
> > .. c:macro:: long
> >
> > **Typedef**: Allocation callback function type definition
> >
> > Fix the regex in order to accept composite types when
> > defining a typedef for a function pointer.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> > scripts/kernel-doc | 2 +-
> > 1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index 99cd8418ff8a..311d213ee74d 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -1438,7 +1438,7 @@ sub dump_typedef($$) {
> > $x =~ s@/\*.*?\*/@@gos; # strip comments.
> >
> > # Parse function prototypes
> > - if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > + if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
>
> I sure wish we could find a way to make all these regexes more
> understandable and maintainable. Reviewing a change like this is ... fun.
>
> Anyway, it seems to work, but it does now include trailing whitespace in
> the type portion. So, for example, from include/linux/xarray.h:
>
> typedef void (*xa_update_node_t)(struct xa_node *node);
>
> The type is parsed as "void " where it was "void" before. The only ill
> effect I can see is that some non-breaking spaces get inserted into the
> HTML output, but perhaps it's worth stripping off that trailing space
> anyway?
Yeah, this is one of the issues. There's another one, tough. While
the above regex recognizes the typedef identifier, it only gets
the last word of "unsigned long", in the case of something like:
typedef unsigned long (*genpool_algo_t)(unsigned long *map);
Here, we have no option but to use a hidden group, e. g. using
this regex:
typedef\s+((?:\w+\s*){1,})\(\*\s*(\w\S+)\s*\)\s*\((.*)\);
I'm enclosing a second version with the above.
Yeah, reviewing it is even funnier, but regex101 can be used to
double-check what the regex is doing:
https://regex101.com/r/bPTm18/2
Thanks,
Mauro
[PATCH] scripts: kernel-doc: fix typedef parsing
The include/linux/genalloc.h file defined this typedef:
typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
Because it has a type composite of two words (unsigned long),
the parser gets the typedef name wrong:
.. c:macro:: long
**Typedef**: Allocation callback function type definition
Fix the regex in order to accept composite types when
defining a typedef for a function pointer.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..b37f3cf8a331 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1438,13 +1438,14 @@ sub dump_typedef($$) {
$x =~ s@/\*.*?\*/@@gos; # strip comments.
# Parse function prototypes
- if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+ if ($x =~ /typedef\s+((?:\w+\s*){1,})\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
# Function typedefs
$return_type = $1;
$declaration_name = $2;
my $args = $3;
+ $return_type =~ s/\s+$//;
create_parameterlist($args, ',', $file, $declaration_name);
Em Fri, 23 Oct 2020 11:01:35 -0700
Joe Perches <[email protected]> escreveu:
> On Fri, 2020-10-23 at 11:22 -0600, Jonathan Corbet wrote:
> > On Fri, 23 Oct 2020 18:32:48 +0200
> > Mauro Carvalho Chehab <[email protected]> wrote:
> >
> > > The include/linux/genalloc.h file defined this typedef:
> > >
> > > typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
> []
> > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> []
> > > # Parse function prototypes
> > > - if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > > + if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> >
> > I sure wish we could find a way to make all these regexes more
> > understandable and maintainable. Reviewing a change like this is ... fun.
>
> Perhaps using some of the checkpatch regex definitions like:
>
> $Type
> $Ident
> $balanced_parens
>
> would help improve readability.
Well, this can help:
my $typedef_type = qr { ((?:\w+\s+){1,}) }x;
my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
my $typedef_args = qr { \s*\((.*)\); }x;
my $typedef1 = qr { typedef\s+$typedef_type\($typedef_ident\)$typedef_args }x;
my $typedef2 = qr { typedef\s+$typedef_type$typedef_ident$typedef_args }x;
# Parse function typedef prototypes
if ($x =~ $typedef1 || $x =~ $typedef2) {
...
But, IMHO, this is as complicated as before, and makes harder
to test the regex outside kernel_doc (like using regex101).
A good thing is that it is easier to see the difference between
the two typedef regexes.
I'll place such optimization on a separate patch. This way, it
should be easier to decide later if this is worth or not.
Also, if we're willing to take such direction, it could make
sense to use the same regexes for matching type, identifier
and arguments inside the functions parser.
> And the regex above doesn't quite work for spacing after typedef.
> The regex should allow space between the open parenthesis and the *
>
> typedef <Type> ( * <Ident> ) (args...);
>
> And this regex does not find typedefs that use another typedef as <Ident> like:
>
> arch/s390/include/asm/debug.h:typedef int (debug_header_proc_t) (debug_info_t *id,
True. I guess that, in order to properly handle it, we should use this:
if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
$x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {
The first check should now parse everything properly:
https://regex101.com/r/bPTm18/5
And the second regex should also get multi-word types when parenthesis
is not used, like:
typedef unsigned int debug_header_proc_t (debug_info_t *id, struct debug_view *view, int area,debug_entry_t *entry, char *out_buf);
typedef unsigned int *debug_header_proc_t (debug_info_t *id, struct debug_view *view, int area,debug_entry_t *entry, char *out_buf);
https://regex101.com/r/Y56X1X/1
Thanks,
Mauro
[PATCH] scripts: kernel-doc: fix typedef parsing
The include/linux/genalloc.h file defined this typedef:
typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
Because it has a type composite of two words (unsigned long),
the parser gets the typedef name wrong:
.. c:macro:: long
**Typedef**: Allocation callback function type definition
Fix the regex in order to accept composite types when
defining a typedef for a function pointer.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..54832618eea0 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1438,13 +1438,14 @@ sub dump_typedef($$) {
$x =~ s@/\*.*?\*/@@gos; # strip comments.
# Parse function prototypes
- if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
- $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
+ if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+ $x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {
# Function typedefs
$return_type = $1;
$declaration_name = $2;
my $args = $3;
+ $return_type =~ s/\s+$//;
create_parameterlist($args, ',', $file, $declaration_name);
On Sat, Oct 24, 2020 at 08:28:27AM +0200, Mauro Carvalho Chehab wrote:
> If the intent is to document the struct and its internal fields,
> this kernel-doc should work:
>
> /**
> * struct refcount_struct - variant of atomic_t specialized for reference counts
> * @refs: atomic_t counter field
> *
> * The counter saturates at REFCOUNT_SATURATED and will not move once
> * there. This avoids wrapping the counter and causing 'spurious'
> * use-after-free bugs.
> */
>
> Which produces this result:
Who cares... :-(
> If you want both, then you would either split struct and typedef, e. g.
> with something like:
>
> /**
> * struct refcount_struct - variant of atomic_t specialized for reference counts
> * @refs: atomic_t counter field
> *
> * The counter saturates at REFCOUNT_SATURATED and will not move once
> * there. This avoids wrapping the counter and causing 'spurious'
> * use-after-free bugs.
> */
> struct refcount_struct {
> atomic_t refs;
> };
>
> /**
> * typedef refcount_t - variant of atomic_t specialized for reference counts
> * @refs: atomic_t counter field
> *
> * The counter saturates at REFCOUNT_SATURATED and will not move once
> * there. This avoids wrapping the counter and causing 'spurious'
> * use-after-free bugs.
> */
> typedef struct refcount_struct refcount_t;
>
> Or, you could add the member at the description field. E. g. something
> like this:
>
> /**
> * typedef refcount_t - variant of atomic_t specialized for reference counts
> *
> * The counter saturates at REFCOUNT_SATURATED and will not move once
> * there. This avoids wrapping the counter and causing 'spurious'
> * use-after-free bugs.
> *
> * Members:
> * ``refs``
> * atomic_t counter field
> */
> typedef struct refcount_struct {
> atomic_t refs;
> } refcount_t;
>
> If you want to test it, you can run kernel-doc directly, to see how
> it will parse it. For ReST output, that's the syntax:
>
> ./scripts/kernel-doc --sphinx-version 3 include/linux/refcount.h
I'll just go ahead and remove the superfluous * from the comment... It's
trivially clear what is meant. If the stupid tool can't deal with that,
I don't care.
All this wanking about docs and making perfectly fine comments bloody
unreadable shit has to stop.
Em Mon, 26 Oct 2020 09:10:59 +0100
Peter Zijlstra <[email protected]> escreveu:
> On Sat, Oct 24, 2020 at 08:28:27AM +0200, Mauro Carvalho Chehab wrote:
> > If the intent is to document the struct and its internal fields,
> > this kernel-doc should work:
> >
> > /**
> > * struct refcount_struct - variant of atomic_t specialized for reference counts
> > * @refs: atomic_t counter field
> > *
> > * The counter saturates at REFCOUNT_SATURATED and will not move once
> > * there. This avoids wrapping the counter and causing 'spurious'
> > * use-after-free bugs.
> > */
> >
> > Which produces this result:
>
> Who cares... :-(
Anyone that would need to use refcount_t, instead of atomic_t.
>
> > If you want both, then you would either split struct and typedef, e. g.
> > with something like:
> >
> > /**
> > * struct refcount_struct - variant of atomic_t specialized for reference counts
> > * @refs: atomic_t counter field
> > *
> > * The counter saturates at REFCOUNT_SATURATED and will not move once
> > * there. This avoids wrapping the counter and causing 'spurious'
> > * use-after-free bugs.
> > */
> > struct refcount_struct {
> > atomic_t refs;
> > };
> >
> > /**
> > * typedef refcount_t - variant of atomic_t specialized for reference counts
> > * @refs: atomic_t counter field
> > *
> > * The counter saturates at REFCOUNT_SATURATED and will not move once
> > * there. This avoids wrapping the counter and causing 'spurious'
> > * use-after-free bugs.
> > */
> > typedef struct refcount_struct refcount_t;
> >
> > Or, you could add the member at the description field. E. g. something
> > like this:
> >
> > /**
> > * typedef refcount_t - variant of atomic_t specialized for reference counts
> > *
> > * The counter saturates at REFCOUNT_SATURATED and will not move once
> > * there. This avoids wrapping the counter and causing 'spurious'
> > * use-after-free bugs.
> > *
> > * Members:
> > * ``refs``
> > * atomic_t counter field
> > */
> > typedef struct refcount_struct {
> > atomic_t refs;
> > } refcount_t;
> >
> > If you want to test it, you can run kernel-doc directly, to see how
> > it will parse it. For ReST output, that's the syntax:
> >
> > ./scripts/kernel-doc --sphinx-version 3 include/linux/refcount.h
>
> I'll just go ahead and remove the superfluous * from the comment... It's
> trivially clear what is meant. If the stupid tool can't deal with that,
> I don't care.
The tool is not that stupid. What's wrong here is that the markup is
asking kernel-doc to document the struct, instead documenting the typedef:
/**
* struct refcount_t - variant of atomic_t specialized for reference counts
...
There is no such struct!
Just doing:
s/struct/typedef/
will do what you intend to document.
Thanks,
Mauro
[PATCH] refcount.h: fix a kernel-doc markup
The kernel-doc markup is wrong: it is asking the tool to document
struct refcount_struct, instead of documenting typedef refcount_t.
Fix it.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
diff --git a/include/linux/refcount.h b/include/linux/refcount.h
index 0e3ee25eb156..f572c62261a8 100644
--- a/include/linux/refcount.h
+++ b/include/linux/refcount.h
@@ -101,7 +101,7 @@
struct mutex;
/**
- * struct refcount_t - variant of atomic_t specialized for reference counts
+ * typedef refcount_t - variant of atomic_t specialized for reference counts
* @refs: atomic_t counter field
*
* The counter saturates at REFCOUNT_SATURATED and will not move once
On Mon, Oct 26, 2020 at 10:16:20AM +0100, Mauro Carvalho Chehab wrote:
> Em Mon, 26 Oct 2020 09:10:59 +0100
> Peter Zijlstra <[email protected]> escreveu:
>
> > On Sat, Oct 24, 2020 at 08:28:27AM +0200, Mauro Carvalho Chehab wrote:
> > > If the intent is to document the struct and its internal fields,
> > > this kernel-doc should work:
> > >
> > > /**
> > > * struct refcount_struct - variant of atomic_t specialized for reference counts
> > > * @refs: atomic_t counter field
> > > *
> > > * The counter saturates at REFCOUNT_SATURATED and will not move once
> > > * there. This avoids wrapping the counter and causing 'spurious'
> > > * use-after-free bugs.
> > > */
> > >
> > > Which produces this result:
> >
> > Who cares... :-(
>
> Anyone that would need to use refcount_t, instead of atomic_t.
They can read the .h file just fine today.
On Fri, 23 Oct 2020 18:33:35 +0200,
Mauro Carvalho Chehab wrote:
>
> Kernel-doc markups should use this format:
> identifier - description
>
> There is a common comment marked, instead, with kernel-doc
> notation.
>
> Some identifiers have different names between their prototypes
> and the kernel-doc markup.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Shall I merge this through sound git tree?
Or if this goes via doc tree, feel free to take my ack
Reviewed-by: Takashi Iwai <[email protected]>
thanks,
Takashi
Em Mon, 26 Oct 2020 14:46:03 +0100
Takashi Iwai <[email protected]> escreveu:
> On Fri, 23 Oct 2020 18:33:35 +0200,
> Mauro Carvalho Chehab wrote:
> >
> > Kernel-doc markups should use this format:
> > identifier - description
> >
> > There is a common comment marked, instead, with kernel-doc
> > notation.
> >
> > Some identifiers have different names between their prototypes
> > and the kernel-doc markup.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>
> Shall I merge this through sound git tree?
>
> Or if this goes via doc tree, feel free to take my ack
> Reviewed-by: Takashi Iwai <[email protected]>
Thanks for reviewing it!
Feel free to merge it though sound tree.
Thanks,
Mauro
On Mon, 26 Oct 2020 15:14:23 +0100,
Mauro Carvalho Chehab wrote:
>
> Em Mon, 26 Oct 2020 14:46:03 +0100
> Takashi Iwai <[email protected]> escreveu:
>
> > On Fri, 23 Oct 2020 18:33:35 +0200,
> > Mauro Carvalho Chehab wrote:
> > >
> > > Kernel-doc markups should use this format:
> > > identifier - description
> > >
> > > There is a common comment marked, instead, with kernel-doc
> > > notation.
> > >
> > > Some identifiers have different names between their prototypes
> > > and the kernel-doc markup.
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> >
> > Shall I merge this through sound git tree?
> >
> > Or if this goes via doc tree, feel free to take my ack
> > Reviewed-by: Takashi Iwai <[email protected]>
>
> Thanks for reviewing it!
>
> Feel free to merge it though sound tree.
OK, applied now. Thanks!
Takashi
On 23/10/2020 17:33, Mauro Carvalho Chehab wrote:
> Fix the name of the enum on its kernel-doc markup:
> enum slim_ch_aux_fmt -> enum slim_ch_aux_bit_fmt
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> drivers/slimbus/slimbus.h | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/drivers/slimbus/slimbus.h b/drivers/slimbus/slimbus.h
> index c73035915f1d..00a7f112574b 100644
> --- a/drivers/slimbus/slimbus.h
> +++ b/drivers/slimbus/slimbus.h
> @@ -244,7 +244,7 @@ enum slim_ch_data_fmt {
> };
>
> /**
> - * enum slim_ch_aux_fmt: SLIMbus channel Aux Field format IDs according to
> + * enum slim_ch_aux_bit_fmt: SLIMbus channel Aux Field format IDs according to
> * Table 63 of SLIMbus Spec 2.0
> * @SLIM_CH_AUX_FMT_NOT_APPLICABLE: Undefined
> * @SLIM_CH_AUX_FMT_ZCUV_TUNNEL_IEC60958: ZCUV for tunneling IEC60958
>
Applied thanks!
srini
On Fri, 2020-10-23 at 18:33 +0200, Mauro Carvalho Chehab wrote:
> locks_delete_lock -> locks_delete_block
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> fs/locks.c | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/fs/locks.c b/fs/locks.c
> index 1f84a03601fe..f3c3ce82a455 100644
> --- a/fs/locks.c
> +++ b/fs/locks.c
> @@ -750,7 +750,7 @@ static void __locks_wake_up_blocks(struct file_lock *blocker)
> }
>
> /**
> - * locks_delete_lock - stop waiting for a file lock
> + * locks_delete_block - stop waiting for a file lock
> * @waiter: the lock which was waiting
> *
> * lockd/nfsd need to disconnect the lock while working on it.
Thanks, merged. Should make 5.11.
Cheers,
--
Jeff Layton <[email protected]>
Em Mon, 26 Oct 2020 20:55:35 -0700
Joe Perches <[email protected]> escreveu:
> On Mon, 2020-10-26 at 08:03 +0100, Mauro Carvalho Chehab wrote:
> []
> > Well, this can help:
> > my $typedef_type = qr { ((?:\w+\s+){1,}) }x;
>
> unbounded captures are generally bad, I suggest a limit like {1,5}
Ok. 5 is likely too low, if "*" starts to be counted as part of the type.
Maybe 8 would be ok.
>
> > if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > $x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {
> []
> > Fix the regex in order to accept composite types when
> > defining a typedef for a function pointer.
> []
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> []
> > @@ -1438,13 +1438,14 @@ sub dump_typedef($$) {
> > $x =~ s@/\*.*?\*/@@gos; # strip comments.
> >
> >
> > # Parse function prototypes
> > - if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > - $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
> > + if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > + $x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {
>
> This typedef does not allow * returns like
>
> const unsigned char *(*string)(args...);
> or
> unsigned char *const(*fn)(args...);
> or
> void *(*alloc)(args...);
Supporting those shouldn't be hard. See enclosed.
>
> (not to mention the truly unusual stuff like the typedefs in
> tools/testing/selftests/bpf/progs/btf_dump_test_case_syntax.c)
>
> typedef void (* (*signal_t)(int, void (*)(int)))(int);
> typedef char * (*fn_ptr_arr1_t[10])(int **);
> typedef char * (* const (* const fn_ptr_arr2_t[5])())(char * (*)(int));
Parsing those using a single regex, though, is a lot more complex.
The logic would likely require some loop or a real lexical
analyzer in order to properly parse it.
In the specific case of userspace tools (and, in special, selftests),
it is probably not worth the effort to add support for C expressions
that only exists there, as those won't likely gain kernel-doc entries
for their source code to become part of the Kernel documentation.
Thanks,
Mauro
[PATH] scripts: kernel-doc: fix typedef parsing
The include/linux/genalloc.h file defined this typedef:
typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
Because it has a type composite of two words (unsigned long),
the parser gets the typedef name wrong:
.. c:macro:: long
**Typedef**: Allocation callback function type definition
Fix the regex in order to accept composite types when
defining a typedef for a function pointer.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..f699cf05d409 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1431,20 +1431,25 @@ sub dump_enum($$) {
}
}
+my $typedef_type = qr { ((?:\s+[\w\*]+){1,8})\s* }x;
+my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
+my $typedef_args = qr { \s*\((.*)\); }x;
+
+my $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x;
+my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x;
+
sub dump_typedef($$) {
my $x = shift;
my $file = shift;
$x =~ s@/\*.*?\*/@@gos; # strip comments.
- # Parse function prototypes
- if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
- $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
-
- # Function typedefs
+ # Parse function typedef prototypes
+ if ($x =~ $typedef1 || $x =~ $typedef2) {
$return_type = $1;
$declaration_name = $2;
my $args = $3;
+ $return_type =~ s/^\s+//;
create_parameterlist($args, ',', $file, $declaration_name);
On Mon, 2020-10-26 at 08:03 +0100, Mauro Carvalho Chehab wrote:
[]
> Well, this can help:
> my $typedef_type = qr { ((?:\w+\s+){1,}) }x;
unbounded captures are generally bad, I suggest a limit like {1,5}
> ????if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> $x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {
[]
> Fix the regex in order to accept composite types when
> defining a typedef for a function pointer.
[]
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
[]
> @@ -1438,13 +1438,14 @@ sub dump_typedef($$) {
> ?????$x =~ s@/\*.*?\*/@@gos; # strip comments.
> ?
>
> ?????# Parse function prototypes
> - if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> - $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
> + if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> + $x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {
This typedef does not allow * returns?like
const unsigned char *(*string)(args...);
or
unsigned char *const(*fn)(args...);
or
void *(*alloc)(args...);
(not to mention the truly unusual stuff like the typedefs in
tools/testing/selftests/bpf/progs/btf_dump_test_case_syntax.c)
typedef void (* (*signal_t)(int, void (*)(int)))(int);
typedef char * (*fn_ptr_arr1_t[10])(int **);
typedef char * (* const (* const fn_ptr_arr2_t[5])())(char * (*)(int));
Hi Mauro,
Mauro Carvalho Chehab <[email protected]> writes:
> There is a common comment marked, instead, with kernel-doc
> notation.
>
> Also, some identifiers have different names between their
> prototypes and the kernel-doc markup.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> drivers/usb/dwc3/core.c | 2 +-
> drivers/usb/dwc3/core.h | 2 +-
> drivers/usb/gadget/composite.c | 2 +-
> drivers/usb/typec/mux.c | 2 +-
> include/linux/usb/composite.h | 2 +-
mind breaking this into 4 commits? One for dwc3, one for
gadget/composite, one for type/mux, and a final for composite.h.
--
balbi
Acked-by: Richard Gong <[email protected]>
On 10/23/20 11:33 AM, Mauro Carvalho Chehab wrote:
> There are some common comments marked, instead, with kernel-doc
> notation, which won't work.
>
> While here, rename an identifier, in order to match the
> function prototype below kernel-doc markup.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> include/linux/firmware/intel/stratix10-svc-client.h | 10 +++++-----
> 1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/include/linux/firmware/intel/stratix10-svc-client.h b/include/linux/firmware/intel/stratix10-svc-client.h
> index a93d85932eb9..ebc295647581 100644
> --- a/include/linux/firmware/intel/stratix10-svc-client.h
> +++ b/include/linux/firmware/intel/stratix10-svc-client.h
> @@ -6,7 +6,7 @@
> #ifndef __STRATIX10_SVC_CLIENT_H
> #define __STRATIX10_SVC_CLIENT_H
>
> -/**
> +/*
> * Service layer driver supports client names
> *
> * fpga: for FPGA configuration
> @@ -15,7 +15,7 @@
> #define SVC_CLIENT_FPGA "fpga"
> #define SVC_CLIENT_RSU "rsu"
>
> -/**
> +/*
> * Status of the sent command, in bit number
> *
> * SVC_STATUS_OK:
> @@ -50,7 +50,7 @@
> #define SVC_STATUS_ERROR 5
> #define SVC_STATUS_NO_SUPPORT 6
>
> -/**
> +/*
> * Flag bit for COMMAND_RECONFIG
> *
> * COMMAND_RECONFIG_FLAG_PARTIAL:
> @@ -58,7 +58,7 @@
> */
> #define COMMAND_RECONFIG_FLAG_PARTIAL 1
>
> -/**
> +/*
> * Timeout settings for service clients:
> * timeout value used in Stratix10 FPGA manager driver.
> * timeout value used in RSU driver
> @@ -218,7 +218,7 @@ void stratix10_svc_free_memory(struct stratix10_svc_chan *chan, void *kaddr);
> int stratix10_svc_send(struct stratix10_svc_chan *chan, void *msg);
>
> /**
> - * intel_svc_done() - complete service request
> + * stratix10_svc_done() - complete service request
> * @chan: service channel assigned to the client
> *
> * This function is used by service client to inform service layer that
>
On Fri, Oct 23, 2020 at 6:38 PM Mauro Carvalho Chehab
<[email protected]> wrote:
>
> It sounds that there were function renames. Update the kernel-doc
> markups accordingly.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> drivers/pnp/core.c | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/drivers/pnp/core.c b/drivers/pnp/core.c
> index 3bf18d718975..a50ab002e9e4 100644
> --- a/drivers/pnp/core.c
> +++ b/drivers/pnp/core.c
> @@ -51,7 +51,7 @@ static void pnp_remove_protocol(struct pnp_protocol *protocol)
> }
>
> /**
> - * pnp_protocol_register - adds a pnp protocol to the pnp layer
> + * pnp_register_protocol - adds a pnp protocol to the pnp layer
> * @protocol: pointer to the corresponding pnp_protocol structure
> *
> * Ex protocols: ISAPNP, PNPBIOS, etc
> @@ -91,7 +91,7 @@ int pnp_register_protocol(struct pnp_protocol *protocol)
> }
>
> /**
> - * pnp_protocol_unregister - removes a pnp protocol from the pnp layer
> + * pnp_unregister_protocol - removes a pnp protocol from the pnp layer
> * @protocol: pointer to the corresponding pnp_protocol structure
> */
> void pnp_unregister_protocol(struct pnp_protocol *protocol)
> --
Applied as 5.10-rc material, thanks!
On Sun, Oct 25, 2020 at 6:38 PM Mauro Carvalho Chehab
<[email protected]> wrote:
> Em Sun, 25 Oct 2020 18:10:44 -0400
> Paul Moore <[email protected]> escreveu:
>
> > On Fri, Oct 23, 2020 at 12:33 PM Mauro Carvalho Chehab
> > <[email protected]> wrote:
> > >
> > > typo:
> > > kauditd_print_skb -> kauditd_printk_skb
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > > ---
> > > kernel/audit.c | 2 +-
> > > 1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > Looks good to me, nice catch. Would you like me to pull this into the
> > audit tree or are you intending this to get pulled in as part of the
> > larger patchset somewhere else?
>
> Feel free to apply it directly via audit tree.
I just merged it into audit/next, you should see it shortly. Thanks!
--
paul moore
http://www.paul-moore.com
On Tue, Oct 27, 2020 at 08:58:47AM +0200, Felipe Balbi wrote:
>
> Hi Mauro,
>
> Mauro Carvalho Chehab <[email protected]> writes:
> > There is a common comment marked, instead, with kernel-doc
> > notation.
> >
> > Also, some identifiers have different names between their
> > prototypes and the kernel-doc markup.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> > drivers/usb/dwc3/core.c | 2 +-
> > drivers/usb/dwc3/core.h | 2 +-
> > drivers/usb/gadget/composite.c | 2 +-
> > drivers/usb/typec/mux.c | 2 +-
> > include/linux/usb/composite.h | 2 +-
>
> mind breaking this into 4 commits? One for dwc3, one for
> gadget/composite, one for type/mux, and a final for composite.h.
I'll just take these all at once, it's easy enough :)
thanks,
greg k-h
Greg Kroah-Hartman <[email protected]> writes:
> On Tue, Oct 27, 2020 at 08:58:47AM +0200, Felipe Balbi wrote:
>>
>> Hi Mauro,
>>
>> Mauro Carvalho Chehab <[email protected]> writes:
>> > There is a common comment marked, instead, with kernel-doc
>> > notation.
>> >
>> > Also, some identifiers have different names between their
>> > prototypes and the kernel-doc markup.
>> >
>> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>> > ---
>> > drivers/usb/dwc3/core.c | 2 +-
>> > drivers/usb/dwc3/core.h | 2 +-
>> > drivers/usb/gadget/composite.c | 2 +-
>> > drivers/usb/typec/mux.c | 2 +-
>> > include/linux/usb/composite.h | 2 +-
>>
>> mind breaking this into 4 commits? One for dwc3, one for
>> gadget/composite, one for type/mux, and a final for composite.h.
>
> I'll just take these all at once, it's easy enough :)
Sure thing, in that case:
Acked-by: Felipe Balbi <[email protected]>
--
balbi
On Fri, 23 Oct 2020 18:33:32 +0200
Mauro Carvalho Chehab <[email protected]> wrote:
> A function has a different name between their prototype
> and its kernel-doc markup.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Applied to the togreg branch of iio.git.
Thanks,
Jonathan
> ---
> include/linux/iio/trigger.h | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/include/linux/iio/trigger.h b/include/linux/iio/trigger.h
> index cad8325903f9..f930c4ccf378 100644
> --- a/include/linux/iio/trigger.h
> +++ b/include/linux/iio/trigger.h
> @@ -97,7 +97,7 @@ static inline struct iio_trigger *iio_trigger_get(struct iio_trigger *trig)
> }
>
> /**
> - * iio_device_set_drvdata() - Set trigger driver data
> + * iio_trigger_set_drvdata() - Set trigger driver data
> * @trig: IIO trigger structure
> * @data: Driver specific data
> *
On Fri, 2020-10-23 at 16:33:04 UTC, Mauro Carvalho Chehab wrote:
> Some identifiers have different names between their prototypes
> and the kernel-doc markup.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Applied to https://git.kernel.org/pub/scm/linux/kernel/git/mtd/linux.git nand/next, thanks.
Miquel
On Fri, Oct 23, 2020 at 06:32:57PM +0200, Mauro Carvalho Chehab wrote:
> Kernel-doc markup should use this format:
> identifier - description
>
> Also, some enums are using wrong names at the kernel-doc
> markup.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> drivers/edac/edac_device.h | 11 +++++------
> include/linux/edac.h | 4 ++--
> 2 files changed, 7 insertions(+), 8 deletions(-)
Applied, thanks.
--
Regards/Gruss,
Boris.
https://people.kernel.org/tglx/notes-about-netiquette
Quoting Mauro Carvalho Chehab (2020-10-23 09:33:25)
> clk_get_duty_cycle -> clk_get_scaled_duty_cycle
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
Applied to clk-next
On Fri, Oct 23, 2020 at 06:33:10PM +0200, Mauro Carvalho Chehab wrote:
> Some identifiers have different names between their prototypes
> and the kernel-doc markup.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Applied to pci/misc for v5.11, thanks!
> ---
> drivers/pci/p2pdma.c | 10 +++++-----
> drivers/pci/pci-driver.c | 4 ++--
> drivers/pci/pci.c | 2 +-
> drivers/pci/probe.c | 4 ++--
> drivers/pci/slot.c | 5 +++--
> 5 files changed, 13 insertions(+), 12 deletions(-)
>
> diff --git a/drivers/pci/p2pdma.c b/drivers/pci/p2pdma.c
> index de1c331dbed4..bace04145c5f 100644
> --- a/drivers/pci/p2pdma.c
> +++ b/drivers/pci/p2pdma.c
> @@ -609,7 +609,7 @@ bool pci_has_p2pmem(struct pci_dev *pdev)
> EXPORT_SYMBOL_GPL(pci_has_p2pmem);
>
> /**
> - * pci_p2pmem_find - find a peer-to-peer DMA memory device compatible with
> + * pci_p2pmem_find_many - find a peer-to-peer DMA memory device compatible with
> * the specified list of clients and shortest distance (as determined
> * by pci_p2pmem_dma())
> * @clients: array of devices to check (NULL-terminated)
> @@ -674,7 +674,7 @@ struct pci_dev *pci_p2pmem_find_many(struct device **clients, int num_clients)
> EXPORT_SYMBOL_GPL(pci_p2pmem_find_many);
>
> /**
> - * pci_alloc_p2p_mem - allocate peer-to-peer DMA memory
> + * pci_alloc_p2pmem - allocate peer-to-peer DMA memory
> * @pdev: the device to allocate memory from
> * @size: number of bytes to allocate
> *
> @@ -727,7 +727,7 @@ void pci_free_p2pmem(struct pci_dev *pdev, void *addr, size_t size)
> EXPORT_SYMBOL_GPL(pci_free_p2pmem);
>
> /**
> - * pci_virt_to_bus - return the PCI bus address for a given virtual
> + * pci_p2pmem_virt_to_bus - return the PCI bus address for a given virtual
> * address obtained with pci_alloc_p2pmem()
> * @pdev: the device the memory was allocated from
> * @addr: address of the memory that was allocated
> @@ -859,7 +859,7 @@ static int __pci_p2pdma_map_sg(struct pci_p2pdma_pagemap *p2p_pgmap,
> }
>
> /**
> - * pci_p2pdma_map_sg - map a PCI peer-to-peer scatterlist for DMA
> + * pci_p2pdma_map_sg_attrs - map a PCI peer-to-peer scatterlist for DMA
> * @dev: device doing the DMA request
> * @sg: scatter list to map
> * @nents: elements in the scatterlist
> @@ -896,7 +896,7 @@ int pci_p2pdma_map_sg_attrs(struct device *dev, struct scatterlist *sg,
> EXPORT_SYMBOL_GPL(pci_p2pdma_map_sg_attrs);
>
> /**
> - * pci_p2pdma_unmap_sg - unmap a PCI peer-to-peer scatterlist that was
> + * pci_p2pdma_unmap_sg_attrs - unmap a PCI peer-to-peer scatterlist that was
> * mapped with pci_p2pdma_map_sg()
> * @dev: device doing the DMA request
> * @sg: scatter list to map
> diff --git a/drivers/pci/pci-driver.c b/drivers/pci/pci-driver.c
> index 8b587fc97f7b..591ab353844a 100644
> --- a/drivers/pci/pci-driver.c
> +++ b/drivers/pci/pci-driver.c
> @@ -90,7 +90,7 @@ static void pci_free_dynids(struct pci_driver *drv)
> }
>
> /**
> - * store_new_id - sysfs frontend to pci_add_dynid()
> + * new_id_store - sysfs frontend to pci_add_dynid()
> * @driver: target device driver
> * @buf: buffer for scanning device ID data
> * @count: input size
> @@ -158,7 +158,7 @@ static ssize_t new_id_store(struct device_driver *driver, const char *buf,
> static DRIVER_ATTR_WO(new_id);
>
> /**
> - * store_remove_id - remove a PCI device ID from this driver
> + * remove_id_store - remove a PCI device ID from this driver
> * @driver: target device driver
> * @buf: buffer for scanning device ID data
> * @count: input size
> diff --git a/drivers/pci/pci.c b/drivers/pci/pci.c
> index 6d4d5a2f923d..8b9bea8ba751 100644
> --- a/drivers/pci/pci.c
> +++ b/drivers/pci/pci.c
> @@ -3480,7 +3480,7 @@ bool pci_acs_enabled(struct pci_dev *pdev, u16 acs_flags)
> }
>
> /**
> - * pci_acs_path_enable - test ACS flags from start to end in a hierarchy
> + * pci_acs_path_enabled - test ACS flags from start to end in a hierarchy
> * @start: starting downstream device
> * @end: ending upstream device or NULL to search to the root bus
> * @acs_flags: required flags
> diff --git a/drivers/pci/probe.c b/drivers/pci/probe.c
> index 4289030b0fff..eb1ec037f9e7 100644
> --- a/drivers/pci/probe.c
> +++ b/drivers/pci/probe.c
> @@ -165,7 +165,7 @@ static inline unsigned long decode_bar(struct pci_dev *dev, u32 bar)
> #define PCI_COMMAND_DECODE_ENABLE (PCI_COMMAND_MEMORY | PCI_COMMAND_IO)
>
> /**
> - * pci_read_base - Read a PCI BAR
> + * __pci_read_base - Read a PCI BAR
> * @dev: the PCI device
> * @type: type of the BAR
> * @res: resource buffer to be filled in
> @@ -1612,7 +1612,7 @@ static bool pci_ext_cfg_is_aliased(struct pci_dev *dev)
> }
>
> /**
> - * pci_cfg_space_size - Get the configuration space size of the PCI device
> + * pci_cfg_space_size_ext - Get the configuration space size of the PCI device
> * @dev: PCI device
> *
> * Regular PCI devices have 256 bytes, but PCI-X 2 and PCI Express devices
> diff --git a/drivers/pci/slot.c b/drivers/pci/slot.c
> index 3861505741e6..bcc8b12ce5da 100644
> --- a/drivers/pci/slot.c
> +++ b/drivers/pci/slot.c
> @@ -323,7 +323,7 @@ EXPORT_SYMBOL_GPL(pci_destroy_slot);
> #if defined(CONFIG_HOTPLUG_PCI) || defined(CONFIG_HOTPLUG_PCI_MODULE)
> #include <linux/pci_hotplug.h>
> /**
> - * pci_hp_create_link - create symbolic link to the hotplug driver module.
> + * pci_hp_create_module_link - create symbolic link to the hotplug driver module.
> * @pci_slot: struct pci_slot
> *
> * Helper function for pci_hotplug_core.c to create symbolic link to
> @@ -349,7 +349,8 @@ void pci_hp_create_module_link(struct pci_slot *pci_slot)
> EXPORT_SYMBOL_GPL(pci_hp_create_module_link);
>
> /**
> - * pci_hp_remove_link - remove symbolic link to the hotplug driver module.
> + * pci_hp_remove_module_link - remove symbolic link to the hotplug driver
> + * module.
> * @pci_slot: struct pci_slot
> *
> * Helper function for pci_hotplug_core.c to remove symbolic link to
> --
> 2.26.2
>
On Fri, Oct 23, 2020 at 06:33:43PM +0200, Mauro Carvalho Chehab wrote:
> Kernel-doc currently expects that the kernel-doc markup to come
> just before the function/enum/struct/union/typedef prototype.
>
> Yet, if it find things like:
>
> /**
> * refcount_add - add a value to a refcount
> * @i: the value to add to the refcount
> * @r: the refcount
> */
> static inline void __refcount_add(int i, refcount_t *r, int *oldp);
> static inline void refcount_add(int i, refcount_t *r);
>
> Kernel-doc will do the wrong thing:
I wonder if we could change kernel-doc to be (optionally) less verbose.
If we allowed people to write:
/**
* Add a value to a refcount.
* @i: The value to add to the refcount
* @r: The refcount
*/
and had the kernel-doc script pick up the name of the following function
automatically, would that be an improvement we could all agree on?
On Thu, 5 Nov 2020 15:00:17 +0000
Matthew Wilcox <[email protected]> wrote:
> I wonder if we could change kernel-doc to be (optionally) less verbose.
> If we allowed people to write:
>
> /**
> * Add a value to a refcount.
> * @i: The value to add to the refcount
> * @r: The refcount
> */
>
> and had the kernel-doc script pick up the name of the following function
> automatically, would that be an improvement we could all agree on?
Given the number of issues Mauro just fixed where the comments had become
separated from the functions they documented, this seems potentially
hazardous... It seems especially likely to fail with the "change foo() to
__foo() and add a new foo() down below" pattern that is fairly common.
jon
Em Thu, 5 Nov 2020 15:00:17 +0000
Matthew Wilcox <[email protected]> escreveu:
> On Fri, Oct 23, 2020 at 06:33:43PM +0200, Mauro Carvalho Chehab wrote:
> > Kernel-doc currently expects that the kernel-doc markup to come
> > just before the function/enum/struct/union/typedef prototype.
> >
> > Yet, if it find things like:
> >
> > /**
> > * refcount_add - add a value to a refcount
> > * @i: the value to add to the refcount
> > * @r: the refcount
> > */
> > static inline void __refcount_add(int i, refcount_t *r, int *oldp);
> > static inline void refcount_add(int i, refcount_t *r);
> >
> > Kernel-doc will do the wrong thing:
>
> I wonder if we could change kernel-doc to be (optionally) less verbose.
> If we allowed people to write:
>
> /**
> * Add a value to a refcount.
> * @i: The value to add to the refcount
> * @r: The refcount
> */
>
> and had the kernel-doc script pick up the name of the following function
> automatically, would that be an improvement we could all agree on?
Matthew,
As patches are usually generated with -U3, the context lines are
not enough to show if a comment preceding a function is a kernel-doc
markup or a normal comment.
In practice, on some patches at this series, I found real issues
because something else was added between the kernel-doc markup
and the documented function.
So, for me, it sounds a bad idea to remove the function name, as
this can be used to detect such issues.
Thanks,
Mauro
On Thu, Nov 05, 2020 at 08:15:26AM -0700, Jonathan Corbet wrote:
> On Thu, 5 Nov 2020 15:00:17 +0000
> Matthew Wilcox <[email protected]> wrote:
>
> > I wonder if we could change kernel-doc to be (optionally) less verbose.
> > If we allowed people to write:
> >
> > /**
> > * Add a value to a refcount.
> > * @i: The value to add to the refcount
> > * @r: The refcount
> > */
> >
> > and had the kernel-doc script pick up the name of the following function
> > automatically, would that be an improvement we could all agree on?
>
> Given the number of issues Mauro just fixed where the comments had become
> separated from the functions they documented, this seems potentially
> hazardous... It seems especially likely to fail with the "change foo() to
> __foo() and add a new foo() down below" pattern that is fairly common.
Sort of, yes. The usual case for doing that is where one adds a new
parameter, and kernel-doc will warn about that. But if the parameters
stay the same (eg refcount_add takes a lock and __refcount_add assumes
the lock is already held), then you've got documentation of __refcount_add
and no documentation of refcount_add() ... and it's probably still _true_
documentation, just not as useful.