1 /*
2  * Copyright (C) 2019 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #pragma once
18 
19 #include <trusty_ipc.h>
20 
21 /**
22  * DOC: Theory of Operation
23  *
24  * UIRQ is a kernel object (identified by name non-empty string) that is
25  * designed to expose hardware or logical software interrupts (interrupt
26  * source) to a user space applications where it is represented as a UIRQ
27  * handle.
28  *
29  * An application obtains UIRQ handle by invoking uirq_open() routine.
30  * Successfully obtaining handle unmasks underlying interrupt source making it
31  * possible to generate interrupts.
32  *
33  * An application can wait on UIRQ handle using standard wait() call to
34  * get notified when underlying interrupt fires. When underlying interrupt
35  * fires it gets masked and a notification is delivered to user space as
36  * an event.
37  *
38  * In response for receiving interrupt notification an application should
39  * perform appropriate actions to handle it and then invoke uirq_ack_handled()
40  * routine to indicate that interrupt source can be unmasked again preparing
41  * for next interrupt delivery.
42  *
43  * The same UIRQ object can be opened multiple times by the same or different
44  * applications. In such case, an interrupt notification event will be
45  * delivered to every UIRQ handle instance and must be handled independently.
46  * The underlying interrupt source will be unmasked only when all clients has
47  * completed their interrupt handling.
48  *
49  * An application can invoke close() call to dispose a UIRQ handle. When
50  * the last instance of UIRQ handle is closed the underlying interrupt source
51  * gets masked preventing it from generating interrupts.
52  */
53 
54 /**
55  * uirq_open() - open UIRQ object
56  * @name: UIRQ object to open
57  * @flags: reserved must be 0
58  *
59  * Return: handle of UIRQ object on success, negative error code otherwise.
60  */
61 handle_t uirq_open(const char* name, uint32_t flags);
62 
63 /**
64  * uirq_ack_handled() - ACK interrupt
65  * @h: uirq handle returned by uirq_open() call
66  *
67  * Return: 0 on success, negative error code otherwise.
68  */
69 int uirq_ack_handled(handle_t h);
70