= Radio Meta Data Interface = The !RadioMetaData interface is an extension to StandardInterfaces to encorporate information describing data with each packet. Further documentation can be found here: [http://ossie.wireless.vt.edu/documentation/system/standardInterfaces-metadata/] == Meta Data Tags == Here is a brief description of the meta data tags used to describe data passed between components. This list is subject to change. || '''Name''' || '''Description''' || '''Type/Range''' || || {{{mod_scheme}}} || Scheme used to modulate the data || {{{UNKNOWN, PSK, DPSK, PAM, FSK, QAM}}} || || {{{M}}} || Number of symbols in {{{mod_scheme}}} constellation || {{{unsigned long int}}} || || {{{sampling_frequency}}} || Frequency (Hz) at which the data are sampled || {{{float}}} || || {{{carrier_frequency}}} || Frequency (Hz) for which the signal is modulated || {{{float}}} || || {{{signal_bandwidth}}} || Bandwidth (Hz) of the signal || {{{float}}} || || {{{signal_strength}}} || Nominal strength of signal (dB) || {{{float}}} || || {{{eom}}} || End-of-message flag || {{{boolean}}} || == Backwards Compatibility == Because the meta data interface is overridden in the port implementation, components not utilizing the meta data for each packet do not need to be edited when installing the [source:/ossie-sdrf2007/system/standardInterfaces-metadata standardInterfaces-metadata] package. All that is needed after installation is simple re-compile. In other words, components are not ''binary'' compatible but are ''source'' compatible. In other words, there are now two {{{pushPacket()}}} methods for the {{{complexShort}}} uses port interface: {{{ #!cpp class complexShort_u { public: // ... void pushPacket( const PortTypes::ShortSequence &I, const PortTypes::ShortSequence &Q); void pushPacket( const PortTypes::ShortSequence &I, const PortTypes::ShortSequence &Q, const standardInterfaces::MetaData &packet_data); // ... }; }}} and two {{{getData()}}} methods for the provides port: {{{ #!cpp class complexShort_p { public: // ... void getData( PortTypes::ShortSequence* &I, PortTypes::ShortSequence* &Q); void getData( PortTypes::ShortSequence* &I, PortTypes::ShortSequence* &Q, standardInterfaces::MetaData* &packet_data); // ... }; }}} == Latency Results == Including meta data with each packet increases the amount of overhead used in mashalling data objects as they are passed from one component to another. As described in the section above, no modifications to the component code are required, however the many parties have expressed concern that the additional data not utilized by the port could slow the component down. Several tests were run to compare the amount of latency between components for different data types. Numerous papers discuss the topic of latency through CORBA, so we won't get into hairy details here. The results for profiling latency vs. packet size can be seen below. Results were averaged over 100,000 trials. Trends were consistent across different platforms. [[Image(http://computing.ece.vt.edu/~jgaeddert/img/ossie/metadata_latency, title="latency results for CORBA call with different metadata objects", alt="metadata latency")]] - '''baseline:''' No function call. Loop timing overhead. - '''empty call:''' Interface with no arguments - '''data:''' Data packet of type {{{CORBA::ShortSequence}}} - '''data w/ basic metadata:''' Data packet as described above but with additional metadata struct - '''data w/ extended metadata:''' Data packet as described above but with extended metadata struct including 10-element array of key/value pairs and XML string The exact interfaces used for analysis can be found in a [source:/customInterfaces/branches/custom-testable-interface branch] of custom interfaces. These results suggest that adding basic metadata with each packet adds negligible overhead in terms of latency. Keep in mind that extracting the metadata object tags was not incorporated into the test (e.g. the amount of time it would take to parse an XML object). Questions and concerns should be directed to JosephGaeddert == Profiling Results == The following results were taken with [http://oprofile.sourceforge.net/news/ oprofile]. Basically, they show that while percentage-wise the {{{PushPacketWithBasicMetaData}}} and {{{PushPacketWithExtendedMetaData}}} interfaces are roughly 2-3 times slower than the regular {{{PushPacket}}} interface, the entire delay is heavily dependent upon the marshalling overhead of omniORB. {{{ # oprofile session:POINT --threshold=4 }}} {{{ CPU: P4 / Xeon with 2 hyper-threads, speed 3391.86 MHz (estimated) Counted GLOBAL_POWER_EVENTS events (time during which processor is not stopped) with a unit mask of 0x01 (mandatory) count 100000 GLOBAL_POWER_E...| samples| %| ------------------ 113976 51.4330 POINT_sink GLOBAL_POWER_E...| samples| %| ------------------ 48674 42.7055 libomniORB4.so.0.7 23593 20.7000 libc-2.4.so 17358 15.2295 libpthread-2.4.so 14604 12.8132 libcustomInterfaces.so.0.0.6 3480 3.0533 libomnithread.so.3.2 2207 1.9364 libstdc++.so.6.0.8 1837 1.6117 anon (tgid:27654 range:0xf82000-0xf83000) 1513 1.3275 ld-2.4.so 698 0.6124 POINT_sink 11 0.0097 libomniDynamic4.so.0.7 1 8.8e-04 libossieidl.so.0.0.4 71417 32.2277 POINT_source GLOBAL_POWER_E...| samples| %| ------------------ 43019 60.2364 libomniORB4.so.0.7 12386 17.3432 libc-2.4.so 7547 10.5675 libpthread-2.4.so 4716 6.6035 libcustomInterfaces.so.0.0.6 1556 2.1788 ld-2.4.so 1436 2.0107 anon (tgid:27653 range:0x538000-0x539000) 736 1.0306 POINT_source 10 0.0140 libomniDynamic4.so.0.7 5 0.0070 libstdc++.so.6.0.8 2 0.0028 libomnithread.so.3.2 1 0.0014 libossiecf.so.0.0.4 1 0.0014 libossieidl.so.0.0.4 1 0.0014 libossieparser.so.0.0.4 1 0.0014 libxerces-c.so.27.0 ... }}} If we take a closer look at customInterfaces... {{{ # opreport session:POINT -l /usr/local/lib/libcustomInterfaces.so.0.0.6 }}} {{{ CPU: P4 / Xeon with 2 hyper-threads, speed 3391.86 MHz (estimated) Counted GLOBAL_POWER_EVENTS events (time during which processor is not stopped) with a unit mask of 0x01 (mandatory) count 100000 samples % image name app name symbol name 2648 13.7060 libcustomInterfaces.so.0.0.6 POINT_sink customInterfaces::_impl_POINT::_dispatch(omniCallHandle&) 2534 13.1159 libcustomInterfaces.so.0.0.6 POINT_sink POINT::providesPort::PushDataWithExtendedMetaData(...) 2031 10.5124 libcustomInterfaces.so.0.0.6 POINT_sink POINT::providesPort::PushDataWithBasicMetaData(...) 1219 6.3095 libcustomInterfaces.so.0.0.6 POINT_sink customInterfaces_i::POINT_p::Pull(...) 1185 6.1335 libcustomInterfaces.so.0.0.6 POINT_sink POINT::providesPort::PushData(...) ... 341 1.7650 libcustomInterfaces.so.0.0.6 POINT_source customInterfaces_i::POINT_u::EmptyCall() ... }}} == Software Status == Currently the meta data interface is implemented as a stand-alone interface, and included in the [source:/ossie-sdrf2007/system/standardInterfaces-metadata/complexShort.idl complex short] and [source:/ossie-sdrf2007/system/standardInterfaces-metadata/realChar.idl real char] {{{pushPacket()}}} interfaces.