1 /*
2 * Copyright (c) 2014 - 2016, 2018 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 #include <map>
42 #include <vector>
43 
44 #include "display_interface.h"
45 #include "sdm_types.h"
46 #include "buffer_allocator.h"
47 #include "buffer_sync_handler.h"
48 #include "socket_handler.h"
49 
50 /*! @brief Display manager interface version.
51 
52   @details Display manager interfaces are version tagged to maintain backward compatibility. This
53   version is supplied as a default argument during display core initialization.
54 
55   Client may use an older version of interfaces and link to a higher version of display manager
56   library, but vice versa is not allowed.
57 
58   A 32-bit client must use 32-bit display core library and a 64-bit client must use 64-bit display
59   core library.
60 
61   Display manager interfaces follow default data structures alignment. Client must not override the
62   default padding rules while using these interfaces.
63 
64   @warning It is assumed that client upgrades or downgrades display core interface all at once
65   and recompile all binaries which use these interfaces. Mix and match of these interfaces can
66   lead to unpredictable behaviour.
67 
68   @sa CoreInterface::CreateCore
69 */
70 #define SDM_REVISION_MAJOR (1)
71 #define SDM_REVISION_MINOR (0)
72 
73 #define SDM_VERSION_TAG ((uint32_t) ((SDM_REVISION_MAJOR << 24) | (SDM_REVISION_MINOR << 16) | \
74                                     (sizeof(SDMCompatibility) << 8) | sizeof(int *)))
75 
76 namespace sdm {
77 
78 /*! @brief This enum represents max bandwidth limit mode.
79 
80   @sa DisplayInterface::SetMaxBandwidthMode
81 */
82 enum HWBwModes {
83   kBwDefault,      //!< Default state. No change in device bandwidth limit.
84   kBwCamera,       //!< Camera is on. Bandwidth limit should be reduced accordingly.
85   kBwVFlip,        //!< VFlip is required. Reduce bandwidth limit accordingly.
86   kBwHFlip,        //!< HFlip is required.  Reduce bandwidth limit accordingly.
87   kBwModeMax,      //!< Limiter for maximum available bandwidth modes.
88 };
89 
90 /*! @brief Information on hardware for the first display
91 
92   @details This structure returns the display type of the first display on the device
93   (internal display or HDMI etc) and whether it is currently connected.
94 */
95 struct HWDisplayInterfaceInfo {
96   DisplayType type = kDisplayTypeMax;
97   bool is_connected = false;
98 };
99 
100 /*! @brief Information about a single display/monitor/screen
101 
102   @details This structure returns the display configuration and status of a single display. A
103   list of this structure type 'HWDisplaysInfo' is used to return information on all available
104   displays. See \link HWDisplaysInfo \endlink
105 */
106 struct HWDisplayInfo {
107   int32_t display_id = -1;                     //!< ID of this display (Display ID).
108   DisplayType display_type = kDisplayTypeMax;  //!< Type of display: BuiltIn/Pluggable/Virtual
109   bool is_connected = false;                   //!< Connection status of the display.
110   bool is_primary = false;                     //!< True only if this is the main display of the
111                                                //!< device.
112   bool is_wb_ubwc_supported = true;            //!< check hardware wb ubwc support
113 };
114 
115 /*! @brief Information on all displays as a map with display_id as key.
116 
117   @details This map returns the display configuration and status of all displays.
118 */
119 typedef std::map<int32_t, HWDisplayInfo> HWDisplaysInfo;
120 
121 /*! @brief Display core interface.
122 
123   @details This class defines display core interfaces. It contains methods which client shall use
124   to create/destroy different display devices. This interface is created during display core
125   CreateCore() and remains valid until DestroyCore().
126 
127   @sa CoreInterface::CreateCore
128   @sa CoreInterface::DestroyCore
129 */
130 class CoreInterface {
131  public:
132   /*! @brief Method to create and get handle to display core interface.
133 
134     @details This method is the entry point into the display core. Client can create and operate on
135     different display devices only through a valid interface handle obtained using this method. An
136     object of display core is created and handle to this object is returned via output parameter.
137     This interface shall be called only once.
138 
139     @param[in] buffer_allocator \link BufferAllocator \endlink
140     @param[in] buffer_sync_handler \link BufferSyncHandler \endlink
141     @param[in] socket_handler \link SocketHandler \endlink
142     @param[out] interface \link CoreInterface \endlink
143     @param[in] version \link SDM_VERSION_TAG \endlink. Client must not override this argument.
144 
145     @return \link DisplayError \endlink
146 
147     @sa DestroyCore
148   */
149   static DisplayError CreateCore(BufferAllocator *buffer_allocator,
150                                  BufferSyncHandler *buffer_sync_handler,
151                                  SocketHandler *socket_handler, CoreInterface **interface,
152                                  uint32_t version = SDM_VERSION_TAG);
153 
154   /*! @brief Method to release handle to display core interface.
155 
156     @details The object of corresponding display core is destroyed when this method is invoked.
157     Client must explicitly destroy all created display device objects associated with this handle
158     before invoking this method.
159 
160     @param[in] interface \link CoreInterface \endlink
161 
162     @return \link DisplayError \endlink
163 
164     @sa CreateCore
165   */
166   static DisplayError DestroyCore();
167 
168   /*! @brief Method to create a display device for a given type.
169 
170     @details Client shall use this method to create each of the connected display type. A handle to
171     interface associated with this object is returned via output parameter which can be used to
172     interact further with the display device.
173 
174     @param[in] type \link DisplayType \endlink
175     @param[in] event_handler \link DisplayEventHandler \endlink
176     @param[out] interface \link DisplayInterface \endlink
177 
178     @return \link DisplayError \endlink
179 
180     @sa DestroyDisplay
181   */
182   virtual DisplayError CreateDisplay(DisplayType type, DisplayEventHandler *event_handler,
183                                      DisplayInterface **interface) = 0;
184 
185   /*! @brief Method to create a display device for a given display ID.
186 
187     @details Client shall use this method to create a DisplayInterface to a discovered display
188     identified by its display ID. A handle to the DisplayInterface is returned via the 'interface'
189     output parameter which can be used to interact further with the display device. Displays and
190     their IDs must be discovered using GetDisplaysStatus().
191 
192     @param[in] display_id A display ID got from \link GetDisplaysStatus() \endlink
193     @param[in] event_handler \link DisplayEventHandler \endlink
194     @param[out] interface \link DisplayInterface \endlink
195 
196     @return \link DisplayError \endlink
197 
198     @sa DestroyDisplay
199   */
200   virtual DisplayError CreateDisplay(int32_t display_id, DisplayEventHandler *event_handler,
201                                      DisplayInterface **interface) = 0;
202 
203   /*! @brief Method to destroy a display device.
204 
205     @details Client shall use this method to destroy each of the created display device objects.
206 
207     @param[in] interface \link DisplayInterface \endlink
208 
209     @return \link DisplayError \endlink
210 
211     @sa CreateDisplay
212   */
213   virtual DisplayError DestroyDisplay(DisplayInterface *interface) = 0;
214 
215   /*! @brief Method to update the bandwidth limit as per given mode.
216 
217     @param[in] mode indicate the mode or use case
218 
219     @return \link DisplayError \endlink
220   */
221   virtual DisplayError SetMaxBandwidthMode(HWBwModes mode) = 0;
222 
223   /*! @brief Method to get characteristics of the first display.
224 
225     @details Client shall use this method to determine if the first display is HDMI, and whether
226     it is currently connected.
227 
228     @param[in] hw_disp_info structure that this method will fill up with info.
229 
230     @return \link DisplayError \endlink
231   */
232   virtual DisplayError GetFirstDisplayInterfaceType(HWDisplayInterfaceInfo *hw_disp_info) = 0;
233 
234   /*! @brief Method to get an up-to-date list of all available displays.
235 
236     @details Client shall use this method to get the updated list of all available displays and
237     their properties, usually in response to a hot-plug event. Client must use one of the returned
238     HWDisplayInfo::display_ids when using CreateDisplay(int32_t display_id, ...) to create the
239     DisplayInterface to the display.
240 
241     @param[out] hw_displays_info \link HWDisplaysInfo \endlink which is a map of \link HWDisplayInfo
242     \endlink structures with display_id as the key.
243 
244     @return \link DisplayError \endlink
245   */
246   virtual DisplayError GetDisplaysStatus(HWDisplaysInfo *hw_displays_info) = 0;
247 
248   /*! @brief Method to get the maximum supported number of concurrent displays of a particular type.
249 
250     @details Client shall use this method to get the maximum number of DisplayInterface instances
251     that can be created for a particular \link DisplayType \endlink display. For the maximum
252     number of concurrent DisplayInterfaces supported of all types, call with type kDisplayTypeMax.
253 
254     @param[in] type Type of display: BuiltIn/Pluggable/Virtual/kDisplayTypeMax
255     key.
256 
257     @param[out] max_displays Maximum number of DisplayInterface instances possible.
258 
259     @return \link DisplayError \endlink
260   */
261   virtual DisplayError GetMaxDisplaysSupported(DisplayType type, int32_t *max_displays) = 0;
262 
263  protected:
~CoreInterface()264   virtual ~CoreInterface() { }
265 };
266 
267 }  // namespace sdm
268 
269 #endif  // __CORE_INTERFACE_H__
270 
271