1 /*
2  * Copyright (c) 2011-2012, The Linux Foundation. All rights reserved.
3 
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *   * Redistributions of source code must retain the above copyright
8  *     notice, this list of conditions and the following disclaimer.
9  *   * Redistributions in binary form must reproduce the above
10  *     copyright notice, this list of conditions and the following
11  *     disclaimer in the documentation and/or other materials provided
12  *     with the distribution.
13  *   * Neither the name of The Linux Foundation nor the names of its
14  *     contributors may be used to endorse or promote products derived
15  *     from this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
18  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
19  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
20  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
21  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
24  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
25  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
26  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
27  * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28  */
29 
30 #ifndef INCLUDE_LIBGENLOCK
31 #define INCLUDE_LIBGENLOCK
32 
33 #include <cutils/native_handle.h>
34 
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38 
39     /* Genlock lock types */
40     typedef enum genlock_lock_type{
41         GENLOCK_READ_LOCK  = 1<<0,  // Read lock
42         GENLOCK_WRITE_LOCK = 1<<1,  // Write lock
43     }genlock_lock_type_t;
44 
45     /* Genlock return values */
46     typedef enum genlock_status{
47         GENLOCK_NO_ERROR = 0,
48         GENLOCK_TIMEDOUT,
49         GENLOCK_FAILURE,
50     } genlock_status_t;
51 
52     /* Genlock defines */
53 #define GENLOCK_MAX_TIMEOUT 1000 // Max 1s timeout
54 
55     /*
56      * Create a genlock lock. The genlock lock file descriptor and the lock
57      * handle are stored in the buffer_handle.
58      *
59      * @param: handle of the buffer
60      * @return error status.
61      */
62     genlock_status_t genlock_create_lock(native_handle_t *buffer_handle);
63 
64 
65     /*
66      * Release a genlock lock associated with the handle.
67      *
68      * @param: handle of the buffer
69      * @return error status.
70      */
71     genlock_status_t genlock_release_lock(native_handle_t *buffer_handle);
72 
73     /*
74      * Attach a lock to the buffer handle passed via an IPC.
75      *
76      * @param: handle of the buffer
77      * @return error status.
78      */
79     genlock_status_t genlock_attach_lock(native_handle_t *buffer_handle);
80 
81     /*
82      * Lock the buffer specified by the buffer handle. The lock held by the
83      * buffer is specified by the lockType. This function will block if a write
84      * lock is requested on the buffer which has previously been locked for a
85      * read or write operation. A buffer can be locked by multiple clients for
86      * read. An optional timeout value can be specified.
87      * By default, there is no timeout.
88      *
89      * @param: handle of the buffer
90      * @param: type of lock to be acquired by the buffer.
91      * @param: timeout value in ms. GENLOCK_MAX_TIMEOUT is the maximum timeout
92      *         value.
93      * @return error status.
94      */
95     genlock_status_t genlock_lock_buffer(native_handle_t *buffer_handle,
96                                          genlock_lock_type_t lockType,
97                                          int timeout);
98 
99     /*
100      * Unlocks a buffer that has previously been locked by the client.
101      *
102      * @param: handle of the buffer to be unlocked.
103      * @return: error status.
104      */
105     genlock_status_t genlock_unlock_buffer(native_handle_t *buffer_handle);
106 
107     /*
108      * Blocks the calling process until the lock held on the handle is unlocked.
109      *
110      * @param: handle of the buffer
111      * @param: timeout value for the wait.
112      * return: error status.
113      */
114     genlock_status_t genlock_wait(native_handle_t *buffer_handle, int timeout);
115 
116     /*
117      * Convert a write lock that we own to a read lock
118      *
119      * @param: handle of the buffer
120      * @param: timeout value for the wait.
121      * return: error status.
122      */
123     genlock_status_t genlock_write_to_read(native_handle_t *buffer_handle,
124                                            int timeout);
125 
126 #ifdef __cplusplus
127 }
128 #endif
129 #endif
130