1 /***************************************************************************
2  * Copyright (c) 2024 Microsoft Corporation
3  *
4  * This program and the accompanying materials are made available under the
5  * terms of the MIT License which is available at
6  * https://opensource.org/licenses/MIT.
7  *
8  * SPDX-License-Identifier: MIT
9  **************************************************************************/
10 
11 
12 /**************************************************************************/
13 /**************************************************************************/
14 /**                                                                       */
15 /** ThreadX Component                                                     */
16 /**                                                                       */
17 /**   Mutex                                                               */
18 /**                                                                       */
19 /**************************************************************************/
20 /**************************************************************************/
21 
22 #define TX_SOURCE_CODE
23 
24 
25 /* Include necessary system files.  */
26 
27 #include "tx_api.h"
28 #include "tx_trace.h"
29 #include "tx_mutex.h"
30 
31 
32 /**************************************************************************/
33 /*                                                                        */
34 /*  FUNCTION                                               RELEASE        */
35 /*                                                                        */
36 /*    _tx_mutex_info_get                                  PORTABLE C      */
37 /*                                                           6.1          */
38 /*  AUTHOR                                                                */
39 /*                                                                        */
40 /*    William E. Lamie, Microsoft Corporation                             */
41 /*                                                                        */
42 /*  DESCRIPTION                                                           */
43 /*                                                                        */
44 /*    This function retrieves information from the specified mutex.       */
45 /*                                                                        */
46 /*  INPUT                                                                 */
47 /*                                                                        */
48 /*    mutex_ptr                         Pointer to mutex control block    */
49 /*    name                              Destination for the mutex name    */
50 /*    count                             Destination for the owner count   */
51 /*    owner                             Destination for the owner's       */
52 /*                                        thread control block pointer    */
53 /*    first_suspended                   Destination for pointer of first  */
54 /*                                        thread suspended on the mutex   */
55 /*    suspended_count                   Destination for suspended count   */
56 /*    next_mutex                        Destination for pointer to next   */
57 /*                                        mutex on the created list       */
58 /*                                                                        */
59 /*  OUTPUT                                                                */
60 /*                                                                        */
61 /*    status                            Completion status                 */
62 /*                                                                        */
63 /*  CALLS                                                                 */
64 /*                                                                        */
65 /*    None                                                                */
66 /*                                                                        */
67 /*  CALLED BY                                                             */
68 /*                                                                        */
69 /*    Application Code                                                    */
70 /*                                                                        */
71 /*  RELEASE HISTORY                                                       */
72 /*                                                                        */
73 /*    DATE              NAME                      DESCRIPTION             */
74 /*                                                                        */
75 /*  05-19-2020     William E. Lamie         Initial Version 6.0           */
76 /*  09-30-2020     Yuxin Zhou               Modified comment(s),          */
77 /*                                            resulting in version 6.1    */
78 /*                                                                        */
79 /**************************************************************************/
_tx_mutex_info_get(TX_MUTEX * mutex_ptr,CHAR ** name,ULONG * count,TX_THREAD ** owner,TX_THREAD ** first_suspended,ULONG * suspended_count,TX_MUTEX ** next_mutex)80 UINT  _tx_mutex_info_get(TX_MUTEX *mutex_ptr, CHAR **name, ULONG *count, TX_THREAD **owner,
81                     TX_THREAD **first_suspended, ULONG *suspended_count,
82                     TX_MUTEX **next_mutex)
83 {
84 
85 TX_INTERRUPT_SAVE_AREA
86 
87 
88     /* Disable interrupts.  */
89     TX_DISABLE
90 
91     /* If trace is enabled, insert this event into the trace buffer.  */
92     TX_TRACE_IN_LINE_INSERT(TX_TRACE_MUTEX_INFO_GET, mutex_ptr, 0, 0, 0, TX_TRACE_MUTEX_EVENTS)
93 
94     /* Log this kernel call.  */
95     TX_EL_MUTEX_INFO_GET_INSERT
96 
97     /* Retrieve all the pertinent information and return it in the supplied
98        destinations.  */
99 
100     /* Retrieve the name of the mutex.  */
101     if (name != TX_NULL)
102     {
103 
104         *name =  mutex_ptr -> tx_mutex_name;
105     }
106 
107     /* Retrieve the current ownership count of the mutex.  */
108     if (count != TX_NULL)
109     {
110 
111         *count =  ((ULONG) mutex_ptr -> tx_mutex_ownership_count);
112     }
113 
114     /* Retrieve the current owner of the mutex.  */
115     if (owner != TX_NULL)
116     {
117 
118         *owner =  mutex_ptr -> tx_mutex_owner;
119     }
120 
121     /* Retrieve the first thread suspended on this mutex.  */
122     if (first_suspended != TX_NULL)
123     {
124 
125         *first_suspended =  mutex_ptr -> tx_mutex_suspension_list;
126     }
127 
128     /* Retrieve the number of threads suspended on this mutex.  */
129     if (suspended_count != TX_NULL)
130     {
131 
132         *suspended_count =  (ULONG) mutex_ptr -> tx_mutex_suspended_count;
133     }
134 
135     /* Retrieve the pointer to the next mutex created.  */
136     if (next_mutex != TX_NULL)
137     {
138 
139         *next_mutex =  mutex_ptr -> tx_mutex_created_next;
140     }
141 
142     /* Restore interrupts.  */
143     TX_RESTORE
144 
145     /* Return completion status.  */
146     return(TX_SUCCESS);
147 }
148 
149