From a84e75527d6c0963f866f6cebb88b603f29098f8 Mon Sep 17 00:00:00 2001
From: ligr <liguorui1213@163.com>
Date: Mon, 22 Sep 2025 08:44:01 +0800
Subject: [PATCH] [components/lwp]add doxygen comment for lwp_tid.

---
 components/lwp/lwp_tid.c | 68 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)

diff --git a/components/lwp/lwp_tid.c b/components/lwp/lwp_tid.c
index e5e4889e4a..8ac016f40c 100644
--- a/components/lwp/lwp_tid.c
+++ b/components/lwp/lwp_tid.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2021, RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -38,11 +38,29 @@ static int current_tid = 0;
 
 static struct rt_mutex tid_lock;
 
+/**
+ * @brief Initialize the thread ID manager
+ *
+ * @return int Returns RT_EOK (0) on success, error code on failure
+ *
+ * @note This function initializes a mutex lock used for thread ID management.
+ */
 int lwp_tid_init(void)
 {
     return rt_mutex_init(&tid_lock, "tidmtx", RT_IPC_FLAG_PRIO);
 }
 
+/**
+ * @brief Allocates a thread ID (TID) from available resources
+ *
+ * @return int The allocated thread ID, or 0 if no TID available (with warning log)
+ *
+ * @note This function performs thread-safe allocation of a TID by:
+ *       1. First checking the free list of available TIDs
+ *       2. If none available, allocating from the TID array if space remains
+ *       3. Performing a two-phase search for unused TIDs (current_tid+1 to TID_MAX, then 1 to current_tid)
+ *       4. Inserting the allocated TID into the AVL tree for tracking
+ */
 int lwp_tid_get(void)
 {
     struct lwp_avl_struct *p;
@@ -97,6 +115,16 @@ int lwp_tid_get(void)
     return tid;
 }
 
+/**
+ * @brief Releases a thread ID (TID) and associated resources
+ *
+ * @param[in] tid The thread ID to release
+ *
+ * @note  This function performs thread-safe release of a TID by:
+ *        1. Finding the TID in the AVL tree and removing it
+ *        2. Adding the freed TID structure to the free list for reuse
+ *        3. Handling thread reference counting and potential suspension
+ */
 void lwp_tid_put(int tid)
 {
     struct lwp_avl_struct *p;
@@ -133,6 +161,13 @@ void lwp_tid_put(int tid)
         lwp_mutex_release_safe(&tid_lock);
 }
 
+/**
+ * @brief Retrieves the thread object associated with a thread ID (TID)
+ *
+ * @param[in] tid The thread ID to look up
+ *
+ * @return rt_thread_t The associated thread object, or RT_NULL if not found
+ */
 rt_thread_t lwp_tid_get_thread_raw(int tid)
 {
     struct lwp_avl_struct *p;
@@ -146,6 +181,19 @@ rt_thread_t lwp_tid_get_thread_raw(int tid)
     return thread;
 }
 
+/**
+ * @brief Retrieves a thread object by TID and increments its reference count
+ *
+ * @param[in] tid The thread ID to look up (0 means current thread)
+ *
+ * @return rt_thread_t The associated thread object, or RT_NULL if not found
+ *
+ * @note This function provides thread-safe access to a thread object while:
+ *       1. Acquiring the tid_lock mutex for synchronization
+ *       2. Looking up the thread by TID (or returning current thread if tid=0)
+ *       3. Incrementing the thread's reference count if found
+ *       4. Releasing the mutex before returning
+ */
 rt_thread_t lwp_tid_get_thread_and_inc_ref(int tid)
 {
     rt_thread_t thread = RT_NULL;
@@ -160,6 +208,15 @@ rt_thread_t lwp_tid_get_thread_and_inc_ref(int tid)
     return thread;
 }
 
+/**
+ * @brief Decrement the reference count of a thread and potentially resume its suspender
+ *
+ * @param[in] thread The thread object whose reference count needs to be decremented
+ *
+ * @note This function safely decreases the reference count of a thread object. If the reference
+ *       count reaches zero and there is a suspender thread waiting (susp_recycler), it will
+ *       be resumed.
+ */
 void lwp_tid_dec_ref(rt_thread_t thread)
 {
     rt_thread_t susp_putter;
@@ -179,6 +236,15 @@ void lwp_tid_dec_ref(rt_thread_t thread)
     }
 }
 
+/**
+ * @brief Associate a thread with a given TID in the thread ID management system
+ *
+ * @param[in] tid The thread ID to associate with the thread
+ * @param[in] thread The thread object to be associated with the TID
+ *
+ * @note This function safely associates a thread object with a specified thread ID (TID)
+ *       in the system's AVL tree. The operation is protected by a mutex to ensure thread safety.
+ */
 void lwp_tid_set_thread(int tid, rt_thread_t thread)
 {
     struct lwp_avl_struct *p;