client/tdm_client.h

   1 /**************************************************************************
   2
   3 libtdm
   4
   5 Copyright 2015 Samsung Electronics co., Ltd. All Rights Reserved.
   6
   7 Contact: Eunchul Kim <chulspro.kim@samsung.com>,
   8          JinYoung Jeon <jy0.jeon@samsung.com>,
   9          Taeheon Kim <th908.kim@samsung.com>,
  10          YoungJun Cho <yj44.cho@samsung.com>,
  11          SooChan Lim <sc1.lim@samsung.com>,
  12          Boram Park <sc1.lim@samsung.com>
  13
  14 Permission is hereby granted, free of charge, to any person obtaining a
  15 copy of this software and associated documentation files (the
  16 "Software"), to deal in the Software without restriction, including
  17 without limitation the rights to use, copy, modify, merge, publish,
  18 distribute, sub license, and/or sell copies of the Software, and to
  19 permit persons to whom the Software is furnished to do so, subject to
  20 the following conditions:
  21
  22 The above copyright notice and this permission notice (including the
  23 next paragraph) shall be included in all copies or substantial portions
  24 of the Software.
  25
  26 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  27 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  28 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  29 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
  30 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  31 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  32 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  33
  34 **************************************************************************/
  35
  36 #ifndef _TDM_CLIENT_H_
  37 #define _TDM_CLIENT_H_
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /**
  44  * @file tdm_client.h
  45  * @brief The header file for a client of TDM.
  46  * @par Example
  47  * @code
  48    #include <tdm_client.h>    //for a client of TDM
  49  * @endcode
  50  */
  51
  52 /**
  53  * @brief The client error enumeration
  54  */
  55 typedef enum
  56 {
  57         TDM_CLIENT_ERROR_NONE                  = 0,  /**< none */
  58         TDM_CLIENT_ERROR_OPERATION_FAILED      = -1, /**< operaion failed */
  59         TDM_CLIENT_ERROR_INVALID_PARAMETER     = -2, /**< wrong input parameter */
  60         TDM_CLIENT_ERROR_PERMISSION_DENIED     = -3, /**< access denied */
  61         TDM_CLIENT_ERROR_OUT_OF_MEMORY         = -4, /**< no free memory */
  62         TDM_CLIENT_ERROR_DPMS_OFF              = -5, /**< dpms off */
  63 } tdm_client_error;
  64
  65 /**
  66  * @brief The TDM client object
  67  */
  68 typedef void *tdm_client;
  69
  70 /**
  71  * @brief The client vblank handler
  72  * @see #tdm_client_wait_vblank
  73  */
  74 typedef void
  75 (*tdm_client_vblank_handler)(unsigned int sequence, unsigned int tv_sec,
  76                              unsigned int tv_usec, void *user_data);
  77
  78 /**
  79  * @brief Create a TDM client object.
  80  * @param[out] error #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value.
  81  * @return A TDM client object if success. Otherwise, NULL.
  82  * @see #tdm_client_destroy
  83  */
  84 tdm_client*
  85 tdm_client_create(tdm_client_error *error);
  86
  87 /**
  88  * @brief Destroy a TDM client object
  89  * @param[in] client A TDM client object
  90  * @see #tdm_client_create
  91  */
  92 void
  93 tdm_client_destroy(tdm_client *client);
  94
  95 /**
  96  * @brief Get the file descriptor
  97  * @param[in] client A TDM client object
  98  * @param[out] fd The file descriptor
  99  * @return #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value.
 100  * @see #tdm_client_handle_events
 101  * @par Example
 102  * @code
 103    #include <tdm_client.h>    //for a client of TDM
 104
 105    err = tdm_client_get_fd(client, &fd);
 106    if (err != TDM_CLIENT_ERROR_NONE) {
 107        //error handling
 108    }
 109
 110    fds.events = POLLIN;
 111    fds.fd = fd;
 112    fds.revents = 0;
 113
 114    while(1) {
 115       ret = poll(&fds, 1, -1);
 116       if (ret < 0) {
 117          if (errno == EBUSY)
 118             continue;
 119          else {
 120             //error handling
 121          }
 122       }
 123
 124       err = tdm_client_handle_events(client);
 125       if (err != TDM_CLIENT_ERROR_NONE) {
 126           //error handling
 127       }
 128    }
 129  * @endcode
 130  */
 131 tdm_client_error
 132 tdm_client_get_fd(tdm_client *client, int *fd);
 133
 134 /**
 135  * @brief Handle the events of the given file descriptor
 136  * @param[in] client A TDM client object
 137  * @return #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value.
 138  * @see #tdm_client_get_fd
 139  */
 140 tdm_client_error
 141 tdm_client_handle_events(tdm_client *client);
 142
 143 /**
 144  * @brief Wait for VBLANK
 145  * @details After interval vblanks, a client vblank handler will be called.
 146  * If 'sw_timer' param is 1 in case of DPMS off, TDM will use the SW timer and
 147  * call a client vblank handler. Otherwise, this function will return error.
 148  * @param[in] client A TDM client object
 149  * @param[in] name The name of a TDM output
 150  * @param[in] sw_timer 0: not using SW timer, 1: using SW timer
 151  * @param[in] interval vblank interval
 152  * @param[in] sync 0: asynchronous, 1:synchronous
 153  * @param[in] func A client vblank handler
 154  * @param[in] user_data The user data
 155  * @return #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value.
 156  * @see #tdm_client_vblank_handler
 157  */
 158 tdm_client_error
 159 tdm_client_wait_vblank(tdm_client *client, char *name,
 160                        int sw_timer, int interval, int sync,
 161                        tdm_client_vblank_handler func, void *user_data);
 162
 163 #ifdef __cplusplus
 164 }
 165 #endif
 166
 167 #endif /* _TDM_CLIENT_H_ */