GnuRadio Companion OOT XML Schema Documentation

问题

GnuRadio companion uses XML files to describe the API for out-of-tree (OOT) module blocks. Where is the documentation that describes that XML schema?

回答1:

There is a partial description here: https://wiki.gnuradio.org/index.php/GNURadioCompanion#Creating_the_XML_Block_Definition

• The name tags dictate the label text for the block, parameters, and ports.

• The key tags are unique identifiers, they may not contain spaces. The block key must be globally unique among all blocks in GRC. The parameter keys must be unique only within the block.

• The category tag is a unix-style path that represents the location of the block inside the block selection window. The path can be a new category (Custom), or represent a sub-category (Filters/Custom). To put a block into the root category, just use a single slash (/) for the root path.

• The import tag (there can be multiple) must be a valid python import statement to the module containing your block.

• The make tag contains the code necessary to construct your block. This code is essentially a cheetah template nested inside an xml tag. Upon code generation, the template performs a text substitution on the "$" parameters. For more advanced capabilities, see the cheetah template documentation.

• The callback tag registers a set-method from your custom block. Once the set-method is registered, the set-method can be called at runtime when a variable is changed. There can be any number of callback tags, one for each set-method of your block. Or no callback tags if this is not applicable.

• For the param tags, the commonly used values for the type tags are: complex, real, int, complex_vector, real_vector, int_vector, string, and raw. The raw type allows any value to be used without performing type checking. The real type should be used for single and double precision floating point numbers. The int type should be used for longs, ints, shorts, and chars.

• The hide tag controls how the parameter is displayed in GRC. It's either none, part (show in the prop dialog, not in the block on the canvas) or all.

• The sink tag represents an input port, and the source tag represents an output port. The allowed values for the type tags are: complex, float, int, short, and byte. For ports with a vector length, specify a vlen tag after the type tag.

In lieu of a better alternative, there is a Document type definition describing the XML for blocks: https://github.com/gnuradio/gnuradio/blob/master/grc/core/block.dtd. The relavant part is shown below:

<!--
    Top level element.
    A block contains a name, ...parameters list, and list of IO ports.
 -->
<!ELEMENT block (name, key, category?, throttle?, flags?, import*, var_make?, var_value?,
        make, callback*, param_tab_order?, param*, bus_sink?, bus_source?, check*,
        sink*, source*, bus_structure_sink?, bus_structure_source?, doc?,  grc_source?)>
<!--
    Sub level elements.
 -->
<!ELEMENT param_tab_order (tab+)>
<!ELEMENT param (base_key?, name, key, value?, type?, hide?, option*, tab?)>
<!ELEMENT option (name, key, opt*)>
<!ELEMENT sink (name, type, vlen?, domain?, nports?, optional?, hide?)>
<!ELEMENT source (name, type, vlen?, domain?, nports?, optional?, hide?)>
<!--
    Bottom level elements.
    Character data only.
 -->

Wikipedia describes the qualifiers used in the Document type definition:

A quantifier is a single character that immediately follows the specified item it applies to, to restrict the number of successive occurrences of these items at the specified position in the content of the element; it may be either:

• + for specifying that there must be one or more occurrences of the item — the effective content of each occurrence may be different;

• * for specifying that any number (zero or more) of occurrences is allowed — the item is optional and the effective content of each occurrence may be different

• ? for specifying that there must not be more than one occurrence — the item is optional;

The <check> tag can be used for validation. E.g. if you had a parameter with key "title" and another parameter with key "num", you could use the following top level tags for validation.

<check>$title != ""</check>
<check>$num &gt; -1</check>
<check>$num &lt; 5</check>

来源：https://stackoverflow.com/questions/46534857/gnuradio-companion-oot-xml-schema-documentation