Re: [Discuss-gnuradio] Submitting OOT Module Questions

[Tom Rondeau]

On Wed, Sep 23, 2015 at 1:39 PM, Richard Bell <address@hidden> wrote:

Hey everyone,

I'm in the process of submitting my first OOT module for merge with GNU Radio base. It's a log gain AGC which converges much faster then the current AGCs when the input signal energy is low. I've read through the following link:
https://gnuradio.org/redmine/projects/gnuradio/wiki/Development#Contributing-to-GNU-Radio-FAQ

1) My first question relates to documentation. Up to now, I've added documentation into my XML files as <doc></doc> tags. To use Doxygen, am I correct to put them in the public *.h file? Is this the only place it should go, or should I add it to the XML as well? I've never been able to get my documentation to propagate through to the GRC block without putting it into the XML, is this a sign of a problem?

Hi Rich,

First, awesome! (And thanks for looking at that wiki page.)

Yes, Doxygen will pull only from the public .h file. That's what goes into the manual. This information should also be scraped to produce the doc tab in the GRC block's parameters dialog. I forget exactly when this happens, but it's possible you might need to run cmake again. Or there's potentially a problem with handling this in OOT modules. I'd work on getting this into gr-analog in your own branch and see if it works ok there. It should, and this would reduce you having to duplicate the docs -- which will mostly be a problem if we ever want to change/update them.

 

2) If I understand the above link correctly, I should fork GNU Radio, create a new branch which I might call Log_AGC, add my code to that branch and then make a pull request. Am I misunderstanding anything?

Yep, that's it!

 

3) As far as code style goes, should I avoid using

#define DEBUG
#ifdef DEBUG
std::cout << "Debug stuff" << "\n";
#endif

statements to hide debug code? That is what I currently do but I know it's not prevalent in the source.

Indeed, avoid that. We have the logging facilities to help with that:

http://gnuradio.org/doc/doxygen/page_logger.html

For pure debug stuff, use the d_debug_logger that all blocks have. Something like:

GR_LOG_DEBUG(d_debug_logger, "Debug stuff");

 

4) I currently have an Optimize option in the GRC block which picks between the way you would write the block if you just used standard C++ statements (not optimized) and if you use Volk (optimized). Using control ports to compare the two, there is an improvement with volk. But I like that someone looking into the block can see how not to do it and then how to do it. Good for beginners jumping into GNU Radio.

Thanks,

Rich

There is a trade-off here between readability and speed. Volk kernels are fairly straight-forward, usually, in what they do, too, so I don't see this as a huge barrier to readability.

Still, I like your thinking on this. What I'd recommend is to remove the "Optimize" option and only have the volk-enabled version in the code. But take the non-volk code as a comment to describe how the code operates on that level.

Tom