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