3、自定义模块开发入门：OOT模块创建流程、Python与C++模块的基本结构

GNU Radio 的强大之处不仅在于其内置的丰富信号处理模块，更在于它允许开发者通过 OOT（Out-of-Tree，树外模块）机制创建自定义模块，以应对特定场景下的特殊需求。无论是接入私有硬件、实现新型算法，还是优化现有处理链路，OOT 模块都是将想法落地为可复用组件的标准途径。本章将深入剖析 OOT 模块的创建流程，并对比 Python 与 C++ 两种模块实现方式的基本结构，为后续章节中排查模块崩溃与日志定位打下坚实的代码基础。

上图清晰地展示了 OOT 模块从创建到构建的完整路径。整个过程可以概括为三个核心阶段：使用 gr_modtool 创建模块骨架、选择模块实现语言（Python 或 C++）、以及通过 CMake 完成编译与安装。理解这一流程是后续所有调试工作的前提，因为许多崩溃问题往往源于模块结构不完整或绑定错误。

3.1 OOT 模块创建流程：从零到可加载模块

OOT 模块的创建并非手工编写所有文件，而是依赖 GNU Radio 提供的 gr_modtool 命令行工具。该工具能够自动生成标准化的目录结构、构建脚本和基础代码，极大降低了开发者的入门门槛。整个流程通常包含以下四个步骤：

1. 创建模块骨架：使用 gr_modtool newmod 命令生成模块的顶层目录和基础配置文件。例如，gr_modtool newmod mymodule 会创建一个名为 gr-mymodule 的目录，其中包含 CMakeLists.txt、lib/、python/、grc/ 等标准子目录。
2. 添加信号处理块：使用 gr_modtool add 命令在模块内新增一个具体的信号处理块。该命令会交互式询问块的名称、语言类型（Python/C++）、是否包含 GRC 绑定等，并自动生成对应的源文件、头文件和 GRC YAML 模板。
3. 编写核心逻辑：开发者需要在生成的 work() 函数中实现具体的信号处理算法。这是模块的核心部分，也是后续崩溃和性能问题的高发区。
4. 构建与安装：在模块根目录下执行 cmake 和 make 命令完成编译，然后通过 sudo make install 将模块安装到系统 GNU Radio 环境中。安装后，需要执行 sudo ldconfig 更新动态链接库缓存。

3.2 Python 模块基本结构：快速原型与灵活调试

Python 模块因其开发效率高、无需编译、易于调试等特点，非常适合算法验证和教学场景。一个典型的 Python OOT 块由三个关键文件组成，它们共同协作，使模块能够被 GNU Radio 运行时识别和调用。

以 gr_modtool add 生成的 my_block 为例，其核心文件结构如下：

• __init__.py：位于 python/ 目录下，负责将模块中的类导出到 Python 命名空间。GNU Radio 通过该文件中的 from .my_block import my_block 语句来加载具体的块实现。
• my_block.py：这是块的实现文件，其中定义了 my_block 类。该类继承自 gr.sync_block（同步块）或 gr.decim_block（抽取块）等基类，并必须重写 work() 方法。
• my_block.block.yml：位于 grc/ 目录下，是 GRC（GNU Radio Companion）的图形化绑定文件。它定义了模块在流程图中的显示名称、参数类型、输入输出端口数量及数据类型。

下面是一个典型的 Python work() 函数实现，该函数实现了简单的信号幅度放大功能：

import numpy as np
from gnuradio import gr

class my_block(gr.sync_block):
    def __init__(self, gain=1.0):
        gr.sync_block.__init__(self,
            name="my_block",
            in_sig=[np.complex64],
            out_sig=[np.complex64])
        self.gain = gain

    def work(self, input_items, output_items):
        in0 = input_items[0]
        out0 = output_items[0]
        # 核心处理逻辑：幅度放大
        out0[:] = in0 * self.gain
        return len(output_items[0])

这段代码展示了 Python 模块的几个关键特征：work() 方法直接接收 NumPy 数组作为输入输出；通过切片赋值 out0[:] = ... 实现数据写入；返回值表示实际处理的样本数。这种简洁性使得 Python 模块非常适合快速验证算法正确性。

3.3 C++ 模块基本结构：高性能与底层控制

对于追求极致性能或需要直接操作硬件的场景，C++ 是首选。C++ 模块的结构相对复杂，涉及头文件、实现文件和 Python 绑定三个层面，但性能优势显著。一个标准的 C++ OOT 块通常包含以下文件：

• my_block.h：头文件，声明 my_block 类。该类继承自 gr::sync_block，并声明构造函数、析构函数以及 work() 函数。头文件中还会定义 ::sptr（智能指针）类型别名，用于 GNU Radio 的内存管理。
• my_block_impl.cc：实现文件，包含 my_block_impl 类的具体实现。该类继承自 my_block，并实现 work() 函数。GNU Radio 采用 PIMPL（Pointer to IMPLementation）模式，将公共接口与具体实现分离，以隐藏内部细节并减少编译依赖。
• my_block_python.cc：pybind11 绑定文件，负责将 C++ 类暴露给 Python。通过 pybind11 宏，将 C++ 的构造函数和公共方法注册为 Python 可调用的形式。

以下是一个 C++ work() 函数的简化示例，实现了与上述 Python 版本相同的放大功能：

#include <gnuradio/io_signature.h>
#include "my_block_impl.h"

namespace gr {
  namespace mymodule {

    my_block::sptr
    my_block::make(float gain)
    {
      return gnuradio::make_block_sptr<my_block_impl>(gain);
    }

    my_block_impl::my_block_impl(float gain)
      : gr::sync_block("my_block",
              gr::io_signature::make(1, 1, sizeof(gr_complex)),
              gr::io_signature::make(1, 1, sizeof(gr_complex))),
        d_gain(gain)
    {}

    int
    my_block_impl::work(int noutput_items,
                        gr_vector_const_void_star &input_items,
                        gr_vector_void_star &output_items)
    {
      const gr_complex *in = (const gr_complex *)input_items[0];
      gr_complex *out = (gr_complex *)output_items[0];

      for (int i = 0; i < noutput_items; i++) {
        out[i] = in[i] * d_gain;
      }
      return noutput_items;
    }
  } // namespace mymodule
} // namespace gr

这段代码揭示了 C++ 模块的几个重要特点：work() 函数直接操作原始指针，避免了 Python 的数组拷贝开销；通过 gr::io_signature::make 定义输入输出端口；使用 d_gain 成员变量存储参数。这种底层控制能力使得 C++ 模块在性能敏感型应用中具有不可替代的地位。

3.4 实战场景：Python 与 C++ 模块的选择与对比

为了帮助开发者更直观地理解两种语言模块的差异，下表从多个维度进行了对比。在实际项目中，应根据具体需求做出合理选择。

以一个具体的信号解调项目为例：假设我们需要实现一个 QPSK 解调器。在项目初期，算法尚未定型，参数需要频繁调整，此时选择 Python 模块可以快速验证解调算法的正确性。开发者可以轻松地在 work() 函数中添加打印语句，观察星座图数据。然而，当算法稳定后，需要处理 100 MHz 以上的实时数据流时，Python 版本将无法满足实时性要求。此时，应将核心解调逻辑迁移到 C++ 模块，并利用 SIMD 指令或多线程技术进行优化。迁移过程中，需要特别注意数据类型的匹配（gr_complex 对应 Python 的 np.complex64）以及缓冲区大小的处理。