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 has been corrected due to a bitstream error. This is a hint, and in most cases 149 * can be ignored. This flag can be set by components on their output to signal the clients 150 * that errors may be present but the frame should be used nonetheless. It can also be set 151 * by clients to signal that the input frame has been corrected, but nonetheless should be 152 * processed. 153 */ 154 FLAG_CORRECTED = (1 << 4), 155 /** 156 * This frame is corrupt due to a bitstream error. This is similar to FLAG_CORRECTED, 157 * with the exception that this is a hint that downstream components should not process this 158 * frame. 159 * <p> 160 * If set on the input by the client, the input is likely non-processable and should be 161 * handled similarly to uncorrectable bitstream error detected. For components that operat 162 * on whole access units, this flag can be propagated to the output. Other components should 163 * aim to detect access unit boundaries to determine if any part of the input frame can be 164 * processed. 165 * <p> 166 * If set by the component, this signals to the client that the output is non-usable - 167 * including possibly the metadata that may also be non-usable; -- however, the component 168 * will try to recover on successive input frames. 169 */ 170 FLAG_CORRUPT = (1 << 5), 171 172 /** 173 * This frame contains only codec-specific configuration data, and no actual access unit. 174 * 175 * \deprecated pass codec configuration with using the C2InitData info parameter together 176 * with the access unit. 177 */ 178 FLAG_CODEC_CONFIG = (1u << 31), 179 }; 180 181 /** 182 * Frame flags */ 183 flags_t flags; 184 C2WorkOrdinalStruct ordinal; 185 std::vector<std::shared_ptr<C2Buffer>> buffers; 186 //< for initial work item, these may also come from the parser - if provided 187 //< for output buffers, these are the responses to requestedInfos 188 std::vector<std::unique_ptr<C2Param>> configUpdate; 189 std::vector<C2InfoBuffer> infoBuffers; 190 }; 191 192 struct C2Worklet { 193 //public: 194 // IN 195 c2_node_id_t component; 196 197 /** Configuration changes to be applied before processing this worklet. */ 198 std::vector<std::unique_ptr<C2Tuning>> tunings; 199 std::vector<std::unique_ptr<C2SettingResult>> failures; 200 201 // OUT 202 C2FrameData output; 203 }; 204 205 /** 206 * Information about partial work-chains not part of the current work items. 207 * 208 * To be defined later. 209 */ 210 struct C2WorkChainInfo; 211 212 /** 213 * This structure holds information about all a single work item. 214 * 215 * This structure shall be passed by the client to the component for the first worklet. As such, 216 * worklets must not be empty. The ownership of this object is passed. 217 */ 218 struct C2Work { 219 //public: 220 /// additional work chain info not part of this work 221 std::shared_ptr<C2WorkChainInfo> chainInfo; 222 223 /// The input data to be processed as part of this work/work-chain. This is provided by the 224 /// client with ownership. When the work is returned (via onWorkDone), the input buffer-pack's 225 /// buffer vector shall contain nullptrs. 226 C2FrameData input; 227 228 /// The chain of components, tunings (including output buffer pool IDs) and info requests that the 229 /// data must pass through. If this has more than a single element, the tunnels between successive 230 /// components of the worklet chain must have been (successfully) pre-registered at the time that 231 /// the work is submitted. Allocating the output buffers in the worklets is the responsibility of 232 /// each component. Upon work submission, each output buffer-pack shall be an appropriately sized 233 /// vector containing nullptrs. When the work is completed/returned to the client, output buffers 234 /// pointers from all but the final worklet shall be nullptrs. 235 std::list<std::unique_ptr<C2Worklet>> worklets; 236 237 /// Number of worklets successfully processed in this chain. This shall be initialized to 0 by the 238 /// client when the work is submitted. It shall contain the number of worklets that were 239 /// successfully processed when the work is returned to the client. If this is less then the number 240 /// of worklets, result must not be success. It must be in the range of [0, worklets.size()]. 241 uint32_t workletsProcessed; 242 243 /// The final outcome of the work (corresponding to the current workletsProcessed). If 0 when 244 /// work is returned, it is assumed that all worklets have been processed. 245 c2_status_t result; 246 }; 247 248 /** 249 * Information about a future work to be submitted to the component. The information is used to 250 * reserve the work for work ordering purposes. 251 */ 252 struct C2WorkOutline { 253 //public: 254 C2WorkOrdinalStruct ordinal; 255 std::vector<c2_node_id_t> chain; 256 }; 257 258 /// @} 259 260 #endif // C2WORK_H_ 261