Guide to the meta refactoring

Contents
What’s all this about then? ............................................................................................................................................... 2
Overview of the changes .................................................................................................................................................. 3
Top Level CMakeLists.txt .............................................................................................................................................. 3
AddressSpace ................................................................................................................................................................ 3
Configuration ................................................................................................................................................................ 3
Device............................................................................................................................................................................ 3
FrameworkInternals ...................................................................................................................................................... 4
Server ............................................................................................................................................................................ 4
Meta .............................................................................................................................................................................. 4
What’s all this about then?
This doc serves as a guide to PR 283 – to merge new meta into master.

It’s a big change; meta has been in quasar since the early paleolithic period, and, like our ancestors from that time it
did what it does using a fairly primitive set of stone tools. Meta 2.0 aims to be a more sleek affair; where possible
using the greatness of quasar tools to achieve its ends.

What am I talking about? Basically old meta was ‘written’ by generating all the address space and device class code it
needed using a (fairly ancient) snapshot of quasar, then stashing all that in the Meta src/include folders. At runtime,
Meta then ran some custom code to fill and inject instances of those classes into the AS and memory. It worked, but
then bashing things with stones works, eventually. The problem was that quasar evolved, meta did not.

Figure 1: cave drawings from the old meta period

Figure 2: new meta, there's just much less of it - that's the beauty of it
Overview of the changes
So, the aim of new meta is to deliver the same functionality old meta did, but, riding on quasar transforms etc –
thereby bestowing all evolutions in quasar directly upon meta. How? By making meta part of the design. Not a
‘normal’ part of the design though; previously the design was all the work of the user – new meta provides a static
design excerpt. The ultimate quasar server design is a merge: user design + meta design.

Top Level CMakeLists.txt

set(DESIGN_FILE ${PROJECT_BINARY_DIR}/Design/DesignWithMeta.xml)

See merge_design_and_meta.py for file that handles merging logic.

AddressSpace
Also simple – removal of old meta hardcoded/hacked AS AS_TYPEs. These days quasar generates these per build, like
any other class.

Configuration
Only sub-dir templates worth mentioning here… changes would have been super simple apart from the fact that new
meta strives for backwards compatibility with logging configs (and no good deed goes unpunished).

Old meta – configurations looked like this. Note From Meta/meta-design.xml logging configurations
ComponentLogLevel is not a singleton, but has no name naturally fall out of the generation step requiring the
attribute to distinguish one instance from another. format below.
<StandardMetaData> <StandardMetaData>
<Log> <Log>
<GeneralLogLevel logLevel="INF"/> <LogLevel name="GeneralLogLevel" logLevel="INF"/>
<ComponentLogLevels> <ComponentLogLevels>
<ComponentLogLevel componentName="X" logLevel="INF"/> <LogLevel name="X" logLevel="INF"/>
<ComponentLogLevel componentName="Y" logLevel="INF"/> <LogLevel name="Y" logLevel="WRN"/>
<ComponentLogLevel componentName="Z" logLevel="INF"/> <LogLevel name="Z" logLevel="WRN"/>
</ComponentLogLevels> </ComponentLogLevels>
</Log> </Log>
</StandardMetaData> </StandardMetaData>
So, backwards compatibility then requires a bit of finagling in the config schema generation transform. These are
marked with _META_BACKWARDS_COMPATIBILITY_HACK_ (for easy identification when time comes to rescind
backwards compatibility support). At runtime meta converts old schema to new schema using
Meta/<src/include>/metaBackwardsCompatibilityUtils.<h/cpp>.

Ultimately this allows server configurations using the logging configs in the old meta style to be loaded into new
meta. Super!

Device
Change here is that previously low level Device BASE and Device USER cmake requirements were generated together
in a single transform; for new meta this is split – cmake requirements for Device BASE is one transform, Device USER
is another transform.

Why? More detail to follow in FrameworkInternals (but basically because meta uses quasar to generate DLogLevel
BASE but meta provides its own custom DLogLevel USER).
FrameworkInternals
Probably the most contentious part of the new meta change, so let’s get right to it – time for transformDesign.py!
The guiding notion here is that nearly all quasar transforms should operate on the user + meta design. Some,
though, only make sense for the USER part of the design. Specifically

1. Class Diagram – should be concerned only with what the user brings to the design, not cluttered with stuff
common to every quasar server. Didn’t want to obscure the user design signal with meta noise
2. Generation of USER layer of device class code (as opposed to BASE layer of same) – as mentioned in section
Device, meta provides its own DLogLevel.h/cpp to handle writing address space changes to LogIt (to modify
logging thresholds via address space).
a. New meta is, however, more than happy for quasar to generate all the BASE device stuff for the
elements in its design – any quasar improvements in BASE generation will thus be applied to meta
design.
3. CMake listings for generated device classes are hence split
a. since quasar generates BASE device code for all elements in the merged user + meta design all these
need to be part of the cmake build.
b. Since quasar generates USER device code for elements in the user design only, then quasar
automatically handles cmake requirements for those it generated (and new meta adds the bits it’s
directly responsible for to cmake, namely DLogLevel.cpp)

To deliver the requirements above I added Boolean column (DESIGN_WITH_META) to the transform table. True
means use merged user + meta design, False means user design only.

merge_design_and_meta.py
The python logic that merges user and meta design: definitely worth a sharp look at that one: mistakes I made in
there will propagate through quasar like woodworm in a swiss chalet.

Server
Not much: just meta invocation stuff. One question… do you think that’s the right place for Meta::initializeMeta()? I
could also call it from inside the configure() function, called after the AS objects are built and connected up with
their associated Device objects.

I think where it is sort of looks right, but if inside the configure function then new meta is more hidden from end
users, which might be a good thing.

Meta
Well, tons of changes here, unsurprisingly, mostly deletion, happily..

Quick tour of meta.h/cpp

Meta:: configureMeta builds the required complete meta configuration if user config provides none, or is only
partially provided. Handles the backwards compatibility of old logging configs too.

Meta::initializeMeta where possible meta design elements are just AS only (no device logic), BuildInformation for
example. This function just finds the corresponding meta AS elements and provides the value.