======DBG-interface======
<label>chap:dbg-interface</label>

=====Command-syntax=====
====list_modules====
<texit>\index{DBG!list_modules}</texit>
returns a list of all available modules

**Arguments**
none

**Returns**
a module_id,name list of all modules available, where module_id is to be
used for reference, while name reflects the spc-name of the module. The
returned list is sorted on module_id.
====list_tag_modules====
<texit>\index{DBG!list_tag_modules}</texit>
returns a list of all available modules and tags all modules as 'seen'. See
also //list_new_modules//.

**Arguments**
none

**Returns**
a module_id,name list of all modules available, where module_id is to be
used for reference, while name reflects the spc-name of the module. The
returned list is sorted on module_id.
====list_new_modules====
<texit>\index{DBG!list_new_modules}</texit>
only returns modules that are not tagged as 'seen'. Useful only in conjunction
with //list_tag_modules//. All returned modules are tagged as 'seen', too.

**Arguments**
none

**Returns**
a module_id,name list of all modules available, where module_id is to be
used for reference, while name reflects the spc-name of the module. The
returned list is sorted on module_id.
====show_all====
<texit>\index{DBG!show_all}</texit>
gives the whole description of a module

**Arguments**
the id of the module

**Returns**
<ldl>
<ldt>input</ldt><ldd>number of inputs, followed by a type,len - list for every input</ldd>
<ldt>output</ldt><ldd>number of outputs, followed by a conn_id,conn_index,type,len list for every output, where conn_id and conn_index point to the module and port connected. If this port is not connected, conn_id and conn_index are both -1.</ldd>
<ldt>config</ldt><ldd>number of configs, followed by a name,type,value - list for every configuration-item.</ldd>
<ldt>stats</ldt><ldd>number of stats, followed by a name,type,value - list for every configuration-item.</ldd>
</ldl>

====show_*====
<texit>\index{DBG!show_input}</texit>
<texit>\index{DBG!show_output}</texit>
<texit>\index{DBG!show_config}</texit>
<texit>\index{DBG!show_stats}</texit>
Returns only part of the description. "*" can be one of {input, output,
config, stats} and will return the corresponding information.

**Arguments**
the id of the module

**Returns**
Like //show_all//, but only the asked argument
====get_output====
<texit>\index{DBG!get_output}</texit>
returns a given output of a given module

**Arguments**
module_id,port_nbr

**Returns**
size,type,values where values are decimal, comma-seperated values. For complex
numbers, each value is a (real,imag)-pair.
====get_block====
<texit>\index{DBG!get_block}</texit>
Returns the values of a block. Contrary to "show_stats" and "show_config",
"get_block" returns the values in their binary form.

**Arguments**
module_id, stats_index

**Returns**
The block of data in binary representation.
====get_image====
<texit>\index{DBG!get_image}</texit>
Returns an image that is stored in a stats. Read //Returns// for a
description of the values returned.

**Arguments**
module_id, stats_index

**Returns**
The image in binary representation. The size of the returned block is of
<latex>width \cdot height \cdot \lceil\frac{bpp + 7}{8}\rceil</latex>. That means that a 20 x 20
black/white image (<latex>bpp=1</latex>) will return 400 bytes.
====set_config====
<texit>\index{DBG!set_config}</texit>
Sends a new config-value

**Arguments**
module_id, config_index, value
value is in human-readable form.

**Returns**
"Reconfigured" on success
====new_list====
<texit>\index{DBG!new_list}</texit>
A list is used when one wants to track a certain value in the software-radio,
or a value-pair. The software-radio tries its best to make sure that all
value-pairs are correlated, but it may happen that an older value gets paired
with a new value.

**Arguments**
<latex>module\_id_1</latex>, <latex>stats\_index_1</latex>, <latex>module\_id_2</latex>, <latex>stats\_index_2</latex>
If <latex>module\_id_2</latex> is <latex>-1</latex> then only a single value will be tracked and the
values returned by //read_list// will contain a {value,time} pair.

**Returns**
The id of the list, in ascii

====read_list====
<texit>\index{DBG!read_list}</texit>
Returns the so far collected value-pairs. The cache is of length 1024, that
means that you should collect the data before 1024 are stored. In the most
busiest scenario, this means once every second.

**Arguments**
list_id

**Returns**
The first line contains the total number of value-pairs that will be sent.
Then follow either (<latex>value_1</latex>, <latex>value_2</latex>) or (value, time) pairs, each one
followed by a "\n".

====close_list====
<texit>\index{DBG!close_list}</texit>
Finishes tracking of the values from this list.

**Arguments**
list_id

**Returns**
OK or error on error.
====process_data====
<texit>\index{DBG!process_data}</texit>
Tells a module to immediatly start processing. If the module has inputs, all
connected inputs will be activated before processing.

**Arguments**
module_id

**Returns**
OK on success

====get_profiling====
<texit>\index{DBG!get_profiling}</texit>
Returns all profiling-data from a module. The software-radio keeps track of the
number of calls and the total execution-time of the following parameters:
user-messages, data-processing and total time.

**Arguments**
module_id

**Returns**
Three lines of profiling with the time spent and the number of calls seperated
by a space. The numbers are 64-bit integers. The time spent is returned in
<latex>\mu</latex>s.

====ping====
<texit>\index{DBG!ping}</texit>
To test whether the software-radio is still running and replying to requests.

**Arguments**
none

**Returns**
"pong"