1 /* 2 * Copyright (c) 2014 - 2016, 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 /*! @file core_interface.h 31 @brief Interface file for core of the display subsystem. 32 33 @details Display core is primarily used for loading and unloading different display device 34 components viz primary, external and virtual. Display core is a statically linked library which 35 runs in caller's process context. 36 */ 37 #ifndef __CORE_INTERFACE_H__ 38 #define __CORE_INTERFACE_H__ 39 40 #include <stdint.h> 41 42 #include "display_interface.h" 43 #include "sdm_types.h" 44 #include "buffer_allocator.h" 45 #include "buffer_sync_handler.h" 46 #include "socket_handler.h" 47 48 /*! @brief Display manager interface version. 49 50 @details Display manager interfaces are version tagged to maintain backward compatibility. This 51 version is supplied as a default argument during display core initialization. 52 53 Client may use an older version of interfaces and link to a higher version of display manager 54 library, but vice versa is not allowed. 55 56 A 32-bit client must use 32-bit display core library and a 64-bit client must use 64-bit display 57 core library. 58 59 Display manager interfaces follow default data structures alignment. Client must not override the 60 default padding rules while using these interfaces. 61 62 @warning It is assumed that client upgrades or downgrades display core interface all at once 63 and recompile all binaries which use these interfaces. Mix and match of these interfaces can 64 lead to unpredictable behaviour. 65 66 @sa CoreInterface::CreateCore 67 */ 68 #define SDM_REVISION_MAJOR (1) 69 #define SDM_REVISION_MINOR (0) 70 71 #define SDM_VERSION_TAG ((uint32_t) ((SDM_REVISION_MAJOR << 24) | (SDM_REVISION_MINOR << 16) | \ 72 (sizeof(SDMCompatibility) << 8) | sizeof(int *))) 73 74 namespace sdm { 75 76 /*! @brief Forward declaration for debug handler. 77 */ 78 class DebugHandler; 79 80 /*! @brief This enum represents max bandwidth limit mode. 81 82 @sa DisplayInterface::SetMaxBandwidthMode 83 */ 84 enum HWBwModes { 85 kBwDefault, //!< Default state. No change in device bandwidth limit. 86 kBwCamera, //!< Camera is on. Bandwidth limit should be reduced accordingly. 87 kBwVFlip, //!< VFlip is required. Reduce bandwidth limit accordingly. 88 kBwHFlip, //!< HFlip is required. Reduce bandwidth limit accordingly. 89 kBwModeMax, //!< Limiter for maximum available bandwidth modes. 90 }; 91 92 93 /*! @brief Information on hardware for the first display 94 95 @details This structure returns the display type of the first display on the device 96 (internal display or HDMI etc) and whether it is currently connected, 97 98 */ 99 struct HWDisplayInterfaceInfo { 100 DisplayType type; 101 bool is_connected; 102 }; 103 104 /*! @brief Display core interface. 105 106 @details This class defines display core interfaces. It contains methods which client shall use 107 to create/destroy different display devices. This interface is created during display core 108 CreateCore() and remains valid until DestroyCore(). 109 110 @sa CoreInterface::CreateCore 111 @sa CoreInterface::DestroyCore 112 */ 113 class CoreInterface { 114 public: 115 /*! @brief Method to create and get handle to display core interface. 116 117 @details This method is the entry point into the display core. Client can create and operate on 118 different display devices only through a valid interface handle obtained using this method. An 119 object of display core is created and handle to this object is returned via output parameter. 120 This interface shall be called only once. 121 122 @param[in] debug_handler \link DebugHandler \endlink 123 @param[in] buffer_allocator \link BufferAllocator \endlink 124 @param[in] buffer_sync_handler \link BufferSyncHandler \endlink 125 @param[out] interface \link CoreInterface \endlink 126 @param[in] version \link SDM_VERSION_TAG \endlink. Client must not override this argument. 127 128 @return \link DisplayError \endlink 129 130 @sa DestroyCore 131 */ 132 static DisplayError CreateCore(DebugHandler *debug_handler, BufferAllocator *buffer_allocator, 133 BufferSyncHandler *buffer_sync_handler, CoreInterface **interface, 134 uint32_t version = SDM_VERSION_TAG); 135 136 /*! @brief Method to create and get handle to display core interface. 137 138 @details This method is the entry point into the display core. Client can create and operate on 139 different display devices only through a valid interface handle obtained using this method. An 140 object of display core is created and handle to this object is returned via output parameter. 141 This interface shall be called only once. 142 143 @param[in] debug_handler \link DebugHandler \endlink 144 @param[in] buffer_allocator \link BufferAllocator \endlink 145 @param[in] buffer_sync_handler \link BufferSyncHandler \endlink 146 @param[in] socket_handler \link SocketHandler \endlink 147 @param[out] interface \link CoreInterface \endlink 148 @param[in] version \link SDM_VERSION_TAG \endlink. Client must not override this argument. 149 150 @return \link DisplayError \endlink 151 152 @sa DestroyCore 153 */ 154 static DisplayError CreateCore(DebugHandler *debug_handler, BufferAllocator *buffer_allocator, 155 BufferSyncHandler *buffer_sync_handler, 156 SocketHandler *socket_handler, CoreInterface **interface, 157 uint32_t version = SDM_VERSION_TAG); 158 159 /*! @brief Method to release handle to display core interface. 160 161 @details The object of corresponding display core is destroyed when this method is invoked. 162 Client must explicitly destroy all created display device objects associated with this handle 163 before invoking this method. 164 165 @param[in] interface \link CoreInterface \endlink 166 167 @return \link DisplayError \endlink 168 169 @sa CreateCore 170 */ 171 static DisplayError DestroyCore(); 172 173 /*! @brief Method to create a display device for a given type. 174 175 @details Client shall use this method to create each of the connected display type. A handle to 176 interface associated with this object is returned via output parameter which can be used to 177 interact further with the display device. 178 179 @param[in] type \link DisplayType \endlink 180 @param[in] event_handler \link DisplayEventHandler \endlink 181 @param[out] interface \link DisplayInterface \endlink 182 183 @return \link DisplayError \endlink 184 185 @sa DestroyDisplay 186 */ 187 virtual DisplayError CreateDisplay(DisplayType type, DisplayEventHandler *event_handler, 188 DisplayInterface **interface) = 0; 189 190 /*! @brief Method to destroy a display device. 191 192 @details Client shall use this method to destroy each of the created display device objects. 193 194 @param[in] interface \link DisplayInterface \endlink 195 196 @return \link DisplayError \endlink 197 198 @sa CreateDisplay 199 */ 200 virtual DisplayError DestroyDisplay(DisplayInterface *interface) = 0; 201 202 /*! @brief Method to update the bandwidth limit as per given mode. 203 204 @param[in] mode indicate the mode or use case 205 206 @return \link DisplayError \endlink 207 208 */ 209 virtual DisplayError SetMaxBandwidthMode(HWBwModes mode) = 0; 210 211 /*! @brief Method to get characteristics of the first display. 212 213 @details Client shall use this method to determine if the first display is HDMI, and whether 214 it is currently connected. 215 216 @param[in] hw_disp_info structure that this method will fill up with info. 217 218 @return \link DisplayError \endlink 219 220 */ 221 virtual DisplayError GetFirstDisplayInterfaceType(HWDisplayInterfaceInfo *hw_disp_info) = 0; 222 223 224 protected: 225 virtual ~CoreInterface() { } 226 }; 227 228 } // namespace sdm 229 230 #endif // __CORE_INTERFACE_H__ 231 232
