qcacmn: Fix QDF trace documentation

The kernel-doc script identified documentation issues in the QDF trace
abstractions, so fix those issues. In addition, there are instances
where public functions have their implementation documented instead of
having their interface documented, so move that documentation.

Change-Id: Ife16fe9527dbe013003c5f2f04d7e9d0a9aa385a
CRs-Fixed: 3406201

qdf/linux/src/i_qdf_trace.h

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2014-2021 The Linux Foundation. All rights reserved.
- * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Qualcomm Innovation Center, Inc. All rights reserved.
  *
  * Permission to use, copy, modify, and/or distribute this software for
  * any purpose with or without fee is hereby granted, provided that the
@@ -304,6 +304,7 @@ static inline void __qdf_trace_hexdump_dummy(QDF_MODULE_ID module,
 		} \
 	} while (0)
 #endif /* WLAN_WARN_ON_ASSERT */
+
 /**
  * qdf_trace_msg()- logging API
  * @module: Module identifier. A member of the QDF_MODULE_ID enumeration that
@@ -320,8 +321,6 @@ static inline void __qdf_trace_hexdump_dummy(QDF_MODULE_ID module,
  * tracing is enabled.
  *
  * Return: nothing
- *
- * implemented in qdf_trace.c
  */
 void __printf(3, 4) qdf_trace_msg(QDF_MODULE_ID module, QDF_TRACE_LEVEL level,
 				  const char *str_format, ...);

qdf/linux/src/i_qdf_tracepoint.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021-2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2021-2023 Qualcomm Innovation Center, Inc. All rights reserved.
  *
  * Permission to use, copy, modify, and/or distribute this software for
  * any purpose with or without fee is hereby granted, provided that the
@@ -197,10 +197,10 @@ bool __qdf_trace_dp_tx_comp_generic_ip_pkt_enabled(void)
  * __qdf_trace_dp_tx_comp_generic_ip_pkt() - Trace generic ip packet in
  *					     tx direction
  * @skb: pointer to network buffer
+ * @ip_proto: IP protocol field
  * @ip_id: ip identification field
  * @trans_hdr_4_bytes: transport header first 4 bytes
  * @latency: latency
-
  *
  * Return: None
  */
