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 C2PARAM_H_ 18 #define C2PARAM_H_ 19 20 #include <C2.h> 21 22 #include <stdbool.h> 23 #include <stdint.h> 24 25 #include <algorithm> 26 #include <string> 27 #include <type_traits> 28 #include <utility> 29 #include <vector> 30 31 /// \addtogroup Parameters 32 /// @{ 33 34 /// \defgroup internal Internal helpers. 35 36 /*! 37 * \file 38 * PARAMETERS: SETTINGs, TUNINGs, and INFOs 39 * === 40 * 41 * These represent miscellaneous control and metadata information and are likely copied into 42 * kernel space. Therefore, these are C-like structures designed to carry just a small amount of 43 * information. We are using C++ to be able to add constructors, as well as non-virtual and class 44 * methods. 45 * 46 * ==Specification details: 47 * 48 * Restrictions: 49 * - must be POD struct, e.g. no vtable (no virtual destructor) 50 * - must have the same size in 64-bit and 32-bit mode (no size_t) 51 * - as such, no pointer members 52 * - some common member field names are reserved as they are defined as methods for all 53 * parameters: 54 * they are: size, type, kind, index and stream 55 * 56 * Behavior: 57 * - Params can be global (not related to input or output), related to input or output, 58 * or related to an input/output stream. 59 * - All params are queried/set using a unique param index, which incorporates a potential stream 60 * index and/or port. 61 * - Querying (supported) params MUST never fail. 62 * - All params MUST have default values. 63 * - If some fields have "unsupported" or "invalid" values during setting, this SHOULD be 64 * communicated to the app. 65 * a) Ideally, this should be avoided. When setting parameters, in general, component should do 66 * "best effort" to apply all settings. It should change "invalid/unsupported" values to the 67 * nearest supported values. 68 * - This is communicated to the client by changing the source values in tune()/ 69 * configure(). 70 * b) If falling back to a supported value is absolutely impossible, the component SHALL return 71 * an error for the specific setting, but should continue to apply other settings. 72 * TODO: this currently may result in unintended results. 73 * 74 * **NOTE:** unlike OMX, params are not versioned. Instead, a new struct with new param index 75 * SHALL be added as new versions are required. 76 * 77 * The proper subtype (Setting, Info or Param) is incorporated into the class type. Define structs 78 * to define multiple subtyped versions of related parameters. 79 * 80 * ==Implementation details: 81 * 82 * - Use macros to define parameters 83 * - All parameters must have a default constructor 84 * - This is only used for instantiating the class in source (e.g. will not be used 85 * when building a parameter by the framework from key/value pairs.) 86 */ 87 88 /// \ingroup internal 89 90 /** 91 * Parameter base class. 92 */ 93 struct C2Param { 94 // param index encompasses the following: 95 // 96 // - kind (setting, tuning, info, struct) 97 // - scope 98 // - direction (global, input, output) 99 // - stream flag 100 // - stream ID (usually 0) 101 // - and the parameter's type (core index) 102 // - flexible parameter flag 103 // - vendor extension flag 104 // - type index (this includes the vendor extension flag) 105 // 106 // layout: 107 // 108 // kind : <------- scope -------> : <----- core index -----> 109 // +------+-----+---+------+--------+----|------+--------------+ 110 // | kind | dir | - |stream|streamID|flex|vendor| type index | 111 // +------+-----+---+------+--------+----+------+--------------+ 112 // bit: 31..30 29.28 25 24 .. 17 16 15 14 .. 0 113 // 114 public: 115 /** 116 * C2Param kinds, usable as bitmaps. 117 */ 118 enum kind_t : uint32_t { 119 NONE = 0, 120 STRUCT = (1 << 0), 121 INFO = (1 << 1), 122 SETTING = (1 << 2), 123 TUNING = (1 << 3) | SETTING, // tunings are settings 124 }; 125 126 /** 127 * The parameter type index specifies the underlying parameter type of a parameter as 128 * an integer value. 129 * 130 * Parameter types are divided into two groups: platform types and vendor types. 131 * 132 * Platform types are defined by the platform and are common for all implementations. 133 * 134 * Vendor types are defined by each vendors, so they may differ between implementations. 135 * It is recommended that vendor types be the same for all implementations by a specific 136 * vendor. 137 */ 138 typedef uint32_t type_index_t; 139 enum : uint32_t { 140 TYPE_INDEX_VENDOR_START = 0x00008000, ///< vendor indices SHALL start after this 141 }; 142 143 /** 144 * Core index is the underlying parameter type for a parameter. It is used to describe the 145 * layout of the parameter structure regardless of the component or parameter kind/scope. 146 * 147 * It is used to identify and distinguish global parameters, and also parameters on a given 148 * port or stream. They must be unique for the set of global parameters, as well as for the 149 * set of parameters on each port or each stream, but the same core index can be used for 150 * parameters on different streams or ports, as well as for global parameters and port/stream 151 * parameters. 152 * 153 * Multiple parameter types can share the same layout. 154 * 155 * \note The layout for all parameters with the same core index across all components must 156 * be identical. 157 */ 158 struct CoreIndex { 159 //public: 160 enum : uint32_t { 161 IS_FLEX_FLAG = 0x00010000, 162 }; 163 164 protected: 165 enum : uint32_t { 166 KIND_MASK = 0xC0000000, 167 KIND_STRUCT = 0x00000000, 168 KIND_TUNING = 0x40000000, 169 KIND_SETTING = 0x80000000, 170 KIND_INFO = 0xC0000000, 171 172 DIR_MASK = 0x30000000, 173 DIR_GLOBAL = 0x20000000, 174 DIR_UNDEFINED = DIR_MASK, // MUST have all bits set 175 DIR_INPUT = 0x00000000, 176 DIR_OUTPUT = 0x10000000, 177 178 IS_STREAM_FLAG = 0x02000000, 179 STREAM_ID_MASK = 0x01FE0000, 180 STREAM_ID_SHIFT = 17, 181 MAX_STREAM_ID = STREAM_ID_MASK >> STREAM_ID_SHIFT, 182 STREAM_MASK = IS_STREAM_FLAG | STREAM_ID_MASK, 183 184 IS_VENDOR_FLAG = 0x00008000, 185 TYPE_INDEX_MASK = 0x0000FFFF, 186 CORE_MASK = TYPE_INDEX_MASK | IS_FLEX_FLAG, 187 }; 188 189 public: 190 /// constructor/conversion from uint32_t CoreIndexC2Param::CoreIndex191 inline CoreIndex(uint32_t index) : mIndex(index) { } 192 193 // no conversion from uint64_t 194 inline CoreIndex(uint64_t index) = delete; 195 196 /// returns true iff this is a vendor extension parameter isVendorC2Param::CoreIndex197 inline bool isVendor() const { return mIndex & IS_VENDOR_FLAG; } 198 199 /// returns true iff this is a flexible parameter (with variable size) isFlexibleC2Param::CoreIndex200 inline bool isFlexible() const { return mIndex & IS_FLEX_FLAG; } 201 202 /// returns the core index 203 /// This is the combination of the parameter type index and the flexible flag. coreIndexC2Param::CoreIndex204 inline uint32_t coreIndex() const { return mIndex & CORE_MASK; } 205 206 /// returns the parameter type index typeIndexC2Param::CoreIndex207 inline type_index_t typeIndex() const { return mIndex & TYPE_INDEX_MASK; } 208 209 DEFINE_FIELD_AND_MASK_BASED_COMPARISON_OPERATORS(CoreIndex, mIndex, CORE_MASK) 210 211 protected: 212 uint32_t mIndex; 213 }; 214 215 /** 216 * Type encompasses the parameter's kind (tuning, setting, info), its scope (whether the 217 * parameter is global, input or output, and whether it is for a stream) and the its base 218 * index (which also determines its layout). 219 */ 220 struct Type : public CoreIndex { 221 //public: 222 /// returns true iff this is a global parameter (not for input nor output) isGlobalC2Param::Type223 inline bool isGlobal() const { return (mIndex & DIR_MASK) == DIR_GLOBAL; } 224 /// returns true iff this is an input or input stream parameter forInputC2Param::Type225 inline bool forInput() const { return (mIndex & DIR_MASK) == DIR_INPUT; } 226 /// returns true iff this is an output or output stream parameter forOutputC2Param::Type227 inline bool forOutput() const { return (mIndex & DIR_MASK) == DIR_OUTPUT; } 228 229 /// returns true iff this is a stream parameter forStreamC2Param::Type230 inline bool forStream() const { return mIndex & IS_STREAM_FLAG; } 231 /// returns true iff this is a port (input or output) parameter forPortC2Param::Type232 inline bool forPort() const { return !forStream() && !isGlobal(); } 233 234 /// returns the parameter type: the parameter index without the stream ID typeC2Param::Type235 inline uint32_t type() const { return mIndex & (~STREAM_ID_MASK); } 236 237 /// return the kind (struct, info, setting or tuning) of this param kindC2Param::Type238 inline kind_t kind() const { 239 switch (mIndex & KIND_MASK) { 240 case KIND_STRUCT: return STRUCT; 241 case KIND_INFO: return INFO; 242 case KIND_SETTING: return SETTING; 243 case KIND_TUNING: return TUNING; 244 default: return NONE; // should not happen 245 } 246 } 247 248 /// constructor/conversion from uint32_t TypeC2Param::Type249 inline Type(uint32_t index) : CoreIndex(index) { } 250 251 // no conversion from uint64_t 252 inline Type(uint64_t index) = delete; 253 254 DEFINE_FIELD_AND_MASK_BASED_COMPARISON_OPERATORS(Type, mIndex, ~STREAM_ID_MASK) 255 256 private: 257 friend struct C2Param; // for setPort() 258 friend struct C2Tuning; // for KIND_TUNING 259 friend struct C2Setting; // for KIND_SETTING 260 friend struct C2Info; // for KIND_INFO 261 // for DIR_GLOBAL 262 template<typename T, typename S, int I, class F> friend struct C2GlobalParam; 263 template<typename T, typename S, int I, class F> friend struct C2PortParam; // for kDir* 264 template<typename T, typename S, int I, class F> friend struct C2StreamParam; // for kDir* 265 friend struct _C2ParamInspector; // for testing 266 267 /** 268 * Sets the port/stream direction. 269 * @return true on success, false if could not set direction (e.g. it is global param). 270 */ setPortC2Param::Type271 inline bool setPort(bool output) { 272 if (isGlobal()) { 273 return false; 274 } else { 275 mIndex = (mIndex & ~DIR_MASK) | (output ? DIR_OUTPUT : DIR_INPUT); 276 return true; 277 } 278 } 279 }; 280 281 /** 282 * index encompasses all remaining information: basically the stream ID. 283 */ 284 struct Index : public Type { 285 /// returns the index as uint32_t uint32_tC2Param::Index286 inline operator uint32_t() const { return mIndex; } 287 288 /// constructor/conversion from uint32_t IndexC2Param::Index289 inline Index(uint32_t index) : Type(index) { } 290 291 /// copy constructor 292 inline Index(const Index &index) = default; 293 294 // no conversion from uint64_t 295 inline Index(uint64_t index) = delete; 296 297 /// returns the stream ID or ~0 if not a stream streamC2Param::Index298 inline unsigned stream() const { 299 return forStream() ? rawStream() : ~0U; 300 } 301 302 /// Returns an index with stream field set to given stream. withStreamC2Param::Index303 inline Index withStream(unsigned stream) const { 304 Index ix = mIndex; 305 (void)ix.setStream(stream); 306 return ix; 307 } 308 309 /// sets the port (direction). Returns true iff successful. withPortC2Param::Index310 inline Index withPort(bool output) const { 311 Index ix = mIndex; 312 (void)ix.setPort(output); 313 return ix; 314 } 315 316 DEFINE_FIELD_BASED_COMPARISON_OPERATORS(Index, mIndex) 317 318 private: 319 friend struct C2Param; // for setStream, MakeStreamId, isValid 320 friend struct _C2ParamInspector; // for testing 321 322 /** 323 * @return true if the type is valid, e.g. direction is not undefined AND 324 * stream is 0 if not a stream param. 325 */ isValidC2Param::Index326 inline bool isValid() const { 327 // there is no Type::isValid (even though some of this check could be 328 // performed on types) as this is only used on index... 329 return (forStream() ? rawStream() < MAX_STREAM_ID : rawStream() == 0) 330 && (mIndex & DIR_MASK) != DIR_UNDEFINED; 331 } 332 333 /// returns the raw stream ID field rawStreamC2Param::Index334 inline unsigned rawStream() const { 335 return (mIndex & STREAM_ID_MASK) >> STREAM_ID_SHIFT; 336 } 337 338 /// returns the streamId bitfield for a given |stream|. If stream is invalid, 339 /// returns an invalid bitfield. MakeStreamIdC2Param::Index340 inline static uint32_t MakeStreamId(unsigned stream) { 341 // saturate stream ID (max value is invalid) 342 if (stream > MAX_STREAM_ID) { 343 stream = MAX_STREAM_ID; 344 } 345 return (stream << STREAM_ID_SHIFT) & STREAM_ID_MASK; 346 } 347 convertToStreamC2Param::Index348 inline bool convertToStream(bool output, unsigned stream) { 349 mIndex = (mIndex & ~DIR_MASK) | IS_STREAM_FLAG; 350 (void)setPort(output); 351 return setStream(stream); 352 } 353 convertToPortC2Param::Index354 inline void convertToPort(bool output) { 355 mIndex = (mIndex & ~(DIR_MASK | IS_STREAM_FLAG)); 356 (void)setPort(output); 357 } 358 convertToGlobalC2Param::Index359 inline void convertToGlobal() { 360 mIndex = (mIndex & ~(DIR_MASK | IS_STREAM_FLAG)) | DIR_GLOBAL; 361 } 362 363 /** 364 * Sets the stream index. 365 * \return true on success, false if could not set index (e.g. not a stream param). 366 */ setStreamC2Param::Index367 inline bool setStream(unsigned stream) { 368 if (forStream()) { 369 mIndex = (mIndex & ~STREAM_ID_MASK) | MakeStreamId(stream); 370 return this->stream() < MAX_STREAM_ID; 371 } 372 return false; 373 } 374 }; 375 376 public: 377 // public getters for Index methods 378 379 /// returns true iff this is a vendor extension parameter isVendorC2Param380 inline bool isVendor() const { return _mIndex.isVendor(); } 381 /// returns true iff this is a flexible parameter isFlexibleC2Param382 inline bool isFlexible() const { return _mIndex.isFlexible(); } 383 /// returns true iff this is a global parameter (not for input nor output) isGlobalC2Param384 inline bool isGlobal() const { return _mIndex.isGlobal(); } 385 /// returns true iff this is an input or input stream parameter forInputC2Param386 inline bool forInput() const { return _mIndex.forInput(); } 387 /// returns true iff this is an output or output stream parameter forOutputC2Param388 inline bool forOutput() const { return _mIndex.forOutput(); } 389 390 /// returns true iff this is a stream parameter forStreamC2Param391 inline bool forStream() const { return _mIndex.forStream(); } 392 /// returns true iff this is a port (input or output) parameter forPortC2Param393 inline bool forPort() const { return _mIndex.forPort(); } 394 395 /// returns the stream ID or ~0 if not a stream streamC2Param396 inline unsigned stream() const { return _mIndex.stream(); } 397 398 /// returns the parameter type: the parameter index without the stream ID typeC2Param399 inline Type type() const { return _mIndex.type(); } 400 401 /// returns the index of this parameter 402 /// \todo: should we restrict this to C2ParamField? indexC2Param403 inline uint32_t index() const { return (uint32_t)_mIndex; } 404 405 /// returns the core index of this parameter coreIndexC2Param406 inline CoreIndex coreIndex() const { return _mIndex.coreIndex(); } 407 408 /// returns the kind of this parameter kindC2Param409 inline kind_t kind() const { return _mIndex.kind(); } 410 411 /// returns the size of the parameter or 0 if the parameter is invalid sizeC2Param412 inline size_t size() const { return _mSize; } 413 414 /// returns true iff the parameter is valid 415 inline operator bool() const { return _mIndex.isValid() && _mSize > 0; } 416 417 /// returns true iff the parameter is invalid 418 inline bool operator!() const { return !operator bool(); } 419 420 // equality is done by memcmp (use equals() to prevent any overread) 421 inline bool operator==(const C2Param &o) const { 422 return equals(o) && memcmp(this, &o, _mSize) == 0; 423 } 424 inline bool operator!=(const C2Param &o) const { return !operator==(o); } 425 426 /// safe(r) type cast from pointer and size FromC2Param427 inline static C2Param* From(void *addr, size_t len) { 428 // _mSize must fit into size, but really C2Param must also to be a valid param 429 if (len < sizeof(C2Param)) { 430 return nullptr; 431 } 432 // _mSize must match length 433 C2Param *param = (C2Param*)addr; 434 if (param->_mSize != len) { 435 return nullptr; 436 } 437 return param; 438 } 439 440 /// Returns managed clone of |orig| at heap. CopyC2Param441 inline static std::unique_ptr<C2Param> Copy(const C2Param &orig) { 442 if (orig.size() == 0) { 443 return nullptr; 444 } 445 void *mem = ::operator new (orig.size()); 446 C2Param *param = new (mem) C2Param(orig.size(), orig._mIndex); 447 param->updateFrom(orig); 448 return std::unique_ptr<C2Param>(param); 449 } 450 451 /// Returns managed clone of |orig| as a stream parameter at heap. CopyAsStreamC2Param452 inline static std::unique_ptr<C2Param> CopyAsStream( 453 const C2Param &orig, bool output, unsigned stream) { 454 std::unique_ptr<C2Param> copy = Copy(orig); 455 if (copy) { 456 copy->_mIndex.convertToStream(output, stream); 457 } 458 return copy; 459 } 460 461 /// Returns managed clone of |orig| as a port parameter at heap. CopyAsPortC2Param462 inline static std::unique_ptr<C2Param> CopyAsPort(const C2Param &orig, bool output) { 463 std::unique_ptr<C2Param> copy = Copy(orig); 464 if (copy) { 465 copy->_mIndex.convertToPort(output); 466 } 467 return copy; 468 } 469 470 /// Returns managed clone of |orig| as a global parameter at heap. CopyAsGlobalC2Param471 inline static std::unique_ptr<C2Param> CopyAsGlobal(const C2Param &orig) { 472 std::unique_ptr<C2Param> copy = Copy(orig); 473 if (copy) { 474 copy->_mIndex.convertToGlobal(); 475 } 476 return copy; 477 } 478 479 #if 0 480 template<typename P, class=decltype(C2Param(P()))> AsC2Param481 P *As() { return P::From(this); } 482 template<typename P> AsC2Param483 const P *As() const { return const_cast<const P*>(P::From(const_cast<C2Param*>(this))); } 484 #endif 485 486 protected: 487 /// sets the stream field. Returns true iff successful. setStreamC2Param488 inline bool setStream(unsigned stream) { 489 return _mIndex.setStream(stream); 490 } 491 492 /// sets the port (direction). Returns true iff successful. setPortC2Param493 inline bool setPort(bool output) { 494 return _mIndex.setPort(output); 495 } 496 497 public: 498 /// invalidate this parameter. There is no recovery from this call; e.g. parameter 499 /// cannot be 'corrected' to be valid. invalidateC2Param500 inline void invalidate() { _mSize = 0; } 501 502 // if other is the same kind of (valid) param as this, copy it into this and return true. 503 // otherwise, do not copy anything, and return false. updateFromC2Param504 inline bool updateFrom(const C2Param &other) { 505 if (other._mSize <= _mSize && other._mIndex == _mIndex && _mSize > 0) { 506 memcpy(this, &other, other._mSize); 507 return true; 508 } 509 return false; 510 } 511 512 protected: 513 // returns |o| if it is a null ptr, or if can suitably be a param of given |type| (e.g. has 514 // same type (ignoring stream ID), and size). Otherwise, returns null. If |checkDir| is false, 515 // allow undefined or different direction (e.g. as constructed from C2PortParam() vs. 516 // C2PortParam::input), but still require equivalent type (stream, port or global); otherwise, 517 // return null. 518 inline static const C2Param* IfSuitable( 519 const C2Param* o, size_t size, Type type, size_t flexSize = 0, bool checkDir = true) { 520 if (o == nullptr || o->_mSize < size || (flexSize && ((o->_mSize - size) % flexSize))) { 521 return nullptr; 522 } else if (checkDir) { 523 return o->_mIndex.type() == type.mIndex ? o : nullptr; 524 } else if (o->_mIndex.isGlobal()) { 525 return nullptr; 526 } else { 527 return ((o->_mIndex.type() ^ type.mIndex) & ~Type::DIR_MASK) ? nullptr : o; 528 } 529 } 530 531 /// base constructor C2ParamC2Param532 inline C2Param(uint32_t paramSize, Index paramIndex) 533 : _mSize(paramSize), 534 _mIndex(paramIndex) { 535 if (paramSize > sizeof(C2Param)) { 536 memset(this + 1, 0, paramSize - sizeof(C2Param)); 537 } 538 } 539 540 /// base constructor with stream set C2ParamC2Param541 inline C2Param(uint32_t paramSize, Index paramIndex, unsigned stream) 542 : _mSize(paramSize), 543 _mIndex(paramIndex | Index::MakeStreamId(stream)) { 544 if (paramSize > sizeof(C2Param)) { 545 memset(this + 1, 0, paramSize - sizeof(C2Param)); 546 } 547 if (!forStream()) { 548 invalidate(); 549 } 550 } 551 552 private: 553 friend struct _C2ParamInspector; // for testing 554 555 /// returns true iff |o| has the same size and index as this. This performs the 556 /// basic check for equality. equalsC2Param557 inline bool equals(const C2Param &o) const { 558 return _mSize == o._mSize && _mIndex == o._mIndex; 559 } 560 561 uint32_t _mSize; 562 Index _mIndex; 563 }; 564 565 /// \ingroup internal 566 /// allow C2Params access to private methods, e.g. constructors 567 #define C2PARAM_MAKE_FRIENDS \ 568 template<typename U, typename S, int I, class F> friend struct C2GlobalParam; \ 569 template<typename U, typename S, int I, class F> friend struct C2PortParam; \ 570 template<typename U, typename S, int I, class F> friend struct C2StreamParam; \ 571 572 /** 573 * Setting base structure for component method signatures. Wrap constructors. 574 */ 575 struct C2Setting : public C2Param { 576 protected: 577 template<typename ...Args> C2SettingC2Setting578 inline C2Setting(const Args(&... args)) : C2Param(args...) { } 579 public: // TODO 580 enum : uint32_t { PARAM_KIND = Type::KIND_SETTING }; 581 }; 582 583 /** 584 * Tuning base structure for component method signatures. Wrap constructors. 585 */ 586 struct C2Tuning : public C2Setting { 587 protected: 588 template<typename ...Args> C2TuningC2Tuning589 inline C2Tuning(const Args(&... args)) : C2Setting(args...) { } 590 public: // TODO 591 enum : uint32_t { PARAM_KIND = Type::KIND_TUNING }; 592 }; 593 594 /** 595 * Info base structure for component method signatures. Wrap constructors. 596 */ 597 struct C2Info : public C2Param { 598 protected: 599 template<typename ...Args> C2InfoC2Info600 inline C2Info(const Args(&... args)) : C2Param(args...) { } 601 public: // TODO 602 enum : uint32_t { PARAM_KIND = Type::KIND_INFO }; 603 }; 604 605 /** 606 * Structure uniquely specifying a field in an arbitrary structure. 607 * 608 * \note This structure is used differently in C2FieldDescriptor to 609 * identify array fields, such that _mSize is the size of each element. This is 610 * because the field descriptor contains the array-length, and we want to keep 611 * a relevant element size for variable length arrays. 612 */ 613 struct _C2FieldId { 614 //public: 615 /** 616 * Constructor used for C2FieldDescriptor that removes the array extent. 617 * 618 * \param[in] offset pointer to the field in an object at address 0. 619 */ 620 template<typename T, class B=typename std::remove_extent<T>::type> _C2FieldId_C2FieldId621 inline _C2FieldId(T* offset) 622 : // offset is from "0" so will fit on 32-bits 623 _mOffset((uint32_t)(uintptr_t)(offset)), 624 _mSize(sizeof(B)) { } 625 626 /** 627 * Direct constructor from offset and size. 628 * 629 * \param[in] offset offset of the field. 630 * \param[in] size size of the field. 631 */ _C2FieldId_C2FieldId632 inline _C2FieldId(size_t offset, size_t size) 633 : _mOffset(offset), _mSize(size) {} 634 635 /** 636 * Constructor used to identify a field in an object. 637 * 638 * \param U[type] pointer to the object that contains this field. This is needed in case the 639 * field is in an (inherited) base class, in which case T will be that base class. 640 * \param pm[im] member pointer to the field 641 */ 642 template<typename R, typename T, typename U, typename B=typename std::remove_extent<R>::type> _C2FieldId_C2FieldId643 inline _C2FieldId(U *, R T::* pm) 644 : _mOffset((uint32_t)(uintptr_t)(&(((U*)256)->*pm)) - 256u), 645 _mSize(sizeof(B)) { } 646 647 /** 648 * Constructor used to identify a field in an object. 649 * 650 * \param pm[im] member pointer to the field 651 */ 652 template<typename R, typename T, typename B=typename std::remove_extent<R>::type> _C2FieldId_C2FieldId653 inline _C2FieldId(R T::* pm) 654 : _mOffset((uint32_t)(uintptr_t)(&(((T*)0)->*pm))), 655 _mSize(sizeof(B)) { } 656 657 inline bool operator==(const _C2FieldId &other) const { 658 return _mOffset == other._mOffset && _mSize == other._mSize; 659 } 660 661 inline bool operator<(const _C2FieldId &other) const { 662 return _mOffset < other._mOffset || 663 // NOTE: order parent structure before sub field 664 (_mOffset == other._mOffset && _mSize > other._mSize); 665 } 666 DEFINE_OTHER_COMPARISON_OPERATORS_C2FieldId667 DEFINE_OTHER_COMPARISON_OPERATORS(_C2FieldId) 668 669 #if 0 670 inline uint32_t offset() const { return _mOffset; } size_C2FieldId671 inline uint32_t size() const { return _mSize; } 672 #endif 673 674 #if defined(FRIEND_TEST) 675 friend void PrintTo(const _C2FieldId &d, ::std::ostream*); 676 #endif 677 678 private: 679 friend struct _C2ParamInspector; 680 friend struct C2FieldDescriptor; 681 682 uint32_t _mOffset; // offset of field 683 uint32_t _mSize; // size of field 684 }; 685 686 /** 687 * Structure uniquely specifying a 'field' in a configuration. The field 688 * can be a field of a configuration, a subfield of a field of a configuration, 689 * and even the whole configuration. Moreover, if the field can point to an 690 * element in a array field, or to the entire array field. 691 * 692 * This structure is used for querying supported values for a field, as well 693 * as communicating configuration failures and conflicts when trying to change 694 * a configuration for a component/interface or a store. 695 */ 696 struct C2ParamField { 697 //public: 698 /** 699 * Create a field identifier using a configuration parameter (variable), 700 * and a pointer to member. 701 * 702 * ~~~~~~~~~~~~~ (.cpp) 703 * 704 * struct C2SomeParam { 705 * uint32_t mField; 706 * uint32_t mArray[2]; 707 * C2OtherStruct mStruct; 708 * uint32_t mFlexArray[]; 709 * } *mParam; 710 * 711 * C2ParamField(mParam, &mParam->mField); 712 * C2ParamField(mParam, &mParam->mArray); 713 * C2ParamField(mParam, &mParam->mArray[0]); 714 * C2ParamField(mParam, &mParam->mStruct.mSubField); 715 * C2ParamField(mParam, &mParam->mFlexArray); 716 * C2ParamField(mParam, &mParam->mFlexArray[2]); 717 * 718 * ~~~~~~~~~~~~~ 719 * 720 * \todo fix what this is for T[] (for now size becomes T[1]) 721 * 722 * \note this does not work for 64-bit members as it triggers a 723 * 'taking address of packed member' warning. 724 * 725 * \param param pointer to parameter 726 * \param offset member pointer 727 */ 728 template<typename S, typename T> C2ParamFieldC2ParamField729 inline C2ParamField(S* param, T* offset) 730 : _mIndex(param->index()), 731 _mFieldId((T*)((uintptr_t)offset - (uintptr_t)param)) {} 732 733 template<typename S, typename T> MakeC2ParamField734 inline static C2ParamField Make(S& param, T& offset) { 735 return C2ParamField(param.index(), (uintptr_t)&offset - (uintptr_t)¶m, sizeof(T)); 736 } 737 738 /** 739 * Create a field identifier using a configuration parameter (variable), 740 * and a member pointer. This method cannot be used to refer to an 741 * array element or a subfield. 742 * 743 * ~~~~~~~~~~~~~ (.cpp) 744 * 745 * C2SomeParam mParam; 746 * C2ParamField(&mParam, &C2SomeParam::mMemberField); 747 * 748 * ~~~~~~~~~~~~~ 749 * 750 * \param p pointer to parameter 751 * \param T member pointer to the field member 752 */ 753 template<typename R, typename T, typename U> C2ParamFieldC2ParamField754 inline C2ParamField(U *p, R T::* pm) : _mIndex(p->index()), _mFieldId(p, pm) { } 755 756 /** 757 * Create a field identifier to a configuration parameter (variable). 758 * 759 * ~~~~~~~~~~~~~ (.cpp) 760 * 761 * C2SomeParam mParam; 762 * C2ParamField(&mParam); 763 * 764 * ~~~~~~~~~~~~~ 765 * 766 * \param param pointer to parameter 767 */ 768 template<typename S> C2ParamFieldC2ParamField769 inline C2ParamField(S* param) 770 : _mIndex(param->index()), _mFieldId(0u, param->size()) { } 771 772 /** Copy constructor. */ 773 inline C2ParamField(const C2ParamField &other) = default; 774 775 /** 776 * Equality operator. 777 */ 778 inline bool operator==(const C2ParamField &other) const { 779 return _mIndex == other._mIndex && _mFieldId == other._mFieldId; 780 } 781 782 /** 783 * Ordering operator. 784 */ 785 inline bool operator<(const C2ParamField &other) const { 786 return _mIndex < other._mIndex || 787 (_mIndex == other._mIndex && _mFieldId < other._mFieldId); 788 } 789 DEFINE_OTHER_COMPARISON_OPERATORSC2ParamField790 DEFINE_OTHER_COMPARISON_OPERATORS(C2ParamField) 791 792 protected: 793 inline C2ParamField(C2Param::Index index, uint32_t offset, uint32_t size) 794 : _mIndex(index), _mFieldId(offset, size) {} 795 796 private: 797 friend struct _C2ParamInspector; 798 799 C2Param::Index _mIndex; ///< parameter index 800 _C2FieldId _mFieldId; ///< field identifier 801 }; 802 803 /** 804 * A shared (union) representation of numeric values 805 */ 806 class C2Value { 807 public: 808 /// A union of supported primitive types. 809 union Primitive { 810 // first member is always zero initialized so it must be the largest 811 uint64_t u64; ///< uint64_t value 812 int64_t i64; ///< int64_t value 813 c2_cntr64_t c64; ///< c2_cntr64_t value 814 uint32_t u32; ///< uint32_t value 815 int32_t i32; ///< int32_t value 816 c2_cntr32_t c32; ///< c2_cntr32_t value 817 float fp; ///< float value 818 819 // constructors - implicit Primitive(uint64_t value)820 Primitive(uint64_t value) : u64(value) { } Primitive(int64_t value)821 Primitive(int64_t value) : i64(value) { } Primitive(c2_cntr64_t value)822 Primitive(c2_cntr64_t value) : c64(value) { } Primitive(uint32_t value)823 Primitive(uint32_t value) : u32(value) { } Primitive(int32_t value)824 Primitive(int32_t value) : i32(value) { } Primitive(c2_cntr32_t value)825 Primitive(c2_cntr32_t value) : c32(value) { } Primitive(uint8_t value)826 Primitive(uint8_t value) : u32(value) { } Primitive(char value)827 Primitive(char value) : i32(value) { } Primitive(float value)828 Primitive(float value) : fp(value) { } 829 830 // allow construction from enum type 831 template<typename E, typename = typename std::enable_if<std::is_enum<E>::value>::type> Primitive(E value)832 Primitive(E value) 833 : Primitive(static_cast<typename std::underlying_type<E>::type>(value)) { } 834 Primitive()835 Primitive() : u64(0) { } 836 837 /** gets value out of the union */ 838 template<typename T> const T &ref() const; 839 840 // verify that we can assume standard aliasing 841 static_assert(sizeof(u64) == sizeof(i64), ""); 842 static_assert(sizeof(u64) == sizeof(c64), ""); 843 static_assert(sizeof(u32) == sizeof(i32), ""); 844 static_assert(sizeof(u32) == sizeof(c32), ""); 845 }; 846 // verify that we can assume standard aliasing 847 static_assert(offsetof(Primitive, u64) == offsetof(Primitive, i64), ""); 848 static_assert(offsetof(Primitive, u64) == offsetof(Primitive, c64), ""); 849 static_assert(offsetof(Primitive, u32) == offsetof(Primitive, i32), ""); 850 static_assert(offsetof(Primitive, u32) == offsetof(Primitive, c32), ""); 851 852 enum type_t : uint32_t { 853 NO_INIT, 854 INT32, 855 UINT32, 856 CNTR32, 857 INT64, 858 UINT64, 859 CNTR64, 860 FLOAT, 861 }; 862 863 template<typename T, bool = std::is_enum<T>::value> TypeFor()864 inline static constexpr type_t TypeFor() { 865 using U = typename std::underlying_type<T>::type; 866 return TypeFor<U>(); 867 } 868 869 // deprectated 870 template<typename T, bool B = std::is_enum<T>::value> typeFor()871 inline static constexpr type_t typeFor() { 872 return TypeFor<T, B>(); 873 } 874 875 // constructors - implicit 876 template<typename T> C2Value(T value)877 C2Value(T value) : _mType(typeFor<T>()), _mValue(value) { } 878 C2Value()879 C2Value() : _mType(NO_INIT) { } 880 type()881 inline type_t type() const { return _mType; } 882 883 template<typename T> get(T * value)884 inline bool get(T *value) const { 885 if (_mType == typeFor<T>()) { 886 *value = _mValue.ref<T>(); 887 return true; 888 } 889 return false; 890 } 891 892 /// returns the address of the value get()893 void *get() const { 894 return _mType == NO_INIT ? nullptr : (void*)&_mValue; 895 } 896 897 /// returns the size of the contained value sizeOf()898 size_t inline sizeOf() const { 899 return SizeFor(_mType); 900 } 901 SizeFor(type_t type)902 static size_t SizeFor(type_t type) { 903 switch (type) { 904 case INT32: 905 case UINT32: 906 case CNTR32: return sizeof(_mValue.i32); 907 case INT64: 908 case UINT64: 909 case CNTR64: return sizeof(_mValue.i64); 910 case FLOAT: return sizeof(_mValue.fp); 911 default: return 0; 912 } 913 } 914 915 private: 916 type_t _mType; 917 Primitive _mValue; 918 }; 919 920 template<> inline const int32_t &C2Value::Primitive::ref<int32_t>() const { return i32; } 921 template<> inline const int64_t &C2Value::Primitive::ref<int64_t>() const { return i64; } 922 template<> inline const uint32_t &C2Value::Primitive::ref<uint32_t>() const { return u32; } 923 template<> inline const uint64_t &C2Value::Primitive::ref<uint64_t>() const { return u64; } 924 template<> inline const c2_cntr32_t &C2Value::Primitive::ref<c2_cntr32_t>() const { return c32; } 925 template<> inline const c2_cntr64_t &C2Value::Primitive::ref<c2_cntr64_t>() const { return c64; } 926 template<> inline const float &C2Value::Primitive::ref<float>() const { return fp; } 927 928 // provide types for enums and uint8_t, char even though we don't provide reading as them 929 template<> constexpr C2Value::type_t C2Value::TypeFor<char, false>() { return INT32; } 930 template<> constexpr C2Value::type_t C2Value::TypeFor<int32_t, false>() { return INT32; } 931 template<> constexpr C2Value::type_t C2Value::TypeFor<int64_t, false>() { return INT64; } 932 template<> constexpr C2Value::type_t C2Value::TypeFor<uint8_t, false>() { return UINT32; } 933 template<> constexpr C2Value::type_t C2Value::TypeFor<uint32_t, false>() { return UINT32; } 934 template<> constexpr C2Value::type_t C2Value::TypeFor<uint64_t, false>() { return UINT64; } 935 template<> constexpr C2Value::type_t C2Value::TypeFor<c2_cntr32_t, false>() { return CNTR32; } 936 template<> constexpr C2Value::type_t C2Value::TypeFor<c2_cntr64_t, false>() { return CNTR64; } 937 template<> constexpr C2Value::type_t C2Value::TypeFor<float, false>() { return FLOAT; } 938 939 // forward declare easy enum template 940 template<typename E> struct C2EasyEnum; 941 942 /** 943 * field descriptor. A field is uniquely defined by an index into a parameter. 944 * (Note: Stream-id is not captured as a field.) 945 * 946 * Ordering of fields is by offset. In case of structures, it is depth first, 947 * with a structure taking an index just before and in addition to its members. 948 */ 949 struct C2FieldDescriptor { 950 //public: 951 /** field types and flags 952 * \note: only 32-bit and 64-bit fields are supported (e.g. no boolean, as that 953 * is represented using INT32). 954 */ 955 enum type_t : uint32_t { 956 // primitive types 957 INT32 = C2Value::INT32, ///< 32-bit signed integer 958 UINT32 = C2Value::UINT32, ///< 32-bit unsigned integer 959 CNTR32 = C2Value::CNTR32, ///< 32-bit counter 960 INT64 = C2Value::INT64, ///< 64-bit signed integer 961 UINT64 = C2Value::UINT64, ///< 64-bit signed integer 962 CNTR64 = C2Value::CNTR64, ///< 64-bit counter 963 FLOAT = C2Value::FLOAT, ///< 32-bit floating point 964 965 // array types 966 STRING = 0x100, ///< fixed-size string (POD) 967 BLOB, ///< blob. Blobs have no sub-elements and can be thought of as byte arrays; 968 ///< however, bytes cannot be individually addressed by clients. 969 970 // complex types 971 STRUCT_FLAG = 0x20000, ///< structs. Marked with this flag in addition to their coreIndex. 972 }; 973 974 typedef std::pair<C2String, C2Value::Primitive> NamedValueType; 975 typedef std::vector<NamedValueType> NamedValuesType; 976 //typedef std::pair<std::vector<C2String>, std::vector<C2Value::Primitive>> NamedValuesType; 977 978 /** 979 * Template specialization that returns the named values for a type. 980 * 981 * \todo hide from client. 982 * 983 * \return a vector of name-value pairs. 984 */ 985 template<typename B> 986 static NamedValuesType namedValuesFor(const B &); 987 988 /** specialization for easy enums */ 989 template<typename E> namedValuesForC2FieldDescriptor990 inline static NamedValuesType namedValuesFor(const C2EasyEnum<E> &) { 991 #pragma GCC diagnostic push 992 #pragma GCC diagnostic ignored "-Wnull-dereference" 993 return namedValuesFor(*(E*)nullptr); 994 #pragma GCC diagnostic pop 995 } 996 997 private: 998 template<typename B, bool enabled=std::is_arithmetic<B>::value || std::is_enum<B>::value> 999 struct C2_HIDE _NamedValuesGetter; 1000 1001 public: C2FieldDescriptorC2FieldDescriptor1002 inline C2FieldDescriptor(uint32_t type, uint32_t extent, C2String name, size_t offset, size_t size) 1003 : _mType((type_t)type), _mExtent(extent), _mName(name), _mFieldId(offset, size) { } 1004 1005 inline C2FieldDescriptor(const C2FieldDescriptor &) = default; 1006 1007 template<typename T, class B=typename std::remove_extent<T>::type> C2FieldDescriptorC2FieldDescriptor1008 inline C2FieldDescriptor(const T* offset, const char *name) 1009 : _mType(this->GetType((B*)nullptr)), 1010 _mExtent(std::is_array<T>::value ? std::extent<T>::value : 1), 1011 _mName(name), 1012 _mNamedValues(_NamedValuesGetter<B>::getNamedValues()), 1013 _mFieldId(offset) {} 1014 1015 /* 1016 template<typename T, typename B=typename std::remove_extent<T>::type> 1017 inline C2FieldDescriptor<T, B, false>(T* offset, const char *name) 1018 : _mType(this->GetType((B*)nullptr)), 1019 _mExtent(std::is_array<T>::value ? std::extent<T>::value : 1), 1020 _mName(name), 1021 _mFieldId(offset) {} 1022 */ 1023 1024 /// \deprecated 1025 template<typename T, typename S, class B=typename std::remove_extent<T>::type> C2FieldDescriptorC2FieldDescriptor1026 inline C2FieldDescriptor(S*, T S::* field, const char *name) 1027 : _mType(this->GetType((B*)nullptr)), 1028 _mExtent(std::is_array<T>::value ? std::extent<T>::value : 1), 1029 _mName(name), 1030 _mFieldId(&(((S*)0)->*field)) {} 1031 1032 /// returns the type of this field typeC2FieldDescriptor1033 inline type_t type() const { return _mType; } 1034 /// returns the length of the field in case it is an array. Returns 0 for 1035 /// T[] arrays, returns 1 for T[1] arrays as well as if the field is not an array. extentC2FieldDescriptor1036 inline size_t extent() const { return _mExtent; } 1037 /// returns the name of the field nameC2FieldDescriptor1038 inline C2String name() const { return _mName; } 1039 namedValuesC2FieldDescriptor1040 const NamedValuesType &namedValues() const { return _mNamedValues; } 1041 1042 #if defined(FRIEND_TEST) 1043 friend void PrintTo(const C2FieldDescriptor &, ::std::ostream*); 1044 friend bool operator==(const C2FieldDescriptor &, const C2FieldDescriptor &); 1045 FRIEND_TEST(C2ParamTest_ParamFieldList, VerifyStruct); 1046 #endif 1047 1048 private: 1049 /** 1050 * Construct an offseted field descriptor. 1051 */ C2FieldDescriptorC2FieldDescriptor1052 inline C2FieldDescriptor(const C2FieldDescriptor &desc, size_t offset) 1053 : _mType(desc._mType), _mExtent(desc._mExtent), 1054 _mName(desc._mName), _mNamedValues(desc._mNamedValues), 1055 _mFieldId(desc._mFieldId._mOffset + offset, desc._mFieldId._mSize) { } 1056 1057 type_t _mType; 1058 uint32_t _mExtent; // the last member can be arbitrary length if it is T[] array, 1059 // extending to the end of the parameter (this is marked with 1060 // 0). T[0]-s are not fields. 1061 C2String _mName; 1062 NamedValuesType _mNamedValues; 1063 1064 _C2FieldId _mFieldId; // field identifier (offset and size) 1065 1066 // NOTE: We do not capture default value(s) here as that may depend on the component. 1067 // NOTE: We also do not capture bestEffort, as 1) this should be true for most fields, 1068 // 2) this is at parameter granularity. 1069 1070 // type resolution GetTypeC2FieldDescriptor1071 inline static type_t GetType(int32_t*) { return INT32; } GetTypeC2FieldDescriptor1072 inline static type_t GetType(uint32_t*) { return UINT32; } GetTypeC2FieldDescriptor1073 inline static type_t GetType(c2_cntr32_t*) { return CNTR32; } GetTypeC2FieldDescriptor1074 inline static type_t GetType(int64_t*) { return INT64; } GetTypeC2FieldDescriptor1075 inline static type_t GetType(uint64_t*) { return UINT64; } GetTypeC2FieldDescriptor1076 inline static type_t GetType(c2_cntr64_t*) { return CNTR64; } GetTypeC2FieldDescriptor1077 inline static type_t GetType(float*) { return FLOAT; } GetTypeC2FieldDescriptor1078 inline static type_t GetType(char*) { return STRING; } GetTypeC2FieldDescriptor1079 inline static type_t GetType(uint8_t*) { return BLOB; } 1080 1081 template<typename T, 1082 class=typename std::enable_if<std::is_enum<T>::value>::type> GetTypeC2FieldDescriptor1083 inline static type_t GetType(T*) { 1084 typename std::underlying_type<T>::type underlying(0); 1085 return GetType(&underlying); 1086 } 1087 1088 // verify C2Struct by having a FieldList() and a CORE_INDEX. 1089 template<typename T, 1090 class=decltype(T::CORE_INDEX + 1), class=decltype(T::FieldList())> GetTypeC2FieldDescriptor1091 inline static type_t GetType(T*) { 1092 static_assert(!std::is_base_of<C2Param, T>::value, "cannot use C2Params as fields"); 1093 return (type_t)(T::CORE_INDEX | STRUCT_FLAG); 1094 } 1095 1096 friend struct _C2ParamInspector; 1097 }; 1098 1099 // no named values for compound types 1100 template<typename B> 1101 struct C2FieldDescriptor::_NamedValuesGetter<B, false> { 1102 inline static C2FieldDescriptor::NamedValuesType getNamedValues() { 1103 return NamedValuesType(); 1104 } 1105 }; 1106 1107 template<typename B> 1108 struct C2FieldDescriptor::_NamedValuesGetter<B, true> { 1109 inline static C2FieldDescriptor::NamedValuesType getNamedValues() { 1110 #pragma GCC diagnostic push 1111 #pragma GCC diagnostic ignored "-Wnull-dereference" 1112 return C2FieldDescriptor::namedValuesFor(*(B*)nullptr); 1113 #pragma GCC diagnostic pop 1114 } 1115 }; 1116 1117 #define DEFINE_NO_NAMED_VALUES_FOR(type) \ 1118 template<> inline C2FieldDescriptor::NamedValuesType C2FieldDescriptor::namedValuesFor(const type &) { \ 1119 return NamedValuesType(); \ 1120 } 1121 1122 // We cannot subtype constructor for enumerated types so insted define no named values for 1123 // non-enumerated integral types. 1124 DEFINE_NO_NAMED_VALUES_FOR(int32_t) 1125 DEFINE_NO_NAMED_VALUES_FOR(uint32_t) 1126 DEFINE_NO_NAMED_VALUES_FOR(c2_cntr32_t) 1127 DEFINE_NO_NAMED_VALUES_FOR(int64_t) 1128 DEFINE_NO_NAMED_VALUES_FOR(uint64_t) 1129 DEFINE_NO_NAMED_VALUES_FOR(c2_cntr64_t) 1130 DEFINE_NO_NAMED_VALUES_FOR(uint8_t) 1131 DEFINE_NO_NAMED_VALUES_FOR(char) 1132 DEFINE_NO_NAMED_VALUES_FOR(float) 1133 1134 /** 1135 * Describes the fields of a structure. 1136 */ 1137 struct C2StructDescriptor { 1138 public: 1139 /// Returns the core index of the struct 1140 inline C2Param::CoreIndex coreIndex() const { return _mType.coreIndex(); } 1141 1142 // Returns the number of fields in this struct (not counting any recursive fields). 1143 // Must be at least 1 for valid structs. 1144 inline size_t numFields() const { return _mFields.size(); } 1145 1146 // Returns the list of direct fields (not counting any recursive fields). 1147 typedef std::vector<C2FieldDescriptor>::const_iterator field_iterator; 1148 inline field_iterator cbegin() const { return _mFields.cbegin(); } 1149 inline field_iterator cend() const { return _mFields.cend(); } 1150 1151 // only supplying const iterator - but these names are needed for range based loops 1152 inline field_iterator begin() const { return _mFields.cbegin(); } 1153 inline field_iterator end() const { return _mFields.cend(); } 1154 1155 template<typename T> 1156 inline C2StructDescriptor(T*) 1157 : C2StructDescriptor(T::CORE_INDEX, T::FieldList()) { } 1158 1159 inline C2StructDescriptor( 1160 C2Param::CoreIndex type, 1161 const std::vector<C2FieldDescriptor> &fields) 1162 : _mType(type), _mFields(fields) { } 1163 1164 private: 1165 friend struct _C2ParamInspector; 1166 1167 inline C2StructDescriptor( 1168 C2Param::CoreIndex type, 1169 std::vector<C2FieldDescriptor> &&fields) 1170 : _mType(type), _mFields(std::move(fields)) { } 1171 1172 const C2Param::CoreIndex _mType; 1173 const std::vector<C2FieldDescriptor> _mFields; 1174 }; 1175 1176 /** 1177 * Describes parameters for a component. 1178 */ 1179 struct C2ParamDescriptor { 1180 public: 1181 /** 1182 * Returns whether setting this param is required to configure this component. 1183 * This can only be true for builtin params for platform-defined components (e.g. video and 1184 * audio encoders/decoders, video/audio filters). 1185 * For vendor-defined components, it can be true even for vendor-defined params, 1186 * but it is not recommended, in case the component becomes platform-defined. 1187 */ 1188 inline bool isRequired() const { return _mAttrib & IS_REQUIRED; } 1189 1190 /** 1191 * Returns whether this parameter is persistent. This is always true for C2Tuning and C2Setting, 1192 * but may be false for C2Info. If true, this parameter persists across frames and applies to 1193 * the current and subsequent frames. If false, this C2Info parameter only applies to the 1194 * current frame and is not assumed to have the same value (or even be present) on subsequent 1195 * frames, unless it is specified for those frames. 1196 */ 1197 inline bool isPersistent() const { return _mAttrib & IS_PERSISTENT; } 1198 1199 inline bool isStrict() const { return _mAttrib & IS_STRICT; } 1200 1201 inline bool isReadOnly() const { return _mAttrib & IS_READ_ONLY; } 1202 1203 inline bool isVisible() const { return !(_mAttrib & IS_HIDDEN); } 1204 1205 inline bool isPublic() const { return !(_mAttrib & IS_INTERNAL); } 1206 1207 /// Returns the name of this param. 1208 /// This defaults to the underlying C2Struct's name, but could be altered for a component. 1209 inline C2String name() const { return _mName; } 1210 1211 /// Returns the parameter index 1212 inline C2Param::Index index() const { return _mIndex; } 1213 1214 /// Returns the indices of parameters that this parameter has a dependency on 1215 inline const std::vector<C2Param::Index> &dependencies() const { return _mDependencies; } 1216 1217 /// \deprecated 1218 template<typename T> 1219 inline C2ParamDescriptor(bool isRequired, C2StringLiteral name, const T*) 1220 : _mIndex(T::PARAM_TYPE), 1221 _mAttrib(IS_PERSISTENT | (isRequired ? IS_REQUIRED : 0)), 1222 _mName(name) { } 1223 1224 /// \deprecated 1225 inline C2ParamDescriptor( 1226 bool isRequired, C2StringLiteral name, C2Param::Index index) 1227 : _mIndex(index), 1228 _mAttrib(IS_PERSISTENT | (isRequired ? IS_REQUIRED : 0)), 1229 _mName(name) { } 1230 1231 enum attrib_t : uint32_t { 1232 // flags that default on 1233 IS_REQUIRED = 1u << 0, ///< parameter is required to be specified 1234 IS_PERSISTENT = 1u << 1, ///< parameter retains its value 1235 // flags that default off 1236 IS_STRICT = 1u << 2, ///< parameter is strict 1237 IS_READ_ONLY = 1u << 3, ///< parameter is publicly read-only 1238 IS_HIDDEN = 1u << 4, ///< parameter shall not be visible to clients 1239 IS_INTERNAL = 1u << 5, ///< parameter shall not be used by framework (other than testing) 1240 IS_CONST = 1u << 6 | IS_READ_ONLY, ///< parameter is publicly const (hence read-only) 1241 }; 1242 1243 inline C2ParamDescriptor( 1244 C2Param::Index index, attrib_t attrib, C2StringLiteral name) 1245 : _mIndex(index), 1246 _mAttrib(attrib), 1247 _mName(name) { } 1248 1249 inline C2ParamDescriptor( 1250 C2Param::Index index, attrib_t attrib, C2String &&name, 1251 std::vector<C2Param::Index> &&dependencies) 1252 : _mIndex(index), 1253 _mAttrib(attrib), 1254 _mName(name), 1255 _mDependencies(std::move(dependencies)) { } 1256 1257 private: 1258 const C2Param::Index _mIndex; 1259 const uint32_t _mAttrib; 1260 const C2String _mName; 1261 std::vector<C2Param::Index> _mDependencies; 1262 1263 friend struct _C2ParamInspector; 1264 }; 1265 1266 DEFINE_ENUM_OPERATORS(::C2ParamDescriptor::attrib_t) 1267 1268 1269 /// \ingroup internal 1270 /// Define a structure without CORE_INDEX. 1271 /// \note _FIELD_LIST is used only during declaration so that C2Struct declarations can end with 1272 /// a simple list of C2FIELD-s and closing bracket. Mark it unused as it is not used in templated 1273 /// structs. 1274 #define DEFINE_BASE_C2STRUCT(name) \ 1275 private: \ 1276 const static std::vector<C2FieldDescriptor> _FIELD_LIST __unused; /**< structure fields */ \ 1277 public: \ 1278 typedef C2##name##Struct _type; /**< type name shorthand */ \ 1279 static const std::vector<C2FieldDescriptor> FieldList(); /**< structure fields factory */ 1280 1281 /// Define a structure with matching CORE_INDEX. 1282 #define DEFINE_C2STRUCT(name) \ 1283 public: \ 1284 enum : uint32_t { CORE_INDEX = kParamIndex##name }; \ 1285 DEFINE_BASE_C2STRUCT(name) 1286 1287 /// Define a flexible structure without CORE_INDEX. 1288 #define DEFINE_BASE_FLEX_C2STRUCT(name, flexMember) \ 1289 public: \ 1290 FLEX(C2##name##Struct, flexMember) \ 1291 DEFINE_BASE_C2STRUCT(name) 1292 1293 /// Define a flexible structure with matching CORE_INDEX. 1294 #define DEFINE_FLEX_C2STRUCT(name, flexMember) \ 1295 public: \ 1296 FLEX(C2##name##Struct, flexMember) \ 1297 enum : uint32_t { CORE_INDEX = kParamIndex##name | C2Param::CoreIndex::IS_FLEX_FLAG }; \ 1298 DEFINE_BASE_C2STRUCT(name) 1299 1300 /// \ingroup internal 1301 /// Describe a structure of a templated structure. 1302 // Use list... as the argument gets resubsitituted and it contains commas. Alternative would be 1303 // to wrap list in an expression, e.g. ({ std::vector<C2FieldDescriptor> list; })) which converts 1304 // it from an initializer list to a vector. 1305 #define DESCRIBE_TEMPLATED_C2STRUCT(strukt, list...) \ 1306 _DESCRIBE_TEMPLATABLE_C2STRUCT(template<>, strukt, __C2_GENERATE_GLOBAL_VARS__, list) 1307 1308 /// \deprecated 1309 /// Describe the fields of a structure using an initializer list. 1310 #define DESCRIBE_C2STRUCT(name, list...) \ 1311 _DESCRIBE_TEMPLATABLE_C2STRUCT(, C2##name##Struct, __C2_GENERATE_GLOBAL_VARS__, list) 1312 1313 /// \ingroup internal 1314 /// Macro layer to get value of enabled that is passed in as a macro variable 1315 #define _DESCRIBE_TEMPLATABLE_C2STRUCT(template, strukt, enabled, list...) \ 1316 __DESCRIBE_TEMPLATABLE_C2STRUCT(template, strukt, enabled, list) 1317 1318 /// \ingroup internal 1319 /// Macro layer to resolve to the specific macro based on macro variable 1320 #define __DESCRIBE_TEMPLATABLE_C2STRUCT(template, strukt, enabled, list...) \ 1321 ___DESCRIBE_TEMPLATABLE_C2STRUCT##enabled(template, strukt, list) 1322 1323 #define ___DESCRIBE_TEMPLATABLE_C2STRUCT(template, strukt, list...) \ 1324 template \ 1325 const std::vector<C2FieldDescriptor> strukt::FieldList() { return list; } 1326 1327 #define ___DESCRIBE_TEMPLATABLE_C2STRUCT__C2_GENERATE_GLOBAL_VARS__(template, strukt, list...) 1328 1329 /** 1330 * Describe a field of a structure. 1331 * These must be in order. 1332 * 1333 * There are two ways to use this macro: 1334 * 1335 * ~~~~~~~~~~~~~ (.cpp) 1336 * struct C2VideoWidthStruct { 1337 * int32_t width; 1338 * C2VideoWidthStruct() {} // optional default constructor 1339 * C2VideoWidthStruct(int32_t _width) : width(_width) {} 1340 * 1341 * DEFINE_AND_DESCRIBE_C2STRUCT(VideoWidth) 1342 * C2FIELD(width, "width") 1343 * }; 1344 * ~~~~~~~~~~~~~ 1345 * 1346 * ~~~~~~~~~~~~~ (.cpp) 1347 * struct C2VideoWidthStruct { 1348 * int32_t width; 1349 * C2VideoWidthStruct() = default; // optional default constructor 1350 * C2VideoWidthStruct(int32_t _width) : width(_width) {} 1351 * 1352 * DEFINE_C2STRUCT(VideoWidth) 1353 * } C2_PACK; 1354 * 1355 * DESCRIBE_C2STRUCT(VideoWidth, { 1356 * C2FIELD(width, "width") 1357 * }) 1358 * ~~~~~~~~~~~~~ 1359 * 1360 * For flexible structures (those ending in T[]), use the flexible macros: 1361 * 1362 * ~~~~~~~~~~~~~ (.cpp) 1363 * struct C2VideoFlexWidthsStruct { 1364 * int32_t widths[]; 1365 * C2VideoFlexWidthsStruct(); // must have a default constructor 1366 * 1367 * private: 1368 * // may have private constructors taking number of widths as the first argument 1369 * // This is used by the C2Param factory methods, e.g. 1370 * // C2VideoFlexWidthsGlobalParam::AllocUnique(size_t, int32_t); 1371 * C2VideoFlexWidthsStruct(size_t flexCount, int32_t value) { 1372 * for (size_t i = 0; i < flexCount; ++i) { 1373 * widths[i] = value; 1374 * } 1375 * } 1376 * 1377 * // If the last argument is T[N] or std::initializer_list<T>, the flexCount will 1378 * // be automatically calculated and passed by the C2Param factory methods, e.g. 1379 * // int widths[] = { 1, 2, 3 }; 1380 * // C2VideoFlexWidthsGlobalParam::AllocUnique(widths); 1381 * template<unsigned N> 1382 * C2VideoFlexWidthsStruct(size_t flexCount, const int32_t(&init)[N]) { 1383 * for (size_t i = 0; i < flexCount; ++i) { 1384 * widths[i] = init[i]; 1385 * } 1386 * } 1387 * 1388 * DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(VideoFlexWidths, widths) 1389 * C2FIELD(widths, "widths") 1390 * }; 1391 * ~~~~~~~~~~~~~ 1392 * 1393 * ~~~~~~~~~~~~~ (.cpp) 1394 * struct C2VideoFlexWidthsStruct { 1395 * int32_t mWidths[]; 1396 * C2VideoFlexWidthsStruct(); // must have a default constructor 1397 * 1398 * DEFINE_FLEX_C2STRUCT(VideoFlexWidths, mWidths) 1399 * } C2_PACK; 1400 * 1401 * DESCRIBE_C2STRUCT(VideoFlexWidths, { 1402 * C2FIELD(mWidths, "widths") 1403 * }) 1404 * ~~~~~~~~~~~~~ 1405 * 1406 */ 1407 #define DESCRIBE_C2FIELD(member, name) \ 1408 C2FieldDescriptor(&((_type*)(nullptr))->member, name), 1409 1410 #define C2FIELD(member, name) _C2FIELD(member, name, __C2_GENERATE_GLOBAL_VARS__) 1411 /// \if 0 1412 #define _C2FIELD(member, name, enabled) __C2FIELD(member, name, enabled) 1413 #define __C2FIELD(member, name, enabled) DESCRIBE_C2FIELD##enabled(member, name) 1414 #define DESCRIBE_C2FIELD__C2_GENERATE_GLOBAL_VARS__(member, name) 1415 /// \endif 1416 1417 /// Define a structure with matching CORE_INDEX and start describing its fields. 1418 /// This must be at the end of the structure definition. 1419 #define DEFINE_AND_DESCRIBE_C2STRUCT(name) \ 1420 _DEFINE_AND_DESCRIBE_C2STRUCT(name, DEFINE_C2STRUCT, __C2_GENERATE_GLOBAL_VARS__) 1421 1422 /// Define a base structure (with no CORE_INDEX) and start describing its fields. 1423 /// This must be at the end of the structure definition. 1424 #define DEFINE_AND_DESCRIBE_BASE_C2STRUCT(name) \ 1425 _DEFINE_AND_DESCRIBE_C2STRUCT(name, DEFINE_BASE_C2STRUCT, __C2_GENERATE_GLOBAL_VARS__) 1426 1427 /// Define a flexible structure with matching CORE_INDEX and start describing its fields. 1428 /// This must be at the end of the structure definition. 1429 #define DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(name, flexMember) \ 1430 _DEFINE_AND_DESCRIBE_FLEX_C2STRUCT( \ 1431 name, flexMember, DEFINE_FLEX_C2STRUCT, __C2_GENERATE_GLOBAL_VARS__) 1432 1433 /// Define a flexible base structure (with no CORE_INDEX) and start describing its fields. 1434 /// This must be at the end of the structure definition. 1435 #define DEFINE_AND_DESCRIBE_BASE_FLEX_C2STRUCT(name, flexMember) \ 1436 _DEFINE_AND_DESCRIBE_FLEX_C2STRUCT( \ 1437 name, flexMember, DEFINE_BASE_FLEX_C2STRUCT, __C2_GENERATE_GLOBAL_VARS__) 1438 1439 /// \if 0 1440 /* 1441 Alternate declaration of field definitions in case no field list is to be generated. 1442 The specific macro is chosed based on the value of __C2_GENERATE_GLOBAL_VARS__ (whether it is 1443 defined (to be empty) or not. This requires two level of macro substitution. 1444 TRICKY: use namespace declaration to handle closing bracket that is normally after 1445 these macros. 1446 */ 1447 1448 #define _DEFINE_AND_DESCRIBE_C2STRUCT(name, defineMacro, enabled) \ 1449 __DEFINE_AND_DESCRIBE_C2STRUCT(name, defineMacro, enabled) 1450 #define __DEFINE_AND_DESCRIBE_C2STRUCT(name, defineMacro, enabled) \ 1451 ___DEFINE_AND_DESCRIBE_C2STRUCT##enabled(name, defineMacro) 1452 #define ___DEFINE_AND_DESCRIBE_C2STRUCT__C2_GENERATE_GLOBAL_VARS__(name, defineMacro) \ 1453 defineMacro(name) } C2_PACK; namespace { 1454 #define ___DEFINE_AND_DESCRIBE_C2STRUCT(name, defineMacro) \ 1455 defineMacro(name) } C2_PACK; \ 1456 const std::vector<C2FieldDescriptor> C2##name##Struct::FieldList() { return _FIELD_LIST; } \ 1457 const std::vector<C2FieldDescriptor> C2##name##Struct::_FIELD_LIST = { 1458 1459 #define _DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(name, flexMember, defineMacro, enabled) \ 1460 __DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(name, flexMember, defineMacro, enabled) 1461 #define __DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(name, flexMember, defineMacro, enabled) \ 1462 ___DEFINE_AND_DESCRIBE_FLEX_C2STRUCT##enabled(name, flexMember, defineMacro) 1463 #define ___DEFINE_AND_DESCRIBE_FLEX_C2STRUCT__C2_GENERATE_GLOBAL_VARS__(name, flexMember, defineMacro) \ 1464 defineMacro(name, flexMember) } C2_PACK; namespace { 1465 #define ___DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(name, flexMember, defineMacro) \ 1466 defineMacro(name, flexMember) } C2_PACK; \ 1467 const std::vector<C2FieldDescriptor> C2##name##Struct::FieldList() { return _FIELD_LIST; } \ 1468 const std::vector<C2FieldDescriptor> C2##name##Struct::_FIELD_LIST = { 1469 /// \endif 1470 1471 1472 /** 1473 * Parameter reflector class. 1474 * 1475 * This class centralizes the description of parameter structures. This can be shared 1476 * by multiple components as describing a parameter does not imply support of that 1477 * parameter. However, each supported parameter and any dependent structures within 1478 * must be described by the parameter reflector provided by a component. 1479 */ 1480 class C2ParamReflector { 1481 public: 1482 /** 1483 * Describes a parameter structure. 1484 * 1485 * \param[in] coreIndex the core index of the parameter structure containing at least the 1486 * core index 1487 * 1488 * \return the description of the parameter structure 1489 * \retval nullptr if the parameter is not supported by this reflector 1490 * 1491 * This methods shall not block and return immediately. 1492 * 1493 * \note this class does not take a set of indices because we would then prefer 1494 * to also return any dependent structures, and we don't want this logic to be 1495 * repeated in each reflector. Alternately, this could just return a map of all 1496 * descriptions, but we want to conserve memory if client only wants the description 1497 * of a few indices. 1498 */ 1499 virtual std::unique_ptr<C2StructDescriptor> describe(C2Param::CoreIndex coreIndex) const = 0; 1500 1501 protected: 1502 virtual ~C2ParamReflector() = default; 1503 }; 1504 1505 /** 1506 * Generic supported values for a field. 1507 * 1508 * This can be either a range or a set of values. The range can be a simple range, an arithmetic, 1509 * geometric or multiply-accumulate series with a clear minimum and maximum value. Values can 1510 * be discrete values, or can optionally represent flags to be or-ed. 1511 * 1512 * \note Do not use flags to represent bitfields. Use individual values or separate fields instead. 1513 */ 1514 struct C2FieldSupportedValues { 1515 //public: 1516 enum type_t { 1517 EMPTY, ///< no supported values 1518 RANGE, ///< a numeric range that can be continuous or discrete 1519 VALUES, ///< a list of values 1520 FLAGS ///< a list of flags that can be OR-ed 1521 }; 1522 1523 type_t type; /** Type of values for this field. */ 1524 1525 typedef C2Value::Primitive Primitive; 1526 1527 /** 1528 * Range specifier for supported value. Used if type is RANGE. 1529 * 1530 * If step is 0 and num and denom are both 1, the supported values are any value, for which 1531 * min <= value <= max. 1532 * 1533 * Otherwise, the range represents a geometric/arithmetic/multiply-accumulate series, where 1534 * successive supported values can be derived from previous values (starting at min), using the 1535 * following formula: 1536 * v[0] = min 1537 * v[i] = v[i-1] * num / denom + step for i >= 1, while min < v[i] <= max. 1538 */ 1539 struct { 1540 /** Lower end of the range (inclusive). */ 1541 Primitive min; 1542 /** Upper end of the range (inclusive if permitted by series). */ 1543 Primitive max; 1544 /** Step between supported values. */ 1545 Primitive step; 1546 /** Numerator of a geometric series. */ 1547 Primitive num; 1548 /** Denominator of a geometric series. */ 1549 Primitive denom; 1550 } range; 1551 1552 /** 1553 * List of values. Used if type is VALUES or FLAGS. 1554 * 1555 * If type is VALUES, this is the list of supported values in decreasing preference. 1556 * 1557 * If type is FLAGS, this vector contains { min-mask, flag1, flag2... }. Basically, the first 1558 * value is the required set of flags to be set, and the rest of the values are flags that can 1559 * be set independently. FLAGS is only supported for integral types. Supported flags should 1560 * not overlap, as it can make validation non-deterministic. The standard validation method 1561 * is that starting from the original value, if each flag is removed when fully present (the 1562 * min-mask must be fully present), we shall arrive at 0. 1563 */ 1564 std::vector<Primitive> values; 1565 1566 C2FieldSupportedValues() 1567 : type(EMPTY) { 1568 } 1569 1570 template<typename T> 1571 C2FieldSupportedValues(T min, T max, T step = T(std::is_floating_point<T>::value ? 0 : 1)) 1572 : type(RANGE), 1573 range{min, max, step, (T)1, (T)1} { } 1574 1575 template<typename T> 1576 C2FieldSupportedValues(T min, T max, T num, T den) : 1577 type(RANGE), 1578 range{min, max, (T)0, num, den} { } 1579 1580 template<typename T> 1581 C2FieldSupportedValues(T min, T max, T step, T num, T den) 1582 : type(RANGE), 1583 range{min, max, step, num, den} { } 1584 1585 /// \deprecated 1586 template<typename T> 1587 C2FieldSupportedValues(bool flags, std::initializer_list<T> list) 1588 : type(flags ? FLAGS : VALUES), 1589 range{(T)0, (T)0, (T)0, (T)0, (T)0} { 1590 for (T value : list) { 1591 values.emplace_back(value); 1592 } 1593 } 1594 1595 /// \deprecated 1596 template<typename T> 1597 C2FieldSupportedValues(bool flags, const std::vector<T>& list) 1598 : type(flags ? FLAGS : VALUES), 1599 range{(T)0, (T)0, (T)0, (T)0, (T)0} { 1600 for(T value : list) { 1601 values.emplace_back(value); 1602 } 1603 } 1604 1605 /// \internal 1606 /// \todo: create separate values vs. flags initializer as for flags we want 1607 /// to list both allowed and required flags 1608 #pragma GCC diagnostic push 1609 #pragma GCC diagnostic ignored "-Wnull-dereference" 1610 template<typename T, typename E=decltype(C2FieldDescriptor::namedValuesFor(*(T*)nullptr))> 1611 C2FieldSupportedValues(bool flags, const T*) 1612 : type(flags ? FLAGS : VALUES), 1613 range{(T)0, (T)0, (T)0, (T)0, (T)0} { 1614 C2FieldDescriptor::NamedValuesType named = C2FieldDescriptor::namedValuesFor(*(T*)nullptr); 1615 if (flags) { 1616 values.emplace_back(0); // min-mask defaults to 0 1617 } 1618 for (const C2FieldDescriptor::NamedValueType &item : named){ 1619 values.emplace_back(item.second); 1620 } 1621 } 1622 }; 1623 #pragma GCC diagnostic pop 1624 1625 /** 1626 * Supported values for a specific field. 1627 * 1628 * This is a pair of the field specifier together with an optional supported values object. 1629 * This structure is used when reporting parameter configuration failures and conflicts. 1630 */ 1631 struct C2ParamFieldValues { 1632 C2ParamField paramOrField; ///< the field or parameter 1633 /// optional supported values for the field if paramOrField specifies an actual field that is 1634 /// numeric (non struct, blob or string). Supported values for arrays (including string and 1635 /// blobs) describe the supported values for each element (character for string, and bytes for 1636 /// blobs). It is optional for read-only strings and blobs. 1637 std::unique_ptr<C2FieldSupportedValues> values; 1638 1639 // This struct is meant to be move constructed. 1640 C2_DEFAULT_MOVE(C2ParamFieldValues); 1641 1642 // Copy constructor/assignment is also provided as this object may get copied. 1643 C2ParamFieldValues(const C2ParamFieldValues &other) 1644 : paramOrField(other.paramOrField), 1645 values(other.values ? std::make_unique<C2FieldSupportedValues>(*other.values) : nullptr) { } 1646 1647 C2ParamFieldValues& operator=(const C2ParamFieldValues &other) { 1648 paramOrField = other.paramOrField; 1649 values = other.values ? std::make_unique<C2FieldSupportedValues>(*other.values) : nullptr; 1650 return *this; 1651 } 1652 1653 1654 /** 1655 * Construct with no values. 1656 */ 1657 C2ParamFieldValues(const C2ParamField ¶mOrField_) 1658 : paramOrField(paramOrField_) { } 1659 1660 /** 1661 * Construct with values. 1662 */ 1663 C2ParamFieldValues(const C2ParamField ¶mOrField_, const C2FieldSupportedValues &values_) 1664 : paramOrField(paramOrField_), 1665 values(std::make_unique<C2FieldSupportedValues>(values_)) { } 1666 1667 /** 1668 * Construct from fields. 1669 */ 1670 C2ParamFieldValues(const C2ParamField ¶mOrField_, std::unique_ptr<C2FieldSupportedValues> &&values_) 1671 : paramOrField(paramOrField_), 1672 values(std::move(values_)) { } 1673 }; 1674 1675 /// @} 1676 1677 // include debug header for C2Params.h if C2Debug.h was already included 1678 #ifdef C2UTILS_DEBUG_H_ 1679 #include <util/C2Debug-param.h> 1680 #endif 1681 1682 #endif // C2PARAM_H_ 1683