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.tunerresourcemanager.CasSessionRequest; 20 import android.media.tv.tunerresourcemanager.IResourcesReclaimListener; 21 import android.media.tv.tunerresourcemanager.ResourceClientProfile; 22 import android.media.tv.tunerresourcemanager.TunerCiCamRequest; 23 import android.media.tv.tunerresourcemanager.TunerDemuxInfo; 24 import android.media.tv.tunerresourcemanager.TunerDemuxRequest; 25 import android.media.tv.tunerresourcemanager.TunerDescramblerRequest; 26 import android.media.tv.tunerresourcemanager.TunerFrontendInfo; 27 import android.media.tv.tunerresourcemanager.TunerFrontendRequest; 28 import android.media.tv.tunerresourcemanager.TunerLnbRequest; 29 30 /** 31 * Interface of the Tuner Resource Manager. It manages resources used by TV Tuners. 32 * <p>Resources include: 33 * <ul> 34 * <li>TunerFrontend {@link android.media.tv.tuner.frontend}. 35 * <li>TunerLnb {@link android.media.tv.tuner.Lnb}. 36 * <li>MediaCas {@link android.media.MediaCas}. 37 * <li>TvInputHardware {@link android.media.tv.TvInputHardwareInfo}. 38 * <ul> 39 * 40 * <p>Expected workflow is: 41 * <ul> 42 * <li>Tuner Java/MediaCas/TIF update resources of the current device with TRM. 43 * <li>Client registers its profile through {@link #registerClientProfile(ResourceClientProfile, 44 * IResourcesReclaimListener, int[])}. 45 * <li>Client requests resources through request APIs. 46 * <li>If the resource needs to be handed to a higher priority client from a lower priority 47 * one, TRM calls IResourcesReclaimListener registered by the lower priority client to release 48 * the resource. 49 * <ul> 50 * 51 * @hide 52 */ 53 interface ITunerResourceManager { 54 /* 55 * This API is used by the client to register their profile with the Tuner Resource manager. 56 * 57 * <p>The profile contains information that can show the base priority score of the client. 58 * 59 * @param profile {@link ResourceClientProfile} profile of the current client 60 * @param listener {@link IResourcesReclaimListener} a callback to 61 * reclaim clients' resources when needed. 62 * @param clientId returns a clientId from the resource manager when the 63 * the client registers its profile. 64 */ registerClientProfile(in ResourceClientProfile profile, IResourcesReclaimListener listener, out int[] clientId)65 void registerClientProfile(in ResourceClientProfile profile, 66 IResourcesReclaimListener listener, out int[] clientId); 67 68 /* 69 * This API is used by the client to unregister their profile with the Tuner Resource manager. 70 * 71 * @param clientId the client id that needs to be unregistered. 72 */ unregisterClientProfile(in int clientId)73 void unregisterClientProfile(in int clientId); 74 75 /* 76 * Updates a registered client's priority and niceValue. 77 * 78 * @param clientId the id of the client that is updating its profile. 79 * @param priority the priority that the client would like to update to. 80 * @param niceValue the nice value that the client would like to update to. 81 * 82 * @return true if the update is successful. 83 */ updateClientPriority(in int clientId, in int priority, in int niceValue)84 boolean updateClientPriority(in int clientId, in int priority, in int niceValue); 85 86 /* 87 * Checks if there is any unused frontend resource of the specified type. 88 * 89 * @param frontendType the specific type of frontend resource to be checked for. 90 * 91 * @return true if there is any unused resource of the specified type. 92 */ hasUnusedFrontend(in int frontendType)93 boolean hasUnusedFrontend(in int frontendType); 94 95 /* 96 * Checks if the client has the lowest priority among the clients that are holding 97 * the frontend resource of the specified type. 98 * 99 * <p> When this function returns false, it means that there is at least one client with the 100 * strictly lower priority (than clientId) that is reclaimable by the system. 101 * 102 * @param clientId The client ID to be checked the priority for. 103 * @param frontendType The specific frontend type to be checked for. 104 * 105 * @return false if there is another client holding the frontend resource of the specified type 106 * that can be reclaimed. Otherwise true. 107 */ isLowestPriority(in int clientId, in int frontendType)108 boolean isLowestPriority(in int clientId, in int frontendType); 109 110 /* 111 * Updates the available Frontend resources information on the current device. 112 * 113 * <p><strong>Note:</strong> This update must happen before the first 114 * {@link #requestFrontend(TunerFrontendRequest,int[])} and {@link #releaseFrontend(int, int)} 115 * call. 116 * 117 * @param infos an array of the available {@link TunerFrontendInfo} information. 118 */ setFrontendInfoList(in TunerFrontendInfo[] infos)119 void setFrontendInfoList(in TunerFrontendInfo[] infos); 120 121 /* 122 * Updates the available Cas resource information on the current device. 123 * 124 * <p><strong>Note:</strong> This update must happen before the first 125 * {@link #requestCasSession(CasSessionRequest, int[])} and {@link #releaseCasSession(int, int)} 126 * call. 127 * 128 * @param casSystemId id of the updating CAS system. 129 * @param maxSessionNum the max session number of the CAS system that is updated. 130 */ updateCasInfo(in int casSystemId, in int maxSessionNum)131 void updateCasInfo(in int casSystemId, in int maxSessionNum); 132 133 /* 134 * Updates the available Demux resources information on the current device. 135 * 136 * <p><strong>Note:</strong> This update must happen before the first 137 * {@link #requestDemux(TunerDemux,int[])} and {@link #releaseDemux(int, int)} 138 * call. 139 * 140 * @param infos an array of the available {@link TunerDemux} information. 141 */ setDemuxInfoList(in TunerDemuxInfo[] infos)142 void setDemuxInfoList(in TunerDemuxInfo[] infos); 143 144 /* 145 * Updates the available Lnb resource information on the current device. 146 * 147 * <p><strong>Note:</strong> This update must happen before the first 148 * {@link #requestLnb(TunerLnbRequest, int[])} and {@link #releaseLnb(int, int)} call. 149 * 150 * @param lnbIds ids of the updating lnbs. 151 */ setLnbInfoList(in long[] lnbIds)152 void setLnbInfoList(in long[] lnbIds); 153 154 /** 155 * Determines whether the Resource Holder retains ownership of the resource during a challenge 156 * scenario, when both Resource Holder and Resource Challenger have same processId and same 157 * priority. 158 * 159 * @param clientId The client id used to set ownership of resource in case of resource 160 * challenger situation. 161 * @param enabled Set to {@code true} to allow the Resource Holder to retain ownership, 162 * or false to allow the Resource Challenger to acquire the resource. 163 * If not explicitly set, enabled is set to {@code false}. 164 */ setResourceOwnershipRetention(int clientId, boolean enabled)165 void setResourceOwnershipRetention(int clientId, boolean enabled); 166 167 /* 168 * This API is used by the Tuner framework to request a frontend from the TunerHAL. 169 * 170 * <p>There are two cases: 171 * <ul> 172 * <li>If the desiredId is not {@link TunerFrontendRequest#DEFAULT_DESIRED_ID} 173 * <li><li>If the desired frontend with the given frontendType is available, the API would send 174 * the id back. 175 * <li><li>If the desired frontend with the given frontendType is in use but the current request 176 * info can show higher priority than other uses of Frontend, the API will send 177 * {@link IResourcesReclaimListener#onReclaimResources()} to the {@link Tuner}. Tuner would 178 * handle the resource reclaim on the holder of lower priority and notify the holder of its 179 * resource loss. 180 * <li><li>If no frontend can be granted, the API would return false. 181 * <ul> 182 * 183 * <li>If the desiredId is {@link TunerFrontendRequest#DEFAULT_DESIRED_ID} 184 * <li><li>If there is frontend available, the API would send the id back. 185 * <li><li>If no Frontend is available but the current request info can show higher priority 186 * than other uses of Frontend, the API will send 187 * {@link IResourcesReclaimListener#onReclaimResources()} to the {@link Tuner}. Tuner would 188 * handle the resource reclaim on the holder of lower priority and notify the holder of its 189 * resource loss. 190 * <li><li>If no frontend can be granted, the API would return false. 191 * <ul> 192 * 193 * <p><strong>Note:</strong> {@link #setFrontendInfoList(TunerFrontendInfo[])} must be called 194 * before this request. 195 * 196 * @param request {@link TunerFrontendRequest} information of the current request. 197 * @param frontendHandle a one-element array to return the granted frontendHandle. 198 * 199 * @return true if there is frontend granted. 200 */ requestFrontend(in TunerFrontendRequest request, out long[] frontendHandle)201 boolean requestFrontend(in TunerFrontendRequest request, out long[] frontendHandle); 202 203 /* 204 * Sets the maximum usable frontends number of a given frontend type. It is used to enable or 205 * disable frontends when cable connection status is changed by user. 206 * 207 * @param frontendType the frontendType which the maximum usable number will be set for. 208 * @param maxNumber the new maximum usable number. 209 * 210 * @return true if successful and false otherwise. 211 */ setMaxNumberOfFrontends(in int frontendType, in int maxNum)212 boolean setMaxNumberOfFrontends(in int frontendType, in int maxNum); 213 214 /* 215 * Get the maximum usable frontends number of a given frontend type. 216 * 217 * @param frontendType the frontendType which the maximum usable number will be queried for. 218 * 219 * @return the maximum usable number of the queried frontend type. Returns -1 when the 220 * frontendType is invalid 221 */ getMaxNumberOfFrontends(in int frontendType)222 int getMaxNumberOfFrontends(in int frontendType); 223 224 /* 225 * Requests to share frontend with an existing client. 226 * 227 * <p><strong>Note:</strong> {@link #setFrontendInfoList(TunerFrontendInfo[])} must be called 228 * before this request. 229 * 230 * @param selfClientId the id of the client that sends the request. 231 * @param targetClientId the id of the client to share the frontend with. 232 */ shareFrontend(in int selfClientId, in int targetClientId)233 void shareFrontend(in int selfClientId, in int targetClientId); 234 235 /* 236 * Transfers the ownership of the shared resource. 237 * 238 * <p><strong>Note:</strong> Only the existing frontend sharee can be the new owner. 239 * 240 * @param resourceType the type of resource to transfer the ownership for. 241 * @param currentOwnerId the id of the current owner client. 242 * @param newOwnerId the id of the new owner client. 243 * 244 * @return true if successful. false otherwise. 245 */ transferOwner(in int resourceType, in int currentOwnerId, in int newOwnerId)246 boolean transferOwner(in int resourceType, in int currentOwnerId, in int newOwnerId); 247 248 /* 249 * This API is used by the Tuner framework to request an available demux from the TunerHAL. 250 * 251 * <p>There are three possible scenarios: 252 * <ul> 253 * <li>If there is demux available, the API would send the handle back. 254 * 255 * <li>If no Demux is available but the current request info can show higher priority than 256 * other uses of demuxes, the API will send 257 * {@link IResourcesReclaimListener#onReclaimResources()} to the {@link Tuner}. Tuner would 258 * handle the resource reclaim on the holder of lower priority and notify the holder of its 259 * resource loss. 260 * 261 * <li>If no demux can be granted, the API would return false. 262 * <ul> 263 * 264 * @param request {@link TunerDemuxRequest} information of the current request. 265 * @param demuxHandle a one-element array to return the granted demux handle. 266 * 267 * @return true if there is demux granted. 268 */ requestDemux(in TunerDemuxRequest request, out long[] demuxHandle)269 boolean requestDemux(in TunerDemuxRequest request, out long[] demuxHandle); 270 271 /* 272 * This API is used by the Tuner framework to request an available descrambler from the 273 * TunerHAL. 274 * 275 * <p>There are three possible scenarios: 276 * <ul> 277 * <li>If there is descrambler available, the API would send the handle back. 278 * 279 * <li>If no Descrambler is available but the current request info can show higher priority than 280 * other uses of Descrambler, the API will send 281 * {@link IResourcesReclaimListener#onReclaimResources()} to the {@link Tuner}. Tuner would 282 * handle the resource reclaim on the holder of lower priority and notify the holder of its 283 * resource loss. 284 * 285 * <li>If no Descrambler can be granted, the API would return false. 286 * <ul> 287 * 288 * @param request {@link TunerDescramblerRequest} information of the current request. 289 * @param descramblerHandle a one-element array to return the granted descrambler handle. 290 * 291 * @return true if there is Descrambler granted. 292 */ requestDescrambler(in TunerDescramblerRequest request, out long[] descramblerHandle)293 boolean requestDescrambler(in TunerDescramblerRequest request, out long[] descramblerHandle); 294 295 /* 296 * This API is used by the Tuner framework to request an available Cas session. This session 297 * needs to be under the CAS system with the id indicated in the {@code request}. 298 * 299 * <p>There are three possible scenarios: 300 * <ul> 301 * <li>If there is Cas session available, the API would send the id back. 302 * 303 * <li>If no Cas session is available but the current request info can show higher priority than 304 * other uses of the sessions under the requested CAS system, the API will send 305 * {@link ITunerResourceManagerCallback#onReclaimResources()} to the {@link Tuner}. Tuner would 306 * handle the resource reclaim on the holder of lower priority and notify the holder of its 307 * resource loss. 308 * 309 * <li>If no Cas session can be granted, the API would return false. 310 * <ul> 311 * 312 * <p><strong>Note:</strong> {@link #updateCasInfo(int, int)} must be called before this request. 313 * 314 * @param request {@link CasSessionRequest} information of the current request. 315 * @param casSessionHandle a one-element array to return the granted cas session handle. 316 * 317 * @return true if there is CAS session granted. 318 */ requestCasSession(in CasSessionRequest request, out long[] casSessionHandle)319 boolean requestCasSession(in CasSessionRequest request, out long[] casSessionHandle); 320 321 /* 322 * This API is used by the Tuner framework to request an available CuCam. 323 * 324 * <p>There are three possible scenarios: 325 * <ul> 326 * <li>If there is CiCam available, the API would send the handle back. 327 * 328 * <li>If no CiCma is available but the current request info can show higher priority than 329 * other uses of the ciCam, the API will send 330 * {@link ITunerResourceManagerCallback#onReclaimResources()} to the {@link Tuner}. Tuner would 331 * handle the resource reclaim on the holder of lower priority and notify the holder of its 332 * resource loss. 333 * 334 * <li>If no CiCam can be granted, the API would return false. 335 * <ul> 336 * 337 * <p><strong>Note:</strong> {@link #updateCasInfo(int, int)} must be called before this request. 338 * 339 * @param request {@link TunerCiCamRequest} information of the current request. 340 * @param ciCamHandle a one-element array to return the granted ciCam handle. 341 * 342 * @return true if there is CiCam granted. 343 */ requestCiCam(in TunerCiCamRequest request, out long[] ciCamHandle)344 boolean requestCiCam(in TunerCiCamRequest request, out long[] ciCamHandle); 345 346 /* 347 * This API is used by the Tuner framework to request an available Lnb from the TunerHAL. 348 * 349 * <p>There are three possible scenarios: 350 * <ul> 351 * <li>If there is Lnb available, the API would send the id back. 352 * 353 * <li>If no Lnb is available but the current request has a higher priority than other uses of 354 * lnbs, the API will send {@link ITunerResourceManagerCallback#onReclaimResources()} to the 355 * {@link Tuner}. Tuner would handle the resource reclaim on the holder of lower priority and 356 * notify the holder of its resource loss. 357 * 358 * <li>If no Lnb system can be granted, the API would return false. 359 * <ul> 360 * 361 * <p><strong>Note:</strong> {@link #setLnbInfos(int[])} must be called before this request. 362 * 363 * @param request {@link TunerLnbRequest} information of the current request. 364 * @param lnbHandle a one-element array to return the granted Lnb handle. 365 * 366 * @return true if there is Lnb granted. 367 */ requestLnb(in TunerLnbRequest request, out long[] lnbHandle)368 boolean requestLnb(in TunerLnbRequest request, out long[] lnbHandle); 369 370 /* 371 * Notifies the TRM that the given frontend has been released. 372 * 373 * <p>Client must call this whenever it releases a Tuner frontend. 374 * 375 * <p><strong>Note:</strong> {@link #setFrontendInfoList(TunerFrontendInfo[])} must be called 376 * before this release. 377 * 378 * @param frontendHandle the handle of the released frontend. 379 * @param clientId the id of the client that is releasing the frontend. 380 */ releaseFrontend(in long frontendHandle, int clientId)381 void releaseFrontend(in long frontendHandle, int clientId); 382 383 /* 384 * Notifies the TRM that the Demux with the given handle was released. 385 * 386 * <p>Client must call this whenever it releases a demux. 387 * 388 * @param demuxHandle the handle of the released Tuner Demux. 389 * @param clientId the id of the client that is releasing the demux. 390 */ releaseDemux(in long demuxHandle, int clientId)391 void releaseDemux(in long demuxHandle, int clientId); 392 393 /* 394 * Notifies the TRM that the Descrambler with the given handle was released. 395 * 396 * <p>Client must call this whenever it releases a descrambler. 397 * 398 * @param descramblerHandle the handle of the released Tuner Descrambler. 399 * @param clientId the id of the client that is releasing the descrambler. 400 */ releaseDescrambler(in long descramblerHandle, int clientId)401 void releaseDescrambler(in long descramblerHandle, int clientId); 402 403 /* 404 * Notifies the TRM that the given Cas session has been released. 405 * 406 * <p>Client must call this whenever it releases a Cas session. 407 * 408 * <p><strong>Note:</strong> {@link #updateCasInfo(int, int)} must be called before this release. 409 * 410 * @param casSessionHandle the handle of the released CAS session. 411 * @param clientId the id of the client that is releasing the cas session. 412 */ releaseCasSession(in long casSessionHandle, int clientId)413 void releaseCasSession(in long casSessionHandle, int clientId); 414 415 /** 416 * Notifies the TRM that the given CiCam has been released. 417 * 418 * <p>Client must call this whenever it releases a CiCam. 419 * 420 * <p><strong>Note:</strong> {@link #updateCasInfo(int, int)} must be called before this 421 * release. 422 * 423 * @param ciCamHandle the handle of the releasing CiCam. 424 * @param clientId the id of the client that is releasing the CiCam. 425 */ releaseCiCam(in long ciCamHandle, int clientId)426 void releaseCiCam(in long ciCamHandle, int clientId); 427 428 /* 429 * Notifies the TRM that the Lnb with the given handle was released. 430 * 431 * <p>Client must call this whenever it releases an Lnb. 432 * 433 * <p><strong>Note:</strong> {@link #setLnbInfos(int[])} must be called before this release. 434 * 435 * @param lnbHandle the handle of the released Tuner Lnb. 436 * @param clientId the id of the client that is releasing the lnb. 437 */ releaseLnb(in long lnbHandle, int clientId)438 void releaseLnb(in long lnbHandle, int clientId); 439 440 /* 441 * Compare two clients' priority. 442 * 443 * @param challengerProfile the {@link ResourceClientProfile} of the challenger. 444 * @param holderProfile the {@link ResourceClientProfile} of the holder of the resource. 445 * 446 * @return true if the challenger has higher priority than the holder. 447 */ isHigherPriority(in ResourceClientProfile challengerProfile, in ResourceClientProfile holderProfile)448 boolean isHigherPriority(in ResourceClientProfile challengerProfile, 449 in ResourceClientProfile holderProfile); 450 451 /* 452 * Stores Frontend resource map for the later restore. 453 * 454 * <p>This is API is only for testing purpose and should be used in pair with 455 * restoreResourceMap(), which allows testing of {@link Tuner} APIs 456 * that behave differently based on different sets of resource map. 457 * 458 * @param resourceType The resource type to store the map for. 459 */ storeResourceMap(in int resourceType)460 void storeResourceMap(in int resourceType); 461 462 /* 463 * Clears the frontend resource map. 464 * 465 * <p>This is API is only for testing purpose and should be called right after 466 * storeResourceMap(), so TRMService#removeFrontendResource() does not 467 * get called in TRMService#setFrontendInfoListInternal() for custom frontend 468 * resource map creation. 469 * 470 * @param resourceType The resource type to clear the map for. 471 */ clearResourceMap(in int resourceType)472 void clearResourceMap(in int resourceType); 473 474 /* 475 * Restores Frontend resource map if it was stored before. 476 * 477 * <p>This is API is only for testing purpose and should be used in pair with 478 * storeResourceMap(), which allows testing of {@link Tuner} APIs 479 * that behave differently based on different sets of resource map. 480 * 481 * @param resourceType The resource type to restore the map for. 482 */ restoreResourceMap(in int resourceType)483 void restoreResourceMap(in int resourceType); 484 485 /** 486 * Grants the lock to the caller for public {@link Tuner} APIs 487 * 488 * <p>{@link Tuner} functions that call both [@link TunerResourceManager} APIs and 489 * grabs lock that are also used in {@link IResourcesReclaimListener#onReclaimResources()} 490 * must call this API before acquiring lock used in onReclaimResources(). 491 * 492 * <p>This API will block until it releases the lock or fails 493 * 494 * @param clientId The ID of the caller. 495 * 496 * @return true if the lock is granted. If false is returned, calling this API again is not 497 * guaranteed to work and may be unrecoverrable. (This should not happen.) 498 */ acquireLock(in int clientId, in long clientThreadId)499 boolean acquireLock(in int clientId, in long clientThreadId); 500 501 /** 502 * Releases the lock to the caller for public {@link Tuner} APIs 503 * 504 * <p>This API must be called in pair with {@link #acquireLock(int, int)} 505 * 506 * <p>This API will block until it releases the lock or fails 507 * 508 * @param clientId The ID of the caller. 509 * 510 * @return true if the lock is granted. If false is returned, calling this API again is not 511 * guaranteed to work and may be unrecoverrable. (This should not happen.) 512 */ releaseLock(in int clientId)513 boolean releaseLock(in int clientId); 514 515 /** 516 * Returns a priority for the given use case type and the client's foreground or background 517 * status. 518 * 519 * @param useCase the use case type of the client. When the given use case type is invalid, 520 * the default use case type will be used. {@see TvInputService#PriorityHintUseCaseType}. 521 * @param pid the pid of the client. When the pid is invalid, background status will be used as 522 * a client's status. Otherwise, client's app corresponding to the given session id will 523 * be used as a client. {@see TvInputService#onCreateSession(String, String)}. 524 * 525 * @return the client priority.. 526 */ getClientPriority(int useCase, int pid)527 int getClientPriority(int useCase, int pid); 528 529 /** 530 * Returns a config priority for the given use case type and the foreground or background 531 * status. 532 * 533 * @param useCase the use case type of the client. When the given use case type is invalid, 534 * the default use case type will be used. {@see TvInputService#PriorityHintUseCaseType}. 535 * @param isForeground {@code true} if foreground, {@code false} otherwise. 536 * 537 * @return the config priority. 538 */ getConfigPriority(int useCase, boolean isForeground)539 int getConfigPriority(int useCase, boolean isForeground); 540 } 541