@@ -217,7 +217,7 @@ void __qdf_trace_dp_tx_comp_generic_ip_pkt(struct sk_buff *skb,
 }
 
 /**
- * __qdf_trace_dp_rx_pkt_enablei() - Get the dp_rx_pkt tracepoint
+ * __qdf_trace_dp_rx_pkt_enabled() - Get the dp_rx_pkt tracepoint
  *  enabled or disabled state
  *
  * Return: True if the tracepoint is enabled else false

qdf/linux/src/qdf_trace.c

@@ -135,16 +135,7 @@ static char qdf_module_param[QDF_PARAM_MAX][QDF_PARAM_STR_LENGTH] = {
 	"qdf_log_flush_timer_period",
 };
 #endif
-/**
- * qdf_snprintf() - wrapper function to snprintf
- * @str_buffer: string Buffer
- * @size: defines the size of the data record
- * @str_format: Format string in which the message to be logged. This format
- * string contains printf-like replacement parameters, which follow
- * this parameter in the variable argument list.
- *
- * Return: num of bytes written to buffer
- */
+
 int qdf_snprintf(char *str_buffer, unsigned int size, char *str_format, ...)
 {
 	va_list args;
@@ -160,21 +151,6 @@ qdf_export_symbol(qdf_snprintf);
 
 #ifdef QDF_ENABLE_TRACING
 
-/**
- * qdf_trace_msg() - externally called trace function
- * @module: Module identifier a member of the QDF_MODULE_ID
- * enumeration that identifies the module issuing the trace message.
- * @level: Trace level a member of the QDF_TRACE_LEVEL enumeration
- * indicating the severity of the condition causing the trace message
- * to be issued. More severe conditions are more likely to be logged.
- * @str_format: Format string in which the message to be logged. This format
- * string contains printf-like replacement parameters, which follow
- * this parameter in the variable argument list.
- *
- * Checks the level of severity and accordingly prints the trace messages
- *
- * Return: None
- */
 void qdf_trace_msg(QDF_MODULE_ID module, QDF_TRACE_LEVEL level,
 		   const char *str_format, ...)
 {
@@ -264,25 +240,6 @@ static inline QDF_STATUS allocate_g_qdf_trace_tbl_buffer(void)
 static inline void free_g_qdf_trace_tbl_buffer(void)
 { }
 #endif
-/**
- * qdf_trace_enable() - Enable MTRACE for specific modules
- * @bitmask_of_module_id: Bitmask according to enum of the modules.
- *  32[dec] = 0010 0000 [bin] <enum of HDD is 5>
- *  64[dec] = 0100 0000 [bin] <enum of SME is 6>
- *  128[dec] = 1000 0000 [bin] <enum of PE is 7>
- * @enable: can be true or false true implies enabling MTRACE false implies
- *		disabling MTRACE.
- *
- * Enable MTRACE for specific modules whose bits are set in bitmask and enable
- * is true. if enable is false it disables MTRACE for that module. set the
- * bitmask according to enum value of the modules.
- * This functions will be called when you issue ioctl as mentioned following
- * [iwpriv wlan0 setdumplog <value> <enable>].
- * <value> - Decimal number, i.e. 64 decimal value shows only SME module,
- * 128 decimal value shows only PE module, 192 decimal value shows PE and SME.
- *
- * Return: None
- */
 void qdf_trace_enable(uint32_t bitmask_of_module_id, uint8_t enable)
 {
 	int i;
@@ -322,14 +279,6 @@ void qdf_trace_enable(uint32_t bitmask_of_module_id, uint8_t enable)
 }
 qdf_export_symbol(qdf_trace_enable);
 
-/**
- * qdf_trace_init() - initializes qdf trace structures and variables
- *
- * Called immediately after cds_preopen, so that we can start recording HDD
- * events ASAP.
- *
- * Return: None
- */
 void qdf_trace_init(void)
 {
 	uint8_t i;
@@ -350,14 +299,6 @@ void qdf_trace_init(void)
 }
 qdf_export_symbol(qdf_trace_init);
 
-/**
- * qdf_trace_deinit() - frees memory allocated dynamically
- *
- * Called from cds_deinit, so that we can free the memory and resets
- * the variables
- *
- * Return: None
- */
 void qdf_trace_deinit(void)
 {
 	g_qdf_trace_data.enable = false;
@@ -370,19 +311,6 @@ void qdf_trace_deinit(void)
 
 qdf_export_symbol(qdf_trace_deinit);
 
-/**
- * qdf_trace() - puts the messages in to ring-buffer
- * @module: Enum of module, basically module id.
- * @code: Code to be recorded
- * @session: Session ID of the log
- * @data: Actual message contents
- *
- * This function will be called from each module who wants record the messages
- * in circular queue. Before calling this functions make sure you have
- * registered your module with qdf through qdf_trace_register function.
- *
- * Return: None
- */
 void qdf_trace(uint8_t module, uint16_t code, uint16_t session, uint32_t data)
 {
 	tp_qdf_trace_record rec = NULL;
@@ -465,14 +393,6 @@ void qdf_mtrace(QDF_MODULE_ID src_module, QDF_MODULE_ID dst_module,
 
 qdf_export_symbol(qdf_mtrace);
 
-/**
- * qdf_trace_spin_lock_init() - initializes the lock variable before use
- *
- * This function will be called from cds_alloc_global_context, we will have lock
- * available to use ASAP
- *
- * Return: None
- */
 QDF_STATUS qdf_trace_spin_lock_init(void)
 {
 	spin_lock_init(&ltrace_lock);
@@ -481,19 +401,6 @@ QDF_STATUS qdf_trace_spin_lock_init(void)
 }
 qdf_export_symbol(qdf_trace_spin_lock_init);
 
-/**
- * qdf_trace_register() - registers the call back functions
- * @module_iD: enum value of module
- * @qdf_trace_callback: call back functions to display the messages in
- * particular format.
- *
- * Registers the call back functions to display the messages in particular
- * format mentioned in these call back functions. This functions should be
- * called by interested module in their init part as we will be ready to
- * register as soon as modules are up.
- *
- * Return: None
- */
 void qdf_trace_register(QDF_MODULE_ID module_id,
 			tp_qdf_trace_cb qdf_trace_callback)
 {
@@ -501,26 +408,6 @@ void qdf_trace_register(QDF_MODULE_ID module_id,
 }
 qdf_export_symbol(qdf_trace_register);
 
-/**
- * qdf_trace_dump_all() - Dump data from ring buffer via call back functions
- * registered with QDF
- * @p_mac: Context of particular module
- * @code: Reason code
- * @session: Session id of log
- * @count: Number of lines to dump starting from tail to head
- *
- * This function will be called up on issuing ioctl call as mentioned following
- * [iwpriv wlan0 dumplog 0 0 <n> <bitmask_of_module>]
- *
- * <n> - number lines to dump starting from tail to head.
- *
- * <bitmask_of_module> - if anybody wants to know how many messages were
- * recorded for particular module/s mentioned by setbit in bitmask from last
- * <n> messages. It is optional, if you don't provide then it will dump
- * everything from buffer.
- *
- * Return: None
- */
 void qdf_trace_dump_all(void *p_mac, uint8_t code, uint8_t session,
 	uint32_t count, uint32_t bitmask_of_module)
 {
@@ -606,12 +493,6 @@ qdf_export_symbol(qdf_trace_dump_all);
 #endif
 
 #ifdef WLAN_FEATURE_MEMDUMP_ENABLE
-/**
- * qdf_register_debugcb_init() - initializes debug callbacks
- * to NULL
- *
- * Return: None
- */
 void qdf_register_debugcb_init(void)
 {
 	uint8_t i;
@@ -621,17 +502,6 @@ void qdf_register_debugcb_init(void)
 }
 qdf_export_symbol(qdf_register_debugcb_init);
 
-/**
- * qdf_register_debug_callback() - stores callback handlers to print
- * state information
- * @module_id: module id of layer
- * @qdf_state_infocb: callback to be registered
- *
- * This function is used to store callback handlers to print
- * state information
- *
- * Return: None
- */
 void qdf_register_debug_callback(QDF_MODULE_ID module_id,
 					tp_qdf_state_info_cb qdf_state_infocb)
 {
@@ -639,17 +509,8 @@ void qdf_register_debug_callback(QDF_MODULE_ID module_id,
 }
 qdf_export_symbol(qdf_register_debug_callback);
 
-/**
- * qdf_state_info_dump_all() - it invokes callback of layer which registered
- * its callback to print its state information.
- * @buf:  buffer pointer to be passed
- * @size:  size of buffer to be filled
- * @driver_dump_size: actual size of buffer used
- *
- * Return: QDF_STATUS_SUCCESS on success
- */
 QDF_STATUS qdf_state_info_dump_all(char *buf, uint16_t size,
-			uint16_t *driver_dump_size)
+				   uint16_t *driver_dump_size)
 {
 	uint8_t module, ret = QDF_STATUS_SUCCESS;
 	uint16_t buf_len = size;
@@ -713,24 +574,6 @@ static void qdf_dp_unused(struct qdf_dp_trace_record_s *record,
 		  __func__);
 }
 
-/**
- * qdf_dp_trace_init() - enables the DP trace
- * @live_mode_config: live mode configuration
- * @thresh: high throughput threshold for disabling live mode
- * @thresh_time_limit: max time to wait before deciding if thresh is crossed
- * @verbosity: dptrace verbosity level
- * @proto_bitmap: bitmap to enable/disable specific protocols
- *
- * Called during driver load to init dptrace
- *
- * A brief note on the 'thresh' param -
- * Total # of packets received in a bandwidth timer interval beyond which
- * DP Trace logging for data packets (including ICMP) will be disabled.
- * In memory logging will still continue for these packets. Other packets for
- * which proto.bitmap is set will continue to be recorded in logs and in memory.
-
- * Return: None
- */
 void qdf_dp_trace_init(bool live_mode_config, uint8_t thresh,
 				uint16_t time_limit, uint8_t verbosity,
 				uint32_t proto_bitmap)
@@ -800,14 +643,7 @@ void qdf_dp_trace_deinit(void)
 
 	free_g_qdf_dp_trace_tbl_buffer();
 }
-/**
- * qdf_dp_trace_set_value() - Configure the value to control DP trace
- * @proto_bitmap: defines the protocol to be tracked
- * @no_of_records: defines the nth packet which is traced
- * @verbosity: defines the verbosity level
- *
- * Return: None
- */
+
 void qdf_dp_trace_set_value(uint32_t proto_bitmap, uint8_t no_of_record,
 			    uint8_t verbosity)
 {
@@ -818,13 +654,6 @@ void qdf_dp_trace_set_value(uint32_t proto_bitmap, uint8_t no_of_record,
 }
 qdf_export_symbol(qdf_dp_trace_set_value);
 
-/**
- * qdf_dp_trace_set_verbosity() - set verbosity value
- *
- * @val: Value to set
- *
- * Return: Null
- */
 void qdf_dp_trace_set_verbosity(uint32_t val)
 {
 	g_qdf_dp_trace_data.verbosity = val;
@@ -832,7 +661,7 @@ void qdf_dp_trace_set_verbosity(uint32_t val)
 qdf_export_symbol(qdf_dp_trace_set_verbosity);
 
 /**
- * qdf_dp_get_verbosity) - get verbosity value
+ * qdf_dp_get_verbosity() - get verbosity value
  *
  * Return: int
  */
@@ -842,13 +671,6 @@ uint8_t qdf_dp_get_verbosity(void)
 }
 qdf_export_symbol(qdf_dp_get_verbosity);
 
-/**
- * qdf_dp_set_proto_bitmap() - set dp trace proto bitmap
- *
- * @val         : unsigned bitmap to set
- *
- * Return: proto bitmap
- */
 void qdf_dp_set_proto_bitmap(uint32_t val)
 {
 	g_qdf_dp_trace_data.proto_bitmap = val;
@@ -867,24 +689,12 @@ static uint32_t qdf_dp_get_proto_event_bitmap(void)
 	return g_qdf_dp_trace_data.proto_event_bitmap;
 }
 
-/**
- * qdf_dp_set_no_of_record() - set dp trace no_of_record
- *
- * @val         : unsigned no_of_record to set
- *
- * Return: null
- */
 void qdf_dp_set_no_of_record(uint32_t val)
 {
 	g_qdf_dp_trace_data.no_of_record = val;
 }
 qdf_export_symbol(qdf_dp_set_no_of_record);
 
-/**
- * qdf_dp_get_no_of_record() - get dp trace no_of_record
- *
- * Return: number of records
- */
 uint8_t qdf_dp_get_no_of_record(void)
 {
 	return g_qdf_dp_trace_data.no_of_record;
@@ -929,11 +739,6 @@ static bool qdf_dp_trace_verbosity_check(enum QDF_DP_TRACE_ID code)
 	}
 }
 
-/**
- * qdf_dp_get_proto_bitmap() - get dp trace proto bitmap
- *
- * Return: proto bitmap
- */
 uint32_t qdf_dp_get_proto_bitmap(void)
 {
 	if (g_qdf_dp_trace_data.enable)
@@ -942,13 +747,6 @@ uint32_t qdf_dp_get_proto_bitmap(void)
 		return 0;
 }
 
-/**
- * qdf_dp_trace_set_track() - Marks whether the packet needs to be traced
- * @nbuf: defines the netbuf
- * @dir: direction
- *
- * Return: None
- */
 void qdf_dp_trace_set_track(qdf_nbuf_t nbuf, enum qdf_proto_dir dir)
 {
 	uint32_t count = 0;
@@ -1176,7 +974,7 @@ static const char *qdf_dp_type_to_str(enum qdf_proto_type type)
 
 /**
  * qdf_dp_subtype_to_str() - convert packet subtype to string
- * @type: type
+ * @subtype: subtype
  *
  * Return: string version of packet subtype
  */
@@ -1656,18 +1454,6 @@ uint8_t *qdf_get_pkt_status_string(uint8_t status)
 	}
 }
 
-/**
- * qdf_dp_log_proto_pkt_info() - Send diag log with pkt info
- * @sa: Source MAC address
- * @da: Destination MAC address
- * @type: packet type
- * @subtype: packet subtype
- * @dir: tx or rx
- * @msdu_id: MSDU id
- * @status: status code
- *
- * Return: none
- */
 void qdf_dp_log_proto_pkt_info(uint8_t *sa, uint8_t *da, uint8_t type,
 			       uint8_t subtype, uint8_t dir, uint16_t msdu_id,
 			       uint8_t status)
@@ -2543,19 +2329,9 @@ void qdf_dp_display_event_record(struct qdf_dp_trace_record_s *record,
 }
 qdf_export_symbol(qdf_dp_display_event_record);
 
-/**
- * qdf_dp_trace_record_event() - record events
- * @code: dptrace code
- * @vdev_id: vdev id
- * @pdev_id: pdev_id
- * @type: proto type
- * @subtype: proto subtype
- *
- * Return: none
- */
 void qdf_dp_trace_record_event(enum QDF_DP_TRACE_ID code, uint8_t vdev_id,
-		uint8_t pdev_id, enum qdf_proto_type type,
-		enum qdf_proto_subtype subtype)
+			       uint8_t pdev_id, enum qdf_proto_type type,
+			       enum qdf_proto_subtype subtype)
 {
 	struct qdf_dp_trace_event_buf buf;
 	int buf_size = sizeof(struct qdf_dp_trace_event_buf);
@@ -2904,16 +2680,6 @@ qdf_dp_display_data_pkt_record(struct qdf_dp_trace_record_s *record,
 			  record->size);
 }
 
-/**
- * qdf_dp_trace() - Stores the data in buffer
- * @nbuf  : defines the netbuf
- * @code : defines the event
- * @pdev_id: pdev_id
- * @data : defines the data to be stored
- * @size : defines the size of the data record
- *
- * Return: None
- */
 void qdf_dp_trace(qdf_nbuf_t nbuf, enum QDF_DP_TRACE_ID code, uint8_t pdev_id,
 	uint8_t *data, uint8_t size, enum qdf_proto_dir dir)
 {
@@ -2927,46 +2693,24 @@ void qdf_dp_trace(qdf_nbuf_t nbuf, enum QDF_DP_TRACE_ID code, uint8_t pdev_id,
 }
 qdf_export_symbol(qdf_dp_trace);
 
-/**
- * qdf_dp_trace_spin_lock_init() - initializes the lock variable before use
- * This function will be called from cds_alloc_global_context, we will have lock
- * available to use ASAP
- *
- * Return: None
- */
 void qdf_dp_trace_spin_lock_init(void)
 {
 	spin_lock_init(&l_dp_trace_lock);
 }
 qdf_export_symbol(qdf_dp_trace_spin_lock_init);
 
-/**
- * qdf_dp_trace_disable_live_mode - disable live mode for dptrace
- *
- * Return: none
- */
 void qdf_dp_trace_disable_live_mode(void)
 {
 	g_qdf_dp_trace_data.force_live_mode = 0;
 }
 qdf_export_symbol(qdf_dp_trace_disable_live_mode);
 
-/**
- * qdf_dp_trace_enable_live_mode() - enable live mode for dptrace
- *
- * Return: none
- */
 void qdf_dp_trace_enable_live_mode(void)
 {
 	g_qdf_dp_trace_data.force_live_mode = 1;
 }
 qdf_export_symbol(qdf_dp_trace_enable_live_mode);
 
-/**
- * qdf_dp_trace_clear_buffer() - clear dp trace buffer
- *
- * Return: none
- */
 void qdf_dp_trace_clear_buffer(void)
 {
 	g_qdf_dp_trace_data.head = INVALID_QDF_DP_TRACE_ADDR;
@@ -3156,7 +2900,7 @@ static void qdf_dpt_display_ptr_record_debugfs(qdf_debugfs_file_t file,
 }
 
 /**
- * qdf_dpt_display_ptr_record_debugfs() - display record
+ * qdf_dpt_display_record_debugfs() - display record
  * @file: file to read
  * @record: dptrace record
  * @index: index
@@ -3394,14 +3138,6 @@ QDF_STATUS qdf_dpt_dump_stats_debugfs(qdf_debugfs_file_t file,
 }
 qdf_export_symbol(qdf_dpt_dump_stats_debugfs);
 
-/**
- * qdf_dpt_set_value_debugfs() - Configure the value to control DP trace
- * @proto_bitmap: defines the protocol to be tracked
- * @no_of_records: defines the nth packet which is traced
- * @verbosity: defines the verbosity level
- *
- * Return: None
- */
 void qdf_dpt_set_value_debugfs(uint8_t proto_bitmap, uint8_t no_of_record,
 			    uint8_t verbosity, uint16_t num_records_to_dump)
 {
@@ -3415,14 +3151,6 @@ void qdf_dpt_set_value_debugfs(uint8_t proto_bitmap, uint8_t no_of_record,
 qdf_export_symbol(qdf_dpt_set_value_debugfs);
 
 
-/**
- * qdf_dp_trace_dump_all() - Dump data from ring buffer via call back functions
- * registered with QDF
- * @count: Number of lines to dump starting from tail to head
- * @pdev_id: pdev_id
- *
- * Return: None
- */
 void qdf_dp_trace_dump_all(uint32_t count, uint8_t pdev_id)
 {
 	struct qdf_dp_trace_record_s p_record;
@@ -3489,22 +3217,6 @@ void qdf_dp_trace_dump_all(uint32_t count, uint8_t pdev_id)
 }
 qdf_export_symbol(qdf_dp_trace_dump_all);
 
-/**
- * qdf_dp_trace_throttle_live_mode() - Throttle DP Trace live mode
- * @high_bw_request: whether this is a high BW req or not
- *
- * The function tries to prevent excessive logging into the live buffer by
- * having an upper limit on number of packets that can be logged per second.
- *
- * The intention is to allow occasional pings and data packets and really low
- * throughput levels while suppressing bursts and higher throughput levels so
- * that we donot hog the live buffer.
- *
- * If the number of packets printed in a particular second exceeds the thresh,
- * disable printing in the next second.
- *
- * Return: None
- */
 void qdf_dp_trace_throttle_live_mode(bool high_bw_request)
 {
 	static int bw_interval_counter;
@@ -3719,11 +3431,6 @@ struct category_name_info g_qdf_category_name[MAX_SUPPORTED_CATEGORY] = {
 };
 qdf_export_symbol(g_qdf_category_name);
 
-/**
- * qdf_trace_display() - Display trace
- *
- * Return:  None
- */
 void qdf_trace_display(void)
 {
 	QDF_MODULE_ID module_id;
@@ -3760,15 +3467,6 @@ uint32_t qdf_rl_print_count = WLAN_MAX_LOGS_PER_SEC;
 uint32_t qdf_rl_print_time = 1;
 uint32_t qdf_rl_print_suppressed;
 
-/**
- * qdf_detected_excessive_logging() - Excessive logging detected
- *
- * Track logging count using a quasi-tumbling window.
- * If the max logging count for a given window is exceeded,
- * return true else fails.
- *
- * Return: true/false
- */
 bool qdf_detected_excessive_logging(void)
 {
 	qdf_time_t now = qdf_system_ticks();