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