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