qcacmn: Fix TWT documentation

Kernel doc script identified documentation issues
in twt, so fix these issues.

Change-Id: I9168e01e5a1941c947726d5f7ac67b6d17af4fb6
CRs-Fixed: 3400817

umac/twt/core/src/wlan_twt_objmgr_handler.h

@@ -1,5 +1,5 @@
 /*
- * 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
@@ -42,7 +42,7 @@ wlan_twt_psoc_obj_destroy_handler(struct wlan_objmgr_psoc *psoc, void *arg);
 
 /**
  * wlan_twt_vdev_obj_create_handler() - twt vdev create handler
- * @psoc: psoc handle
+ * @vdev: vdev handle
  * @arg: argument
  *
  * return: QDF_STATUS
@@ -52,7 +52,7 @@ wlan_twt_vdev_obj_create_handler(struct wlan_objmgr_vdev *vdev, void *arg);
 
 /**
  * wlan_twt_vdev_obj_destroy_handler() - twt vdev destroy handler
- * @psoc: psoc handle
+ * @vdev: vdev handle
  * @arg: argument
  *
  * return: QDF_STATUS
@@ -62,7 +62,7 @@ wlan_twt_vdev_obj_destroy_handler(struct wlan_objmgr_vdev *vdev, void *arg);
 
 /**
  * wlan_twt_peer_obj_create_handler() - twt peer create handler
- * @psoc: psoc handle
+ * @peer: peer handle
  * @arg: argument
  *
  * return: QDF_STATUS
@@ -72,7 +72,7 @@ wlan_twt_peer_obj_create_handler(struct wlan_objmgr_peer *peer, void *arg);
 
 /**
  * wlan_twt_peer_obj_destroy_handler() - twt peer destroy handler
- * @psoc: psoc handle
+ * @peer: peer handle
  * @arg: argument
  *
  * return: QDF_STATUS

umac/twt/dispatcher/inc/wlan_twt_api.h

@@ -1,5 +1,5 @@
 /*
- * 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
@@ -66,7 +66,6 @@ QDF_STATUS twt_psoc_disable(struct wlan_objmgr_psoc *psoc);
 
 /**
  * wlan_twt_init() - twt init
- * @psoc: psoc handle
  *
  * return: QDF_STATUS
  */
@@ -74,7 +73,6 @@ QDF_STATUS wlan_twt_init(void);
 
 /**
  * wlan_twt_deinit() - twt de-init
- * @psoc: psoc handle
  *
  * return: QDF_STATUS
  */

umac/twt/dispatcher/inc/wlan_twt_public_structs.h

@@ -1,5 +1,5 @@
 /*
- * 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
@@ -86,18 +86,20 @@ enum wlan_twt_session_state {
 	WLAN_TWT_SETUP_STATE_SUSPEND         = 2,
 };
 
-/* enum TWT_ROLE - role specified in ext conf in wmi_twt_enable/disable_cmd
- * TWT_ROLE_REQUESTOR: TWT role is requestor
- * TWT_ROLE_RESPONDER: TWT role is responder
+/**
+ * enum TWT_ROLE - role specified in ext conf in wmi_twt_enable/disable_cmd
+ * @TWT_ROLE_REQUESTOR: TWT role is requestor
+ * @TWT_ROLE_RESPONDER: TWT role is responder
  */
 enum TWT_ROLE {
 	TWT_ROLE_REQUESTOR,
 	TWT_ROLE_RESPONDER,
 };
 
