1 /* 2 * Copyright 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.media.tv.tunerresourcemanager; 18 19 import android.media.tv.tuner.TunerFrontendInfo; 20 import android.media.tv.tunerresourcemanager.CasSessionRequest; 21 import android.media.tv.tunerresourcemanager.IResourcesReclaimListener; 22 import android.media.tv.tunerresourcemanager.ResourceClientProfile; 23 import android.media.tv.tunerresourcemanager.TunerCiCamRequest; 24 import android.media.tv.tunerresourcemanager.TunerDemuxRequest; 25 import android.media.tv.tunerresourcemanager.TunerDescramblerRequest; 26 import android.media.tv.tunerresourcemanager.TunerFrontendRequest; 27 import android.media.tv.tunerresourcemanager.TunerLnbRequest; 28 29 /** 30 * Interface of the Tuner Resource Manager. It manages resources used by TV Tuners. 31 * <p>Resources include: 32 * <ul> 33 * <li>TunerFrontend {@link android.media.tv.tuner.frontend}. 34 * <li>TunerLnb {@link android.media.tv.tuner.Lnb}. 35 * <li>MediaCas {@link android.media.MediaCas}. 36 * <li>TvInputHardware {@link android.media.tv.TvInputHardwareInfo}. 37 * <ul> 38 * 39 * <p>Expected workflow is: 40 * <ul> 41 * <li>Tuner Java/MediaCas/TIF update resources of the current device with TRM. 42 * <li>Client registers its profile through {@link #registerClientProfile(ResourceClientProfile, 43 * IResourcesReclaimListener, int[])}. 44 * <li>Client requests resources through request APIs. 45 * <li>If the resource needs to be handed to a higher priority client from a lower priority 46 * one, TRM calls IResourcesReclaimListener registered by the lower priority client to release 47 * the resource. 48 * <ul> 49 * 50 * @hide 51 */ 52 interface ITunerResourceManager { 53 /* 54 * This API is used by the client to register their profile with the Tuner Resource manager. 55 * 56 * <p>The profile contains information that can show the base priority score of the client. 57 * 58 * @param profile {@link ResourceClientProfile} profile of the current client 59 * @param listener {@link IResourcesReclaimListener} a callback to 60 * reclaim clients' resources when needed. 61 * @param clientId returns a clientId from the resource manager when the 62 * the client registers its profile. 63 */ registerClientProfile(in ResourceClientProfile profile, IResourcesReclaimListener listener, out int[] clientId)64 void registerClientProfile(in ResourceClientProfile profile, 65 IResourcesReclaimListener listener, out int[] clientId); 66 67 /* 68 * This API is used by the client to unregister their profile with the Tuner Resource manager. 69 * 70 * @param clientId the client id that needs to be unregistered. 71 */ unregisterClientProfile(in int clientId)72 void unregisterClientProfile(in int clientId); 73 74 /* 75 * Updates a registered client's priority and niceValue. 76 * 77 * @param clientId the id of the client that is updating its profile. 78 * @param priority the priority that the client would like to update to. 79 * @param niceValue the nice value that the client would like to update to. 80 * 81 * @return true if the update is successful. 82 */ updateClientPriority(in int clientId, in int priority, in int niceValue)83 boolean updateClientPriority(in int clientId, in int priority, in int niceValue); 84 85 /* 86 * Updates the available Frontend resources information on the current device. 87 * 88 * <p><strong>Note:</strong> This update must happen before the first 89 * {@link #requestFrontend(TunerFrontendRequest,int[])} and {@link #releaseFrontend(int, int)} 90 * call. 91 * 92 * @param infos an array of the available {@link TunerFrontendInfo} information. 93 */ setFrontendInfoList(in TunerFrontendInfo[] infos)94 void setFrontendInfoList(in TunerFrontendInfo[] infos); 95 96 /* 97 * Updates the available Cas resource information on the current device. 98 * 99 * <p><strong>Note:</strong> This update must happen before the first 100 * {@link #requestCasSession(CasSessionRequest, int[])} and {@link #releaseCasSession(int, int)} 101 * call. 102 * 103 * @param casSystemId id of the updating CAS system. 104 * @param maxSessionNum the max session number of the CAS system that is updated. 105 */ updateCasInfo(in int casSystemId, in int maxSessionNum)106 void updateCasInfo(in int casSystemId, in int maxSessionNum); 107 108 /* 109 * Updates the available Lnb resource information on the current device. 110 * 111 * <p><strong>Note:</strong> This update must happen before the first 112 * {@link #requestLnb(TunerLnbRequest, int[])} and {@link #releaseLnb(int, int)} call. 113 * 114 * @param lnbIds ids of the updating lnbs. 115 */ setLnbInfoList(in int[] lnbIds)116 void setLnbInfoList(in int[] lnbIds); 117 118 /* 119 * This API is used by the Tuner framework to request an available frontend from the TunerHAL. 120 * 121 * <p>There are three possible scenarios: 122 * <ul> 123 * <li>If there is frontend available, the API would send the id back. 124 * 125 * <li>If no Frontend is available but the current request info can show higher priority than 126 * other uses of Frontend, the API will send 127 * {@link IResourcesReclaimListener#onReclaimResources()} to the {@link Tuner}. Tuner would 128 * handle the resource reclaim on the holder of lower priority and notify the holder of its 129 * resource loss. 130 * 131 * <li>If no frontend can be granted, the API would return false. 132 * <ul> 133 * 134 * <p><strong>Note:</strong> {@link #setFrontendInfoList(TunerFrontendInfo[])} must be called 135 * before this request. 136 * 137 * @param request {@link TunerFrontendRequest} information of the current request. 138 * @param frontendHandle a one-element array to return the granted frontendHandle. 139 * 140 * @return true if there is frontend granted. 141 */ requestFrontend(in TunerFrontendRequest request, out int[] frontendHandle)142 boolean requestFrontend(in TunerFrontendRequest request, out int[] frontendHandle); 143 144 /* 145 * Requests to share frontend with an existing client. 146 * 147 * <p><strong>Note:</strong> {@link #setFrontendInfoList(TunerFrontendInfo[])} must be called 148 * before this request. 149 * 150 * @param selfClientId the id of the client that sends the request. 151 * @param targetClientId the id of the client to share the frontend with. 152 */ shareFrontend(in int selfClientId, in int targetClientId)153 void shareFrontend(in int selfClientId, in int targetClientId); 154 155 /* 156 * This API is used by the Tuner framework to request an available demux from the TunerHAL. 157 * 158 * <p>There are three possible scenarios: 159 * <ul> 160 * <li>If there is demux available, the API would send the handle back. 161 * 162 * <li>If no Demux is available but the current request info can show higher priority than 163 * other uses of demuxes, the API will send 164 * {@link IResourcesReclaimListener#onReclaimResources()} to the {@link Tuner}. Tuner would 165 * handle the resource reclaim on the holder of lower priority and notify the holder of its 166 * resource loss. 167 * 168 * <li>If no demux can be granted, the API would return false. 169 * <ul> 170 * 171 * @param request {@link TunerDemuxRequest} information of the current request. 172 * @param demuxHandle a one-element array to return the granted demux handle. 173 * 174 * @return true if there is demux granted. 175 */ requestDemux(in TunerDemuxRequest request, out int[] demuxHandle)176 boolean requestDemux(in TunerDemuxRequest request, out int[] demuxHandle); 177 178 /* 179 * This API is used by the Tuner framework to request an available descrambler from the 180 * TunerHAL. 181 * 182 * <p>There are three possible scenarios: 183 * <ul> 184 * <li>If there is descrambler available, the API would send the handle back. 185 * 186 * <li>If no Descrambler is available but the current request info can show higher priority than 187 * other uses of Descrambler, the API will send 188 * {@link IResourcesReclaimListener#onReclaimResources()} to the {@link Tuner}. Tuner would 189 * handle the resource reclaim on the holder of lower priority and notify the holder of its 190 * resource loss. 191 * 192 * <li>If no Descrambler can be granted, the API would return false. 193 * <ul> 194 * 195 * @param request {@link TunerDescramblerRequest} information of the current request. 196 * @param descramblerHandle a one-element array to return the granted descrambler handle. 197 * 198 * @return true if there is Descrambler granted. 199 */ requestDescrambler(in TunerDescramblerRequest request, out int[] descramblerHandle)200 boolean requestDescrambler(in TunerDescramblerRequest request, out int[] descramblerHandle); 201 202 /* 203 * This API is used by the Tuner framework to request an available Cas session. This session 204 * needs to be under the CAS system with the id indicated in the {@code request}. 205 * 206 * <p>There are three possible scenarios: 207 * <ul> 208 * <li>If there is Cas session available, the API would send the id back. 209 * 210 * <li>If no Cas session is available but the current request info can show higher priority than 211 * other uses of the sessions under the requested CAS system, the API will send 212 * {@link ITunerResourceManagerCallback#onReclaimResources()} to the {@link Tuner}. Tuner would 213 * handle the resource reclaim on the holder of lower priority and notify the holder of its 214 * resource loss. 215 * 216 * <li>If no Cas session can be granted, the API would return false. 217 * <ul> 218 * 219 * <p><strong>Note:</strong> {@link #updateCasInfo(int, int)} must be called before this request. 220 * 221 * @param request {@link CasSessionRequest} information of the current request. 222 * @param casSessionHandle a one-element array to return the granted cas session handle. 223 * 224 * @return true if there is CAS session granted. 225 */ requestCasSession(in CasSessionRequest request, out int[] casSessionHandle)226 boolean requestCasSession(in CasSessionRequest request, out int[] casSessionHandle); 227 228 /* 229 * This API is used by the Tuner framework to request an available CuCam. 230 * 231 * <p>There are three possible scenarios: 232 * <ul> 233 * <li>If there is CiCam available, the API would send the handle back. 234 * 235 * <li>If no CiCma is available but the current request info can show higher priority than 236 * other uses of the ciCam, the API will send 237 * {@link ITunerResourceManagerCallback#onReclaimResources()} to the {@link Tuner}. Tuner would 238 * handle the resource reclaim on the holder of lower priority and notify the holder of its 239 * resource loss. 240 * 241 * <li>If no CiCam can be granted, the API would return false. 242 * <ul> 243 * 244 * <p><strong>Note:</strong> {@link #updateCasInfo(int, int)} must be called before this request. 245 * 246 * @param request {@link TunerCiCamRequest} information of the current request. 247 * @param ciCamHandle a one-element array to return the granted ciCam handle. 248 * 249 * @return true if there is CiCam granted. 250 */ requestCiCam(in TunerCiCamRequest request, out int[] ciCamHandle)251 boolean requestCiCam(in TunerCiCamRequest request, out int[] ciCamHandle); 252 253 /* 254 * This API is used by the Tuner framework to request an available Lnb from the TunerHAL. 255 * 256 * <p>There are three possible scenarios: 257 * <ul> 258 * <li>If there is Lnb available, the API would send the id back. 259 * 260 * <li>If no Lnb is available but the current request has a higher priority than other uses of 261 * lnbs, the API will send {@link ITunerResourceManagerCallback#onReclaimResources()} to the 262 * {@link Tuner}. Tuner would handle the resource reclaim on the holder of lower priority and 263 * notify the holder of its resource loss. 264 * 265 * <li>If no Lnb system can be granted, the API would return false. 266 * <ul> 267 * 268 * <p><strong>Note:</strong> {@link #setLnbInfos(int[])} must be called before this request. 269 * 270 * @param request {@link TunerLnbRequest} information of the current request. 271 * @param lnbHandle a one-element array to return the granted Lnb handle. 272 * 273 * @return true if there is Lnb granted. 274 */ requestLnb(in TunerLnbRequest request, out int[] lnbHandle)275 boolean requestLnb(in TunerLnbRequest request, out int[] lnbHandle); 276 277 /* 278 * Notifies the TRM that the given frontend has been released. 279 * 280 * <p>Client must call this whenever it releases a Tuner frontend. 281 * 282 * <p><strong>Note:</strong> {@link #setFrontendInfoList(TunerFrontendInfo[])} must be called 283 * before this release. 284 * 285 * @param frontendHandle the handle of the released frontend. 286 * @param clientId the id of the client that is releasing the frontend. 287 */ releaseFrontend(in int frontendHandle, int clientId)288 void releaseFrontend(in int frontendHandle, int clientId); 289 290 /* 291 * Notifies the TRM that the Demux with the given handle was released. 292 * 293 * <p>Client must call this whenever it releases a demux. 294 * 295 * @param demuxHandle the handle of the released Tuner Demux. 296 * @param clientId the id of the client that is releasing the demux. 297 */ releaseDemux(in int demuxHandle, int clientId)298 void releaseDemux(in int demuxHandle, int clientId); 299 300 /* 301 * Notifies the TRM that the Descrambler with the given handle was released. 302 * 303 * <p>Client must call this whenever it releases a descrambler. 304 * 305 * @param descramblerHandle the handle of the released Tuner Descrambler. 306 * @param clientId the id of the client that is releasing the descrambler. 307 */ releaseDescrambler(in int descramblerHandle, int clientId)308 void releaseDescrambler(in int descramblerHandle, int clientId); 309 310 /* 311 * Notifies the TRM that the given Cas session has been released. 312 * 313 * <p>Client must call this whenever it releases a Cas session. 314 * 315 * <p><strong>Note:</strong> {@link #updateCasInfo(int, int)} must be called before this release. 316 * 317 * @param casSessionHandle the handle of the released CAS session. 318 * @param clientId the id of the client that is releasing the cas session. 319 */ releaseCasSession(in int casSessionHandle, int clientId)320 void releaseCasSession(in int casSessionHandle, int clientId); 321 322 /** 323 * Notifies the TRM that the given CiCam has been released. 324 * 325 * <p>Client must call this whenever it releases a CiCam. 326 * 327 * <p><strong>Note:</strong> {@link #updateCasInfo(int, int)} must be called before this 328 * release. 329 * 330 * @param ciCamHandle the handle of the releasing CiCam. 331 * @param clientId the id of the client that is releasing the CiCam. 332 */ releaseCiCam(in int ciCamHandle, int clientId)333 void releaseCiCam(in int ciCamHandle, int clientId); 334 335 /* 336 * Notifies the TRM that the Lnb with the given handle was released. 337 * 338 * <p>Client must call this whenever it releases an Lnb. 339 * 340 * <p><strong>Note:</strong> {@link #setLnbInfos(int[])} must be called before this release. 341 * 342 * @param lnbHandle the handle of the released Tuner Lnb. 343 * @param clientId the id of the client that is releasing the lnb. 344 */ releaseLnb(in int lnbHandle, int clientId)345 void releaseLnb(in int lnbHandle, int clientId); 346 347 /* 348 * Compare two clients' priority. 349 * 350 * @param challengerProfile the {@link ResourceClientProfile} of the challenger. 351 * @param holderProfile the {@link ResourceClientProfile} of the holder of the resource. 352 * 353 * @return true if the challenger has higher priority than the holder. 354 */ isHigherPriority(in ResourceClientProfile challengerProfile, in ResourceClientProfile holderProfile)355 boolean isHigherPriority(in ResourceClientProfile challengerProfile, 356 in ResourceClientProfile holderProfile); 357 } 358