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