-/* enum TWT_OPERATION - specified in ext conf in wmi_twt_enable/disable_cmd
- * TWT_OPERATION_INDIVIDUAL: Individual TWT operation
- * TWT_OPERATION_BROADCAST: Broadcast TWT operation
+/**
+ * enum TWT_OPERATION - specified in ext conf in wmi_twt_enable/disable_cmd
+ * @TWT_OPERATION_INDIVIDUAL: Individual TWT operation
+ * @TWT_OPERATION_BROADCAST: Broadcast TWT operation
  */
 enum TWT_OPERATION {
 	TWT_OPERATION_INDIVIDUAL,
@@ -177,7 +179,8 @@ struct twt_enable_param {
 		 b_twt_ax_mbss_enable:1;
 };
 
-/* HOST_TWT_DISABLE_REASON - reason code of disable TWT
+/**
+ * enum HOST_TWT_DISABLE_REASON - reason code of disable TWT
  * @HOST_TWT_DISABLE_REASON_NONE: Host sends TWT disable command to firmware
  *                              in normal case.
  * @HOST_TWT_DISABLE_REASON_CONCURRENCY_SCC: Host sends TWT disable command
@@ -213,16 +216,14 @@ struct twt_disable_param {
 	enum HOST_TWT_DISABLE_REASON dis_reason_code;
 };
 
-/* status code of enabling TWT
- * HOST_TWT_ENABLE_STATUS_OK: enabling TWT successfully completed
- * HOST_TWT_ENABLE_STATUS_ALREADY_ENABLED: TWT already enabled
- * HOST_TWT_ENABLE_STATUS_NOT_READY: FW not ready for enabling TWT
- * HOST_TWT_ENABLE_INVALID_PARAM: invalid parameters
- * HOST_TWT_ENABLE_STATUS_UNKNOWN_ERROR: enabling TWT failed with an
+/**
+ * enum HOST_TWT_ENABLE_STATUS - status code of enabling TWT
+ * @HOST_TWT_ENABLE_STATUS_OK: enabling TWT successfully completed
+ * @HOST_TWT_ENABLE_STATUS_ALREADY_ENABLED: TWT already enabled
+ * @HOST_TWT_ENABLE_STATUS_NOT_READY: FW not ready for enabling TWT
+ * @HOST_TWT_ENABLE_INVALID_PARAM: invalid parameters
+ * @HOST_TWT_ENABLE_STATUS_UNKNOWN_ERROR: enabling TWT failed with an
  *                                      unknown reason
- * HOST_TWT_ENABLE_STATUS_INVALID_COMMAND: If the host has sent TWT enable
- *                     command and received TWT disable event or any other event
- *                     then host sets this status internally.
  */
 enum HOST_TWT_ENABLE_STATUS {
 	HOST_TWT_ENABLE_STATUS_OK,
@@ -232,7 +233,8 @@ enum HOST_TWT_ENABLE_STATUS {
 	HOST_TWT_ENABLE_STATUS_UNKNOWN_ERROR,
 };
 
-/* enum - status code of adding TWT dialog
+/**
+ * enum HOST_ADD_TWT_STATUS - status code of adding TWT dialog
  * @HOST_ADD_TWT_STATUS_OK: adding TWT dialog successfully completed
  * @HOST_ADD_TWT_STATUS_TWT_NOT_ENABLED: TWT not enabled
  * @HOST_ADD_TWT_STATUS_USED_DIALOG_ID: TWT dialog ID is already used
@@ -281,7 +283,8 @@ struct twt_enable_complete_event_param {
 	uint32_t status;
 };
 
-/* enum HOST_TWT_DISABLE_STATUS  - status code of disable TWT
+/**
+ * enum HOST_TWT_DISABLE_STATUS  - status code of disable TWT
  * @HOST_TWT_DISABLE_STATUS_OK: TWT disable is successfully completed
  * @HOST_TWT_DISABLE_STATUS_ROAM_IN_PROGRESS: roaming in progress
  * @HOST_TWT_DISABLE_STATUS_CHAN_SW_IN_PROGRESS: channel switch in progress
@@ -297,7 +300,7 @@ enum HOST_TWT_DISABLE_STATUS {
 };
 
 /**
- * struct twt_disable_complete_event:
+ * struct twt_disable_complete_event_param:
  * @pdev_id: pdev_id for identifying the MAC.
  * @status: From enum HOST_TWT_DISABLE_STATUS
  */
@@ -307,7 +310,7 @@ struct twt_disable_complete_event_param {
 };
 
 /**
- * twt_ack_context - twt ack private context
+ * struct twt_ack_context: twt ack private context
  * @vdev_id: vdev id
  * @peer_macaddr: peer mac address
  * @dialog_id: dialog id
@@ -323,7 +326,7 @@ struct twt_ack_context {
 };
 
 /**
- * twt_en_dis_context - twt enable/disable private context
+ * struct twt_en_dis_context:  twt enable/disable private context
  * @twt_role: twt role. When the upper layer is invoking requestor/responder
  * enable/disable command via the TWT component API, Firmware WMI event
  * doesn't have the info in the event params to distinguish if this enable or
@@ -364,6 +367,8 @@ struct twt_ack_complete_event_param {
  * @announ: If the flow type is announced/unannounced
  * @protection: If the TWT protection field is set
  * @info_frame_disabled: If the TWT Information frame is disabled
+ * @pm_responder_bit_valid: is pm_responder_bit valid
+ * @pm_responder_bit: set pm_responder_bit
  * @dialog_id: Dialog_id of current session
  * @wake_dura_us: wake duration in us
  * @wake_intvl_us: wake time interval in us
@@ -451,7 +456,7 @@ enum HOST_TWT_COMMAND {
  * @b_twt_recommendation: defines types of frames tx during bTWT SP
  * @b_twt_persistence: Countdown VAL frames to param update/teardown
  * @wake_time_tsf: Absolute TSF value to start first TWT service period
- * @annouce_timeout_us: Timeout value before sending QoS NULL frame.
+ * @announce_timeout_us: Timeout value before sending QoS NULL frame.
  */
 struct twt_add_dialog_param {
 	uint32_t vdev_id;
@@ -479,7 +484,8 @@ struct twt_add_dialog_param {
 	uint32_t announce_timeout_us;
 };
 
-/* enum HOST_TWT_GET_STATS_STATUS - status code of TWT Get stats dialog id
+/**
+ * enum HOST_TWT_GET_STATS_STATUS - status code of TWT Get stats dialog id
  * @HOST_TWT_GET_STATS_STATUS_OK: Get status TWT dialog successfully completed
  * @HOST_TWT_GET_STATS_STATUS_DIALOG_ID_NOT_EXIST: TWT dialog ID does not exist
  * @HOST_TWT_GET_STATS_STATUS_INVALID_PARAM: Invalid parameters
@@ -492,7 +498,8 @@ enum HOST_TWT_GET_STATS_STATUS {
 	HOST_TWT_GET_STATS_STATUS_UNKNOWN_ERROR,
 };
 
-/* enum HOST_TWT_ADD_STATUS - status code of TWT add dialog
+/**
+ * enum HOST_TWT_ADD_STATUS - status code of TWT add dialog
  * @HOST_TWT_ADD_STATUS_OK: add TWT dialog successfully completed
  * @HOST_TWT_ADD_STATUS_TWT_NOT_ENABLED: TWT not enabled
  * @HOST_TWT_ADD_STATUS_USED_DIALOG_ID: TWT dialog ID is already used
@@ -550,7 +557,7 @@ enum HOST_TWT_ADD_STATUS {
  *                          0 means responder pm mode field is not valid
  * @pm_responder_bit: 1 means that responder set responder pm mode to 1
  *                    0 means that responder set responder pm mode to 0
- * @wake_dura_us: wake duration in us
+ * @wake_dur_us: wake duration in us
  * @wake_intvl_us: wake time interval in us
  * @sp_offset_us: Time until initial TWT SP occurs
  * @sp_tsf_us_lo: TWT service period tsf in usecs lower bits - 31:0
@@ -574,7 +581,7 @@ struct twt_add_dialog_additional_params {
 };
 
 /**
- * struct twt_add_dialog_complete_param -
+ * struct twt_add_dialog_complete_event_param:
  * @vdev_id: VDEV identifier
  * @peer_macaddr: Peer mac address
  * @dialog_id: TWT dialog ID
@@ -702,7 +709,8 @@ struct twt_nudge_dialog_cmd_param {
 	int32_t sp_start_offset;
 };
 
-/* enum HOST_TWT_PAUSE_STATUS - status code of pause TWT dialog
+/**
+ * enum HOST_TWT_PAUSE_STATUS - status code of pause TWT dialog
  * @HOST_TWT_PAUSE_STATUS_OK: pausing TWT dialog successfully completed
  * @HOST_TWT_PAUSE_STATUS_DIALOG_ID_NOT_EXIST: TWT dialog ID not exists
  * @HOST_TWT_PAUSE_STATUS_INVALID_PARAM: invalid parameters
@@ -746,7 +754,8 @@ struct twt_pause_dialog_complete_event_param {
 	enum HOST_TWT_PAUSE_STATUS status;
 };
 
-/* enum HOST_TWT_NUDGE_STATUS - status code of nudge TWT dialog
+/**
+ * enum HOST_TWT_NUDGE_STATUS - status code of nudge TWT dialog
  * @HOST_TWT_NUDGE_STATUS_OK: nudge TWT dialog successfully completed
  * @HOST_TWT_NUDGE_STATUS_DIALOG_ID_NOT_EXIST: TWT dialog ID not exists
  * @HOST_TWT_NUDGE_STATUS_INVALID_PARAM: invalid parameters
@@ -757,6 +766,7 @@ struct twt_pause_dialog_complete_event_param {
  * request/response frame
  * @HOST_TWT_NUDGE_STATUS_UNKNOWN_ERROR: nudge TWT dialog failed with an
  * unknown reason
+ * @HOST_TWT_NUDGE_STATUS_ALREADY_PAUSED: TWT dialog already in paused state
  * @HOST_TWT_NUDGE_STATUS_CHAN_SW_IN_PROGRESS: Channel switch in progress
  * @HOST_TWT_NUDGE_STATUS_ROAM_IN_PROGRESS: Roaming in progress
  * @HOST_TWT_NUDGE_STATUS_SCAN_IN_PROGRESS: Scan is in progress
@@ -810,7 +820,8 @@ struct twt_resume_dialog_cmd_param {
 	uint32_t next_twt_size;
 };
 
-/* enum HOST_TWT_RESUME_STATUS - status code of resume TWT dialog
+/**
+ * enum HOST_TWT_RESUME_STATUS - status code of resume TWT dialog
  * @HOST_TWT_RESUME_STATUS_OK: resuming TWT dialog successfully completed
  * @HOST_TWT_RESUME_STATUS_DIALOG_ID_NOT_EXIST: TWT dialog ID not exists
  * @HOST_TWT_RESUME_STATUS_INVALID_PARAM: invalid parameters
@@ -854,7 +865,8 @@ struct twt_resume_dialog_complete_event_param {
 	uint32_t status;
 };
 
-/* enum HOST_TWT_NOTIFY_STATUS - status code of notify TWT event
+/**
+ * enum HOST_TWT_NOTIFY_STATUS - status code of notify TWT event
  * @HOST_TWT_NOTIFY_EVENT_READY: FW is ready to process the TWT setup request.
  * @HOST_TWT_NOTIFY_EVENT_AP_TWT_REQ_BIT_SET: AP set the TWT required bit
  * @HOST_TWT_NOTIFY_EVENT_AP_TWT_REQ_BIT_CLEAR: AP cleared the TWT required bit
@@ -875,7 +887,8 @@ struct twt_notify_event_param {
 	enum HOST_TWT_NOTIFY_STATUS status;
 };
 
-/* HOST_TWT_NEXT_WORK_ACTION - next action of TWT worker thread
+/**
+ * enum HOST_TWT_NEXT_WORK_ACTION - next action of TWT worker thread
  * @HOST_TWT_SEND_DELETE_CMD: Send TWT delete command request
  */
 enum HOST_TWT_NEXT_WORK_ACTION {
@@ -904,19 +917,20 @@ struct twt_btwt_invite_sta_cmd_param {
 	uint32_t dialog_id;
 };
 
-/* enum HOST_TWT_INVITATION_BTWT_STATUS - status code of TWT Invitation
+/**
+ * enum HOST_TWT_INVITATION_BTWT_STATUS - status code of TWT Invitation
  *                              dialog
- * HOST_TWT_INVITATION_BTWT_STATUS_OK: BTWT invitation successfully
+ * @HOST_TWT_INVITATION_BTWT_STATUS_OK: BTWT invitation successfully
  *                              completed
- * HOST_TWT_INVITATION_TWT_STATUS_DIALOG_ID_NOT_EXIST: BTWT dialog ID not
+ * @HOST_TWT_INVITATION_BTWT_STATUS_DIALOG_ID_NOT_EXIST: BTWT dialog ID not
  *                              exists
- * HOST_TWT_INVITATION_BTWT_STATUS_INVALID_PARAM: invalid parameters
- * HOST_TWT_INVITATION_BTWT_STATUS_DIALOG_ID_BUSY: FW is in the process of
+ * @HOST_TWT_INVITATION_BTWT_STATUS_INVALID_PARAM: invalid parameters
+ * @HOST_TWT_INVITATION_BTWT_STATUS_DIALOG_ID_BUSY: FW is in the process of
  *                              handling this dialog
- * HOST_TWT_INVITATION_BTWT_STATUS_NO_RESOURCE: FW resource exhausted
- * HOST_TWT_INVITATION_BTWT_STATUS_NO_ACK: peer AP/STA did not ACK the
+ * @HOST_TWT_INVITATION_BTWT_STATUS_NO_RESOURCE: FW resource exhausted
+ * @HOST_TWT_INVITATION_BTWT_STATUS_NO_ACK: peer AP/STA did not ACK the
  *                              request/response frame
- * HOST_TWT_INVITATION_BTWT_STATUS_UNKNOWN_ERROR: BTWT invitation failed
+ * @HOST_TWT_INVITATION_BTWT_STATUS_UNKNOWN_ERROR: BTWT invitation failed
  *                              with an unknown reason
  */
 enum HOST_TWT_INVITATION_BTWT_STATUS {
@@ -955,18 +969,19 @@ struct twt_btwt_remove_sta_cmd_param {
 	uint32_t dialog_id;
 };
 
-/* enum HOST_TWT_KICKOFF_BTWT_STATUS - status code of kickoff BTWT dialog
- * HOST_TWT_KICKOFF_BTWT_STATUS_OK: TWT kickoff successfully completed
- * HOST_TWT_KICKOFF_BTWT_STATUS_DIALOG_ID_NOT_EXIST: BTWT dialog ID not
+/**
+ * enum HOST_TWT_KICKOFF_BTWT_STATUS - status code of kickoff BTWT dialog
+ * @HOST_TWT_KICKOFF_BTWT_STATUS_OK: TWT kickoff successfully completed
+ * @HOST_TWT_KICKOFF_BTWT_STATUS_DIALOG_ID_NOT_EXIST: BTWT dialog ID not
  *                              exists
- * HOST_TWT_KICKOFF_BTWT_STATUS_INVALID_PARAM: invalid parameters
- * HOST_TWT_KICKOFF_BTWT_STATUS_DIALOG_ID_BUSY: FW is in the process of
+ * @HOST_TWT_KICKOFF_BTWT_STATUS_INVALID_PARAM: invalid parameters
+ * @HOST_TWT_KICKOFF_BTWT_STATUS_DIALOG_ID_BUSY: FW is in the process of
  *                              handling this dialog
- * HOST_TWT_KICKOFF_BTWT_STATUS_NOT_PAUSED: Dialog not currently paused
- * HOST_TWT_KICKOFF_BTWT_STATUS_NO_RESOURCE: FW resource exhausted
- * HOST_TWT_KICKOFF_BTWT_STATUS_NO_ACK: peer AP/STA did not ACK the
+ * @HOST_TWT_KICKOFF_BTWT_STATUS_NOT_PAUSED: Dialog not currently paused
+ * @HOST_TWT_KICKOFF_BTWT_STATUS_NO_RESOURCE: FW resource exhausted
+ * @HOST_TWT_KICKOFF_BTWT_STATUS_NO_ACK: peer AP/STA did not ACK the
  *                              request/response frame
- * HOST_TWT_KICKOFF_BTWT_STATUS_UNKNOWN_ERROR: BTWT kickoff failed with an
+ * @HOST_TWT_KICKOFF_BTWT_STATUS_UNKNOWN_ERROR: BTWT kickoff failed with an
  *                              unknown reason
  */
 enum HOST_TWT_KICKOFF_BTWT_STATUS {
@@ -997,12 +1012,12 @@ struct twt_btwt_remove_sta_complete_event_param {
 
 /**
  * enum HOST_TWT_CMD_FOR_ACK_EVENT - Ack event for different TWT command
- * HOST_TWT_ADD_DIALOG_CMDID: Ack event for add dialog command
- * HOST_TWT_DEL_DIALOG_CMDID: Ack event for delete dialog command
- * HOST_TWT_PAUSE_DIALOG_CMDID: Ack event for pause command
- * HOST_TWT_RESUME_DIALOG_CMDID: Ack event for resume command
- * HOST_TWT_NUDGE_DIALOG_CMDID: Ack event for nudge command
- * HOST_TWT_UNKNOWN_CMDID: Ack event for unknown TWT command
+ * @HOST_TWT_ADD_DIALOG_CMDID: Ack event for add dialog command
+ * @HOST_TWT_DEL_DIALOG_CMDID: Ack event for delete dialog command
+ * @HOST_TWT_PAUSE_DIALOG_CMDID: Ack event for pause command
+ * @HOST_TWT_RESUME_DIALOG_CMDID: Ack event for resume command
+ * @HOST_TWT_NUDGE_DIALOG_CMDID: Ack event for nudge command
+ * @HOST_TWT_UNKNOWN_CMDID: Ack event for unknown TWT command
  */
 enum HOST_TWT_CMD_FOR_ACK_EVENT {
 	HOST_TWT_ADD_DIALOG_CMDID = 0,