1 /*******************************************************************************
2  *
3  * Module Name: utxfmutex - external AML mutex access functions
4  *
5  ******************************************************************************/
6 
7 /*
8  * Copyright (C) 2000 - 2020, Intel Corp.
9  * All rights reserved.
10  *
11  * Redistribution and use in source and binary forms, with or without
12  * modification, are permitted provided that the following conditions
13  * are met:
14  * 1. Redistributions of source code must retain the above copyright
15  *    notice, this list of conditions, and the following disclaimer,
16  *    without modification.
17  * 2. Redistributions in binary form must reproduce at minimum a disclaimer
18  *    substantially similar to the "NO WARRANTY" disclaimer below
19  *    ("Disclaimer") and any redistribution must be conditioned upon
20  *    including a substantially similar Disclaimer requirement for further
21  *    binary redistribution.
22  * 3. Neither the names of the above-listed copyright holders nor the names
23  *    of any contributors may be used to endorse or promote products derived
24  *    from this software without specific prior written permission.
25  *
26  * Alternatively, this software may be distributed under the terms of the
27  * GNU General Public License ("GPL") version 2 as published by the Free
28  * Software Foundation.
29  *
30  * NO WARRANTY
31  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
32  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
33  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
34  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
35  * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
36  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
37  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
38  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
39  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
40  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
41  * POSSIBILITY OF SUCH DAMAGES.
42  */
43 
44 #include "acpi.h"
45 #include "accommon.h"
46 #include "acnamesp.h"
47 
48 
49 #define _COMPONENT          ACPI_UTILITIES
50         ACPI_MODULE_NAME    ("utxfmutex")
51 
52 
53 /* Local prototypes */
54 
55 static ACPI_STATUS
56 AcpiUtGetMutexObject (
57     ACPI_HANDLE             Handle,
58     ACPI_STRING             Pathname,
59     ACPI_OPERAND_OBJECT     **RetObj);
60 
61 
62 /*******************************************************************************
63  *
64  * FUNCTION:    AcpiUtGetMutexObject
65  *
66  * PARAMETERS:  Handle              - Mutex or prefix handle (optional)
67  *              Pathname            - Mutex pathname (optional)
68  *              RetObj              - Where the mutex object is returned
69  *
70  * RETURN:      Status
71  *
72  * DESCRIPTION: Get an AML mutex object. The mutex node is pointed to by
73  *              Handle:Pathname. Either Handle or Pathname can be NULL, but
74  *              not both.
75  *
76  ******************************************************************************/
77 
78 static ACPI_STATUS
79 AcpiUtGetMutexObject (
80     ACPI_HANDLE             Handle,
81     ACPI_STRING             Pathname,
82     ACPI_OPERAND_OBJECT     **RetObj)
83 {
84     ACPI_NAMESPACE_NODE     *MutexNode;
85     ACPI_OPERAND_OBJECT     *MutexObj;
86     ACPI_STATUS             Status;
87 
88 
89     /* Parameter validation */
90 
91     if (!RetObj || (!Handle && !Pathname))
92     {
93         return (AE_BAD_PARAMETER);
94     }
95 
96     /* Get a the namespace node for the mutex */
97 
98     MutexNode = Handle;
99     if (Pathname != NULL)
100     {
101         Status = AcpiGetHandle (
102             Handle, Pathname, ACPI_CAST_PTR (ACPI_HANDLE, &MutexNode));
103         if (ACPI_FAILURE (Status))
104         {
105             return (Status);
106         }
107     }
108 
109     /* Ensure that we actually have a Mutex object */
110 
111     if (!MutexNode ||
112         (MutexNode->Type != ACPI_TYPE_MUTEX))
113     {
114         return (AE_TYPE);
115     }
116 
117     /* Get the low-level mutex object */
118 
119     MutexObj = AcpiNsGetAttachedObject (MutexNode);
120     if (!MutexObj)
121     {
122         return (AE_NULL_OBJECT);
123     }
124 
125     *RetObj = MutexObj;
126     return (AE_OK);
127 }
128 
129 
130 /*******************************************************************************
131  *
132  * FUNCTION:    AcpiAcquireMutex
133  *
134  * PARAMETERS:  Handle              - Mutex or prefix handle (optional)
135  *              Pathname            - Mutex pathname (optional)
136  *              Timeout             - Max time to wait for the lock (millisec)
137  *
138  * RETURN:      Status
139  *
140  * DESCRIPTION: Acquire an AML mutex. This is a device driver interface to
141  *              AML mutex objects, and allows for transaction locking between
142  *              drivers and AML code. The mutex node is pointed to by
143  *              Handle:Pathname. Either Handle or Pathname can be NULL, but
144  *              not both.
145  *
146  ******************************************************************************/
147 
148 ACPI_STATUS
149 AcpiAcquireMutex (
150     ACPI_HANDLE             Handle,
151     ACPI_STRING             Pathname,
152     UINT16                  Timeout)
153 {
154     ACPI_STATUS             Status;
155     ACPI_OPERAND_OBJECT     *MutexObj;
156 
157 
158     /* Get the low-level mutex associated with Handle:Pathname */
159 
160     Status = AcpiUtGetMutexObject (Handle, Pathname, &MutexObj);
161     if (ACPI_FAILURE (Status))
162     {
163         return (Status);
164     }
165 
166     /* Acquire the OS mutex */
167 
168     Status = AcpiOsAcquireMutex (MutexObj->Mutex.OsMutex, Timeout);
169     return (Status);
170 }
171 
172 ACPI_EXPORT_SYMBOL (AcpiAcquireMutex)
173 
174 
175 /*******************************************************************************
176  *
177  * FUNCTION:    AcpiReleaseMutex
178  *
179  * PARAMETERS:  Handle              - Mutex or prefix handle (optional)
180  *              Pathname            - Mutex pathname (optional)
181  *
182  * RETURN:      Status
183  *
184  * DESCRIPTION: Release an AML mutex. This is a device driver interface to
185  *              AML mutex objects, and allows for transaction locking between
186  *              drivers and AML code. The mutex node is pointed to by
187  *              Handle:Pathname. Either Handle or Pathname can be NULL, but
188  *              not both.
189  *
190  ******************************************************************************/
191 
192 ACPI_STATUS
193 AcpiReleaseMutex (
194     ACPI_HANDLE             Handle,
195     ACPI_STRING             Pathname)
196 {
197     ACPI_STATUS             Status;
198     ACPI_OPERAND_OBJECT     *MutexObj;
199 
200 
201     /* Get the low-level mutex associated with Handle:Pathname */
202 
203     Status = AcpiUtGetMutexObject (Handle, Pathname, &MutexObj);
204     if (ACPI_FAILURE (Status))
205     {
206         return (Status);
207     }
208 
209     /* Release the OS mutex */
210 
211     AcpiOsReleaseMutex (MutexObj->Mutex.OsMutex);
212     return (AE_OK);
213 }
214 
215 ACPI_EXPORT_SYMBOL (AcpiReleaseMutex)
216