Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 1 | /* |
Ramkumar Radhakrishnan | 7ebf034 | 2015-01-20 15:00:46 -0800 | [diff] [blame] | 2 | * Copyright (c) 2014 - 2015, The Linux Foundation. All rights reserved. |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 3 | * |
Ramkumar Radhakrishnan | 7ebf034 | 2015-01-20 15:00:46 -0800 | [diff] [blame] | 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. |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 16 | * |
Ramkumar Radhakrishnan | 7ebf034 | 2015-01-20 15:00:46 -0800 | [diff] [blame] | 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. |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 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 | |
Ramkumar Radhakrishnan | d33432e | 2014-11-16 13:23:19 -0800 | [diff] [blame] | 42 | #include "display_interface.h" |
Dileep Marchya | 3ffb470 | 2014-12-04 16:31:37 -0800 | [diff] [blame] | 43 | #include "sde_types.h" |
Ramkumar Radhakrishnan | befbdbe | 2015-01-14 20:14:40 -0800 | [diff] [blame] | 44 | #include "buffer_allocator.h" |
| 45 | |
| 46 | class BufferSyncHandler; |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 47 | |
Dileep Marchya | 3ffb470 | 2014-12-04 16:31:37 -0800 | [diff] [blame] | 48 | /*! @brief Display engine interface version. |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 49 | |
Dileep Marchya | 3ffb470 | 2014-12-04 16:31:37 -0800 | [diff] [blame] | 50 | @details Display engine interfaces are version tagged to maintain backward compatibility. This |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 51 | version is supplied as a default argument during display core initialization. |
| 52 | |
Dileep Marchya | 3ffb470 | 2014-12-04 16:31:37 -0800 | [diff] [blame] | 53 | Client may use an older version of interfaces and link to a higher version of display engine |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 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 | |
Dileep Marchya | 3ffb470 | 2014-12-04 16:31:37 -0800 | [diff] [blame] | 59 | Display engine interfaces follow default data structures alignment. Client must not override the |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 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 | */ |
Dileep Marchya | 3ffb470 | 2014-12-04 16:31:37 -0800 | [diff] [blame] | 68 | #define SDE_REVISION_MAJOR (1) |
| 69 | #define SDE_REVISION_MINOR (0) |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 70 | |
Dileep Marchya | 3ffb470 | 2014-12-04 16:31:37 -0800 | [diff] [blame] | 71 | #define SDE_VERSION_TAG ((uint32_t) ((SDE_REVISION_MAJOR << 24) | (SDE_REVISION_MINOR << 16) | \ |
| 72 | (sizeof(SDECompatibility) << 8) | sizeof(int *))) |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 73 | |
| 74 | namespace sde { |
| 75 | |
Ramkumar Radhakrishnan | 7ebf034 | 2015-01-20 15:00:46 -0800 | [diff] [blame] | 76 | /*! @brief Forward declaration for debug handler. |
| 77 | */ |
| 78 | class DebugHandler; |
| 79 | |
| 80 | |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 81 | /*! @brief Event data associated with hotplug event. |
| 82 | |
| 83 | @sa CoreEventHandler::Hotplug |
| 84 | */ |
| 85 | struct CoreEventHotplug { |
| 86 | bool connected; //!< True when device is connected. |
| 87 | |
| 88 | CoreEventHotplug() : connected(false) { } |
| 89 | }; |
| 90 | |
| 91 | /*! @brief Display core event handler implemented by the client. |
| 92 | |
| 93 | @details This class declares prototype for display core event handler methods which must be |
| 94 | implemented by the client. Display core will use these methods to notify events to the client. |
| 95 | Client must post heavy-weight event handling to a separate thread and unblock display core thread |
| 96 | instantly. |
| 97 | |
| 98 | @sa CoreInterface::CreateCore |
| 99 | */ |
| 100 | class CoreEventHandler { |
| 101 | public: |
| 102 | /*! @brief Event handler for Hotplug event. |
| 103 | |
| 104 | @details Event generated when a display device is connected or disconnected. Applicable to |
| 105 | detachable displays only. |
| 106 | |
| 107 | @param[in] \link CoreEventHotplug \endlink |
| 108 | |
| 109 | @return \link DisplayError \endlink |
| 110 | */ |
| 111 | virtual DisplayError Hotplug(const CoreEventHotplug &hotplug) = 0; |
| 112 | |
| 113 | protected: |
| 114 | virtual ~CoreEventHandler() { } |
| 115 | }; |
| 116 | |
| 117 | /*! @brief Display core interface. |
| 118 | |
| 119 | @details This class defines display core interfaces. It contains methods which client shall use |
| 120 | to create/destroy different display devices. This interface is created during display core |
| 121 | CreateCore() and remains valid until DestroyCore(). |
| 122 | |
| 123 | @sa CoreInterface::CreateCore |
| 124 | @sa CoreInterface::DestroyCore |
| 125 | */ |
| 126 | class CoreInterface { |
| 127 | public: |
| 128 | /*! @brief Method to create and get handle to display core interface. |
| 129 | |
| 130 | @details This method is the entry point into the display core. Client can create and operate on |
| 131 | different display devices only through a valid interface handle obtained using this method. An |
| 132 | object of display core is created and handle to this object is returned via output parameter. |
| 133 | This interface shall be called only once. |
| 134 | |
| 135 | @param[in] event_handler \link CoreEventHandler \endlink |
Ramkumar Radhakrishnan | 7ebf034 | 2015-01-20 15:00:46 -0800 | [diff] [blame] | 136 | @param[in] debug_handler \link DebugHandler \endlink |
Ramkumar Radhakrishnan | befbdbe | 2015-01-14 20:14:40 -0800 | [diff] [blame] | 137 | @param[in] buffer_allocator \link BufferAllocator \endlink |
| 138 | @param[in] buffer_sync_handler \link BufferSyncHandler \endlink |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 139 | @param[out] interface \link CoreInterface \endlink |
Dileep Marchya | 3ffb470 | 2014-12-04 16:31:37 -0800 | [diff] [blame] | 140 | @param[in] version \link SDE_VERSION_TAG \endlink. Client must not override this argument. |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 141 | |
| 142 | @return \link DisplayError \endlink |
| 143 | |
| 144 | @sa DestroyCore |
| 145 | */ |
Ramkumar Radhakrishnan | 7ebf034 | 2015-01-20 15:00:46 -0800 | [diff] [blame] | 146 | static DisplayError CreateCore(CoreEventHandler *event_handler, DebugHandler *debug_handler, |
Ramkumar Radhakrishnan | befbdbe | 2015-01-14 20:14:40 -0800 | [diff] [blame] | 147 | BufferAllocator *buffer_allocator, |
| 148 | BufferSyncHandler *buffer_sync_handler, CoreInterface **interface, |
| 149 | uint32_t version = SDE_VERSION_TAG); |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 150 | |
| 151 | /*! @brief Method to release handle to display core interface. |
| 152 | |
| 153 | @details The object of corresponding display core is destroyed when this method is invoked. |
| 154 | Client must explicitly destroy all created display device objects associated with this handle |
| 155 | before invoking this method. |
| 156 | |
| 157 | @param[in] interface \link CoreInterface \endlink |
| 158 | |
| 159 | @return \link DisplayError \endlink |
| 160 | |
| 161 | @sa CreateCore |
| 162 | */ |
| 163 | static DisplayError DestroyCore(); |
| 164 | |
| 165 | /*! @brief Method to create a display device for a given type. |
| 166 | |
| 167 | @details Client shall use this method to create each of the connected display type. A handle to |
| 168 | interface associated with this object is returned via output parameter which can be used to |
| 169 | interact further with the display device. |
| 170 | |
Ramkumar Radhakrishnan | d33432e | 2014-11-16 13:23:19 -0800 | [diff] [blame] | 171 | @param[in] type \link DisplayType \endlink |
| 172 | @param[in] event_handler \link DisplayEventHandler \endlink |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 173 | @param[out] interface \link DisplayInterface \endlink |
| 174 | |
| 175 | @return \link DisplayError \endlink |
| 176 | |
Ramkumar Radhakrishnan | d33432e | 2014-11-16 13:23:19 -0800 | [diff] [blame] | 177 | @sa DestroyDisplay |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 178 | */ |
Ramkumar Radhakrishnan | d33432e | 2014-11-16 13:23:19 -0800 | [diff] [blame] | 179 | virtual DisplayError CreateDisplay(DisplayType type, DisplayEventHandler *event_handler, |
Dileep Marchya | 3ffb470 | 2014-12-04 16:31:37 -0800 | [diff] [blame] | 180 | DisplayInterface **interface) = 0; |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 181 | |
| 182 | /*! @brief Method to destroy a display device. |
| 183 | |
| 184 | @details Client shall use this method to destroy each of the created display device objects. |
| 185 | |
| 186 | @param[in] interface \link DisplayInterface \endlink |
| 187 | |
| 188 | @return \link DisplayError \endlink |
| 189 | |
Ramkumar Radhakrishnan | d33432e | 2014-11-16 13:23:19 -0800 | [diff] [blame] | 190 | @sa CreateDisplay |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 191 | */ |
Ramkumar Radhakrishnan | d33432e | 2014-11-16 13:23:19 -0800 | [diff] [blame] | 192 | virtual DisplayError DestroyDisplay(DisplayInterface *interface) = 0; |
Dileep Marchya | f9ba485 | 2014-10-24 19:56:57 -0700 | [diff] [blame] | 193 | |
| 194 | protected: |
| 195 | virtual ~CoreInterface() { } |
| 196 | }; |
| 197 | |
| 198 | } // namespace sde |
| 199 | |
| 200 | #endif // __CORE_INTERFACE_H__ |
| 201 | |