Home | History | Annotate | Download | only in libgenlock 
      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