1 /* 2 * Copyright (C) 2019 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 package android.automotive.computepipe.runner; 17 18 import android.automotive.computepipe.runner.PipeDescriptor; 19 import android.automotive.computepipe.runner.IPipeStateCallback; 20 import android.automotive.computepipe.runner.IPipeStream; 21 import android.automotive.computepipe.runner.IPipeDebugger; 22 23 @VintfStability 24 interface IPipeRunner { 25 /** 26 * Init the runner 27 * 28 * @param statecb state handler to notify client of different state 29 * transitions in the runner. The runner deletes this callback after release 30 * is invoked. This is the first call that should be invoked by the client 31 */ init(in IPipeStateCallback statecb)32 void init(in IPipeStateCallback statecb); 33 34 /** 35 * Returns the descriptor for the associated mediapipe 36 * 37 * @param out A descriptor that describes the input options, offload options 38 * and the outputstreams of a computepipe instance. 39 */ getPipeDescriptor()40 PipeDescriptor getPipeDescriptor(); 41 42 /** 43 * Set the input source for the computepipe graph. 44 * This should be done prior to invoking startPipe. 45 * 46 * @param configId id selected from the available input options. 47 * @param out if selection of input source was supported returns OK 48 */ setPipeInputSource(in int configId)49 void setPipeInputSource(in int configId); 50 51 /** 52 * Set the offload options for a graph. 53 * This should be a subset of the supported offload options present in the 54 * descriptor. This should be done prior to invoking startPipe 55 * 56 * @param configID offload option id from the advertised offload options. 57 * @param out if offload option was set then returns OK. 58 */ setPipeOffloadOptions(in int configId)59 void setPipeOffloadOptions(in int configId); 60 61 /** 62 * Set the termination options for a graph. 63 * This should be a subset of the supported termination options present in the 64 * descriptor. This should be done prior to invoking startPipe. 65 * 66 * @param terminationId id of the supported termination option as advertized 67 * in the pipe descriptor 68 * @param out if termination criteria was supported then returns OK. 69 */ setPipeTermination(in int configId)70 void setPipeTermination(in int configId); 71 72 /** 73 * Enable a output stream and install call back for packets from that 74 * stream. This should be invoked prior to calling startPipe. 75 * Call this for each output stream that a client wants to enable 76 * 77 * @param configId: describes the output stream configuration the client 78 * wants to enable 79 * @param maxInFlightCount: The maximum number of inflight packets the 80 * client can handle. 81 * @param handler: the handler for the output packets to be invoked once 82 * packet is received 83 * @param out OK void if setting callback succeeded 84 */ setPipeOutputConfig(in int configId, in int maxInFlightCount, in IPipeStream handler)85 void setPipeOutputConfig(in int configId, in int maxInFlightCount, in IPipeStream handler); 86 87 /** 88 * Apply all configs. 89 * The client has finsihed specifying all the config options. 90 * Now the configs should be applied. Once the configs are applied the 91 * client will get a notification saying PipeState::CONFIG_DONE. 92 * The configuration applied with this step, will be retained for all future runs 93 * unless explicitly reset by calling resetPipeConfigs(). 94 * In case of client death as well, the applied configurations are reset. 95 * In case the runner reports a ERR_HALT state, at any time after applyPipeConfigs(), 96 * all configurations are retained, and expected to be reset by the client 97 * explicitly, prior to attempting a new run. 98 * This call is only allowed when pipe is not running. 99 * 100 * @param out void::OK if the runner was notified to apply config. 101 */ applyPipeConfigs()102 void applyPipeConfigs(); 103 104 /** 105 * Reset all configs. 106 * The runner stores the configuration even after pipe execution has 107 * completed. This call erases the previous configuration, so that client 108 * can modify and set the configuration again. This call is only allowed 109 * when pipe is not running. 110 * 111 * @param out void::OK if the runner was notified to apply config. 112 */ resetPipeConfigs()113 void resetPipeConfigs(); 114 115 /** 116 * Start pipe execution on the runner. Prior to this step 117 * each of the configuration steps should be completed. Once the 118 * configurations have been applied, the state handler will be invoked with 119 * the PipeState::CONFIG_DONE notification. Wait for this notification before starting the pipe. 120 * Once the Pipe starts execution the client will receive the state 121 * notification PipeState::RUNNING through the state handler. 122 * 123 * @param out OK void if start succeeded. 124 */ startPipe()125 void startPipe(); 126 127 /** 128 * Stop pipe execution on the runner. 129 * 130 * This can invoked only when the pipe is in run state ie PipeState::RUNNING. 131 * If a client has already chosen a termination option, then this 132 * call overrides that termination criteria. 133 * 134 * Client will be notified once the pipe has stopped using PipeState::DONE 135 * notification. Until then, outstanding packets may continue to be received. 136 * These packets must still be returned with doneWithPacket(). (This does not 137 * apply to SEMANTIC_DATA, as they are copied in the stream callback). 138 * 139 * Once the Pipe stops execution (no new packets generated), 140 * the client will receive the state 141 * notification, PipeState::DONE. 142 * 143 * Once the pipe has completely quiesced, it will transition back to 144 * PipeState::CONFIG_DONE and at this point a new startPipe() can be issued or 145 * previously applied configs can be reset using the resetPipeConfigs() call. 146 * 147 * @param out OK void if stop succeeded 148 */ stopPipe()149 void stopPipe(); 150 151 /** 152 * Signal completion of a packet having been consumed by the client. 153 * With this signal from client the runner should release buffer corresponding to the packet. 154 * 155 * @param bufferId Buffer id of the packet 156 * @param streamId Stream id of the packet 157 * @param out OK void if successful 158 */ doneWithPacket(in int bufferId, in int streamId)159 void doneWithPacket(in int bufferId, in int streamId); 160 161 /** 162 * Returns the debugger associated with the runner for this graph 163 * 164 * @param out Debugger handle to interact with specific graph 165 */ getPipeDebugger()166 IPipeDebugger getPipeDebugger(); 167 168 /** 169 * Immediately frees up all config resources associated with the client. 170 * Client will not receive state notifications after this call is complete. 171 * 172 * This will also free up any in flight packet. 173 * The client may still get in flight IPipeStream::deliverPacket() callbacks. 174 * However the underlying buffer has been freed up from the packets. 175 * 176 * This also resets any configuration that a client may have performed, 177 * ie pipe transitions back to PipeState::RESET state. 178 * So client will have to start next session with 179 * the configuration steps, ie invoke setPipe*() methods. 180 * 181 * If the client had chosen to enable profiling through IPipeDebugger, 182 * the client should first invoke IPipeDebugger::Release() prior to 183 * this method. 184 * 185 * @return status OK if all resources were freed up. 186 */ releaseRunner()187 void releaseRunner(); 188 } 189