1 /* 2 * Copyright (C) 2016 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 #ifndef C2WORK_H_ 18 19 #define C2WORK_H_ 20 21 #include <C2Buffer.h> 22 #include <C2Param.h> 23 24 #include <memory> 25 #include <list> 26 #include <vector> 27 28 #include <stdint.h> 29 #include <stdbool.h> 30 31 /// \defgroup work Work and data processing 32 /// @{ 33 34 /** 35 * Information describing the reason a parameter settings may fail, or 36 * may be overriden. 37 */ 38 struct C2SettingResult { 39 enum Failure : uint32_t { 40 /* parameter failures below */ 41 BAD_TYPE, ///< parameter is not supported 42 BAD_PORT, ///< parameter is not supported on the specific port 43 BAD_INDEX, ///< parameter is not supported on the specific stream 44 READ_ONLY, ///< parameter is read-only and cannot be set 45 MISMATCH, ///< parameter mismatches input data 46 47 /* field failures below */ 48 BAD_VALUE, ///< strict parameter does not accept value for the field at all 49 CONFLICT, ///< strict parameter field value is in conflict with an/other setting(s) 50 51 /// parameter field is out of range due to other settings (this failure mode 52 /// can only be used for strict calculated parameters) 53 UNSUPPORTED, 54 55 /// field does not access the requested parameter value at all. It has been corrected to 56 /// the closest supported value. This failure mode is provided to give guidance as to what 57 /// are the currently supported values for this field (which may be a subset of the at-all- 58 /// potential values) 59 INFO_BAD_VALUE, 60 61 /// requested parameter value is in conflict with an/other setting(s) 62 /// and has been corrected to the closest supported value. This failure 63 /// mode is given to provide guidance as to what are the currently supported values as well 64 /// as to optionally provide suggestion to the client as to how to enable the requested 65 /// parameter value. 66 INFO_CONFLICT, 67 }; 68 69 Failure failure; ///< failure code 70 71 /// Failing (or corrected) field or parameterand optionally, currently supported values for the 72 /// field. Values must only be set for field failures other than BAD_VALUE, and only if they are 73 /// different from the globally supported values (e.g. due to restrictions by another param or 74 /// input data). 75 C2ParamFieldValues field; 76 77 /// Conflicting parameters or fields with optional suggestions with (optional) suggested values 78 /// for any conflicting fields to avoid the conflict. Must only be set for CONFLICT, UNSUPPORTED 79 /// and INFO_CONFLICT failure codes. 80 std::vector<C2ParamFieldValues> conflicts; 81 }; 82 83 // ================================================================================================ 84 // WORK 85 // ================================================================================================ 86 87 /** Unique ID for a processing node. */ 88 typedef uint32_t c2_node_id_t; 89 90 enum { 91 kParamIndexWorkOrdinal, 92 }; 93 94 /** 95 * Information for ordering work items on a component port. 96 */ 97 struct C2WorkOrdinalStruct { 98 //public: 99 c2_cntr64_t timestamp; /** frame timestamp in microseconds */ 100 c2_cntr64_t frameIndex; /** submission ordinal on the initial component */ 101 c2_cntr64_t customOrdinal; /** can be given by the component, e.g. decode order */ 102 103 DEFINE_AND_DESCRIBE_C2STRUCT(WorkOrdinal) 104 C2FIELD(timestamp, "timestamp") 105 C2FIELD(frameIndex, "frame-index") 106 C2FIELD(customOrdinal, "custom-ordinal") 107 }; 108 109 /** 110 * This structure represents a Codec 2.0 frame with its metadata. 111 * 112 * A frame basically consists of an ordered sets of buffers, configuration changes and info buffers 113 * along with some non-configuration metadata. 114 */ 115 struct C2FrameData { 116 //public: 117 enum flags_t : uint32_t { 118 /** 119 * For input frames: no output frame shall be generated when processing this frame, but 120 * metadata shall still be processed. 121 * For output frames: this frame shall be discarded and but metadata is still valid. 122 */ 123 FLAG_DROP_FRAME = (1 << 0), 124 /** 125 * This frame is the last frame of the current stream. Further frames are part of a new 126 * stream. 127 */ 128 FLAG_END_OF_STREAM = (1 << 1), 129 /** 130 * This frame shall be discarded with its metadata. 131 * This flag is only set by components - e.g. as a response to the flush command. 132 */ 133 FLAG_DISCARD_FRAME = (1 << 2), 134 /** 135 * This frame is not the last frame produced for the input. 136 * 137 * This flag is normally set by the component - e.g. when an input frame results in multiple 138 * output frames, this flag is set on all but the last output frame. 139 * 140 * Also, when components are chained, this flag should be propagated down the 141 * work chain. That is, if set on an earlier frame of a work-chain, it should be propagated 142 * to all later frames in that chain. Additionally, components down the chain could set 143 * this flag even if not set earlier, e.g. if multiple output frame is generated at that 144 * component for the input frame. 145 */ 146 FLAG_INCOMPLETE = (1 << 3), 147 /** 148 * This frame contains only codec-specific configuration data, and no actual access unit. 149 * 150 * \deprecated pass codec configuration with using the \todo codec-specific configuration 151 * info together with the access unit. 152 */ 153 FLAG_CODEC_CONFIG = (1u << 31), 154 }; 155 156 /** 157 * Frame flags */ 158 flags_t flags; 159 C2WorkOrdinalStruct ordinal; 160 std::vector<std::shared_ptr<C2Buffer>> buffers; 161 //< for initial work item, these may also come from the parser - if provided 162 //< for output buffers, these are the responses to requestedInfos 163 std::vector<std::unique_ptr<C2Param>> configUpdate; 164 std::vector<std::shared_ptr<C2InfoBuffer>> infoBuffers; 165 }; 166 167 struct C2Worklet { 168 //public: 169 // IN 170 c2_node_id_t component; 171 172 /** Configuration changes to be applied before processing this worklet. */ 173 std::vector<std::unique_ptr<C2Tuning>> tunings; 174 std::vector<std::unique_ptr<C2SettingResult>> failures; 175 176 // OUT 177 C2FrameData output; 178 }; 179 180 /** 181 * Information about partial work-chains not part of the current work items. 182 * 183 * To be defined later. 184 */ 185 struct C2WorkChainInfo; 186 187 /** 188 * This structure holds information about all a single work item. 189 * 190 * This structure shall be passed by the client to the component for the first worklet. As such, 191 * worklets must not be empty. The ownership of this object is passed. 192 */ 193 struct C2Work { 194 //public: 195 /// additional work chain info not part of this work 196 std::shared_ptr<C2WorkChainInfo> chainInfo; 197 198 /// The input data to be processed as part of this work/work-chain. This is provided by the 199 /// client with ownership. When the work is returned (via onWorkDone), the input buffer-pack's 200 /// buffer vector shall contain nullptrs. 201 C2FrameData input; 202 203 /// The chain of components, tunings (including output buffer pool IDs) and info requests that the 204 /// data must pass through. If this has more than a single element, the tunnels between successive 205 /// components of the worklet chain must have been (successfully) pre-registered at the time that 206 /// the work is submitted. Allocating the output buffers in the worklets is the responsibility of 207 /// each component. Upon work submission, each output buffer-pack shall be an appropriately sized 208 /// vector containing nullptrs. When the work is completed/returned to the client, output buffers 209 /// pointers from all but the final worklet shall be nullptrs. 210 std::list<std::unique_ptr<C2Worklet>> worklets; 211 212 /// Number of worklets successfully processed in this chain. This shall be initialized to 0 by the 213 /// client when the work is submitted. It shall contain the number of worklets that were 214 /// successfully processed when the work is returned to the client. If this is less then the number 215 /// of worklets, result must not be success. It must be in the range of [0, worklets.size()]. 216 uint32_t workletsProcessed; 217 218 /// The final outcome of the work (corresponding to the current workletsProcessed). If 0 when 219 /// work is returned, it is assumed that all worklets have been processed. 220 c2_status_t result; 221 }; 222 223 /** 224 * Information about a future work to be submitted to the component. The information is used to 225 * reserve the work for work ordering purposes. 226 */ 227 struct C2WorkOutline { 228 //public: 229 C2WorkOrdinalStruct ordinal; 230 std::vector<c2_node_id_t> chain; 231 }; 232 233 /// @} 234 235 #endif // C2WORK_H_ 236