8月 292014
 

有时候我们希望在构建时能够在命令行添加一些宏定义,改变程序行为。一个典型应用示例是代码里通过检查是否定义了 DEBUG 宏,来决定是否输出调试信息。编译器一般提供命令行选项支持这种做法,例如使用 gcc 时可以在命令行添加 -D 选项,定义一些宏:

gcc -DDEBUG=1 a.c

不过,大型项目一般都需要自动化构建工具,如 GNU Autotools 或者 CMake。使用它们后,我们无法直接修改编译命令,但它们提供了替代方案。对于 Autotools,它可以识别 CPPFLAGS 等环境变量,从而我们可以在命令行上添加宏定义,例如:

CPPFLAGS="-DDEBUG=1" ./configure

此外,我们还可以先 export CPPFLAGS="-DDEBUG=1",再用 ./configure 命令。注意这里 CPPFLAGS 的 CPP 指的是 C 预处理器 (C Preprocessor),不是 C++,其中只应该设置 -I-D-U 等影响预处理器的选项。Autotools 支持 CFLAGSCXXFLAGSLDFLAGS 环境变量,分别用来指定 C 编译链接时、C++ 编译链接时、以及仅在链接时有效的选项。

目前许多项目已经使用 CMake 来构建。CMake 支持 CFLAGSCXXFLAGSLDFLAGS 等,但遗憾的是唯独不支持 CPPFLAGS。也就是说,CMake 会无视 CPPFLAGS 环境变量的值。Aron Xu 为此报了一个 BUG,不过因为没人志愿去做,所以一直没有修复。许多人可能会以为,可以用类似 cmake .. -DVAR=VALUE 的方式来添加宏定义,但这是无效的。这样一来,如果想在命令行上指定宏定义,只能复用 CFLAGS 或者 CXXFLAGS 变量。这基本可以工作,因为一般情况下预处理和编译是同一个命令进行的。

CMake 中标准的添加宏定义方法是使用 ADD_DEFINITIONS(-DMACRO)(参考文档),不过这需要修改 CMakeLists.txt 文件。如果想要在命令行上定制宏的开关或取值,那么可以像这里一样,定义一个 CMake 选项:

OPTION(DEFINE_MACRO "Option description" ON) # Enabled by default

然后做一个条件判断:

IF(DEFINE_MACRO)
    ADD_DEFINITIONS(-DMACRO)
ENDIF(DEFINE_MACRO)

之后,就可以用 cmake -DDEFINE_MACRO=OFF .. 调整宏的开关或取值了。

最后值得一提的是,如果代码里已经有了宏定义语句,那么通过命令行修改其取值是不可能的。编译器会警告宏被重复定义,而且生效的是源文件中的定义。想要重新定义,只能随后 #undef#define。这将不得不通过修改代码来实现。

8月 282014
 

本文介绍 C++ 中传统枚举类型存在的作用域不受限等问题,随后列举经典的限定其作用域的做法,最后给出新标准 C++11 下的解决方案。

传统行为

传统的枚举类型在 C 语言中就有,C++ 中行为和 C 中一致,常被用来定义有类型的常量。一个典型的枚举类型定义如下:

enum Color { RED, BLUE };

C++ 发明人 Bjarne Stroustrup 总结这种枚举有如下问题

  • 作用域不受限 (unscoped),枚举变量的作用域不受限,会暴露给领近的代码作用域(如果在最外层则为全局作用域),容易引起命名冲突。例如如下代码是无法编译通过的:

    enum Color { RED, BLUE };
    enum Feeling { EXCITED, BLUE };
  • 会隐式转换为 int。这是 C 中的默认行为,但是和“有类型的常量”的初衷是不符合的。比如上面例子中 EXCITED == RED 会返回真(gcc 编译会有警告),这其实是不合常理的。

  • 用来表征枚举变量的实际类型不能明确指定,从而无法支持枚举类型的前向声明。

经典做法

解决作用域不受限带来的命名冲突问题的一个简单方法是,给枚举变量命名时加前缀,如上面例子改成 COLOR_BLUE 以及 FEELING_BLUE。一般说来,为了一致性我们会把所有常量统一加上前缀。但是这样定义枚举变量的代码就显得累赘。C 程序中可能不得不这样做。不过 C++ 程序员恐怕都不喜欢这种方法。替代方案是命名空间:

namespace Color { enum Type { RED, YELLOW, BLUE }; };

这样之后就可以用 Color::Type c = Color::RED; 来定义新的枚举变量了。如果 using namespace Color 后,前缀还可以省去,使得代码简化。不过,因为命名空间是可以随后被扩充内容的,所以它提供的作用域封闭性不高。在大项目中,还是有可能不同人给不同的东西起同样的枚举类型名。

更“有效”的办法是用一个类或结构体来限定其作用域,例如:

struct Color { enum Type { RED, YELLOW, BLUE }; };

定义新变量的方法和上面命名空间的相同。不过这样就不用担心类在别处被修改内容。这里用结构体而非类,一是因为本身希望这些常量可以公开访问,二是因为它只包含数据没有成员函数。

C++11 的枚举类

上面的做法解决了第一个问题,但对于后两个仍无能为力。庆幸的是,C++11 标准中引入了“枚举类”(enum class),可以较好地解决上述问题。它使用如下语法定义:

enum class Color { RED, BLACK };

可见语法更为简单了。如此一来,定义新变量也得到简化:

Color c = Color::RED;

类限制了其作用域,避免了命名冲突。同时也避免了隐式类型转换。也就是说,枚举类即是作用域受限的 (scoped),又是强类型的 (strongly typed) 枚举。至于第三个问题,C++11 标准允许指定存储类型:

enum class Color : char { RED, BLUE };

上面例子使用 char 来存储这个枚举类。缺省情况下使用 int。这样枚举就可以进行前向声明了:

enum class Color : char ;   // forward declaration
void foo (Color *p);
// ...
enum class Color : char { RED, BLUE }; // definition

有了前向声明,代码可以更好地组织到不同的文件里,增加程序可读性和可维护性。

更多参考

除了文中链接外,还有如下链接可供参考:

8月 272014
 

使用 bladeRF 板卡时我们会遇到两个“镜像”:固件 (firmware) 镜像与 FPGA 镜像。二者是两个不同的概念。但是业界叫法不一,有时候会把二者混为一谈。一般而言,固件指的是嵌入到硬件设备中的软件,存放在只读存储器 (ROM) 或者闪存 (flash) 中,一般不易修改,修改的操作称为“刷新”(flashing)。固件这个名词最初和微代码相关,不过 bladeRF 里源代码是嵌入式 C 程序。FPGA 全名为可编程门阵列,其门电路、寄存器连接可以编程重构,其源程序一般是硬件描述语言 (HDL),通过综合 (synthesis) 等步骤得到二进制文件。在 bladeRF 板卡上,FPGA 只是一块 Altera 芯片。在没有内置非挥发存储时,FPGA 镜像需要每次上电时重新加载,bladeRF 就是这种情况。所以在拿到板卡时,上面已有固件,但还没有 FPGA 镜像。下面本文会具体说明在使用 bladeRF 时如何刷新固件、加载/更新 FPGA 镜像、以及如何自动加载 FPGA 镜像。注意,有时为了避免混淆,会称 FPGA 镜像为 FPGA 比特流 (bitstream),或者 FPGA 配置(因为它就是配置了门电路等组件的连接)。

刷新固件

注意:刷新固件前请先取消 FPGA 自动加载,以避免可能的冲突。FPGA 自动加载的细节参见下文。

Nuand 官方提供固件的源码,我们可以自行编译,不过这需要一套嵌入式开发工具链。Nuand 也提供构建好的固件镜像,可以直接下载使用。要刷新固件,只需在命令行执行:

bladeRF-cli -f bladeRF_fw_vX.Y.Z.img -v verbose

其中 X.Y.Z 为具体的版本号。命令完成后,需要断电重启了 bladeRF。然后可以用 bladeRF-cli 工具检查:

$ bladeRF-cli -e version

  bladeRF-cli version:        0.11.1-git-c631100
  libbladeRF version:         0.16.2-git-c631100

  Firmware version:           1.7.1-git-ca697ee
  FPGA version:               Unknown (FPGA not loaded)

看下其中 Firmware version(固件版本)是否更新。

事实上,还有另外一种刷新固件的方法,是通过进入设备的启动加载 (Bootloader) 模式(类似 Android 的 Recovery),输入一些命令完成的。不过这种方式步骤繁琐,一般不推荐使用,建议在上述简单方法遇到错误时考虑采用。具体步骤参加维基

加载 FPGA 镜像

注意到上面的示例中,FPGA version(FPGA 版本)显示为 Unknown(未知),FPGA 未加载。目前 bladeRF 使用两种 FPGA。要加载正确的 FPGA 镜像,首先需要确定手头 bladeRF 板卡的 FPGA 尺寸。它可以根据当初购买的价格判断,但更靠谱的方法是使用命令行查看:

$ bladeRF-cli -i
bladeRF> info

  Serial #:                 4f977f01eec48f5068c2ee3aeba41ba9
  VCTCXO DAC calibration:   0x8b63
  FPGA size:                40 KLE
  FPGA loaded:              yes
  USB bus:                  4
  USB address:              5
  USB speed:                SuperSpeed
  Backend:                  libusb
  Instance:                 0

交互模式下用 info 命令,或者直接在命令行下 bladeRF-cli -e info,在输出中寻找 FPGA size,就可以看到 FPGA 尺寸信息。这里示例显示板卡使用 40 KLE FPGA。事实上,FPGA 尺寸还可以通过查看 FPGA 芯片上的 EP4CExxxF23C8N 字样中 xxx 的部分来获得。

Nuand 官方提供了预先构建的 FPGA 镜像,免除用户手工编译之苦。40 KLE FPGA 对应 hostedx40.rbf 文件,以此类推。要加载 FPGA 镜像,只需使用命令 bladeRF-cli -l /path/to/fpga/file,或者交互模式下 load fpga /path/to/fpga/file,其中 /path/to/fpga/file 为 FPGA 镜像所在路径。FPGA 镜像成功加载后,板卡上的三个 LED 灯会亮起,交互模式下 version 命令可以看到 FPGA 版本不再是未知。

不过,正如前文所说,每次重新加电后,FPGA 镜像都需要重新加载。下面说下如何自动加载 FPGA 镜像。

自动加载 FPGA 镜像

bladeRF 维基上提供了两种自动加载 FPGA 镜像的方法。第一种方法基于主机软件,libbladeRF 在打开设备时,会在如下目录自动搜索合适的 FPGA 镜像:

  • $HOME/.config/Nuand/bladeRF/
  • $HOME/.Nuand/bladeRF/
  • /etc/Nuand/bladeRF/
  • /usr/share/Nuand/bladeRF/

只需将下载的 FPGA 镜像文件放在上述目录之一(没有可以新建之),即可实现 FPGA 镜像的自动加载。

另一种方式是将 FPGA 镜像写入设备的 SPI 闪存。这种方式的好处是写入后就不再依赖主机,从而可以实现脱机运行。不过这种方式比较慢,加载 x40 镜像需要大约 4 秒钟。注意绝对不要在加载完成,三个 LED 灯亮起前试图使用设备。要使用这种方式,需要执行下面命令:

bladeRF-cli -L /path/to/fpga/file

一般说来,如果没有脱机工作的需求,还是推荐第一种自动加载方法。

前面提到,刷新固件时最好取消自动加载。对于第一种方法,只需把 FPGA 镜像文件临时移走。第二种方法,则需要执行命令 bladeRF-cli -L X,以擦除写入的 FPGA 镜像。

致谢

本工作由星天科技赞助。

8月 102014
 

bladeRF 维基上介绍了在 Linux 系统上搭建 bladeRF 环境的步骤,不过原文是英文的,另外其中一些具体选择不尽合理。本文以 Fedora 系统为示例,提供一个中文版的 bladeRF 环境搭建指南,并着重介绍和维基上的不同点。比较可能有一定的时效性,但一些原则应该足够通用。本文的比较基准是当前的维基版本

安装依赖

维基上建议安装 “Development Tools” “Development Libraries” 两个软件包组,但我们只需要其中的一部分软件包,其中有些可能已经安装过了,而像 cvs 等并不必须。如果你像我一样有“洁癖”,不希望安装不需要的软件包,那么可以用如下的命令安装必须的依赖(未严格验证,在我这里绝大多数包都在之前安装过了):

sudo yum install git doxygen gettext glibc-devel ncurses-devel readline-devel zlib-devel boost-devel
sudo yum install libusbx libusbx-devel cmake wget gcc-c++

注意其中是 libusbx 而非 libusb,后者是 0.x 系列的版本,而非 1.x 系列。Debian/Ubuntu 系的用户会注意到软件包命名上的差异 (devel 而非 dev)。

维基上推荐安装 libtecla,以增强 bladeRF-cli 交互模式的编辑功能。不过 Fedora 软件源里目前还没有这个包,所以需要手动下载,解压缩,使用经典的 ./configure; make; sudo make install 三部曲安装。

构建 bladeRF

在终端下进入打算用来放置 bladeRF 源码的目录,用 git 将 bladeRF 的源码库克隆下来:

cd /path/to/bladeRF/directory
git clone https://github.com/Nuand/bladeRF.git

切换到源码目录中的 host 目录,创建一个 build 目录用来存放构建过程的中间文件。这种使用单独的构建目录的方式称为树外构建 (out of tree build),相对于直接在源码目录构建,好处在于生成的中间文件不会分散在源码目录里,方便清理,另外可以用多个构建目录构建出互不干扰的不同参数下的版本。之后切换到构建目录,然后就是标准的 cmake ..; make; sudo make install 三部曲了。注意这里 cmake 时启用了 INSTALL_UDEV_RULES 宏,使得安装时把 udev 规则文件也安装到系统中。

cd bladeRF/host/
mkdir build
cd build
cmake -DINSTALL_UDEV_RULES=ON ../
make
sudo make install

很遗憾的是这里安装的 udev 规则文件使用了 plugdev 群组,不是 Fedora 下的标准做法。可以参考之前的博文修改 udev 规则文件。

为了让新安装的 bladeRF 库文件可以被二进制文件使用,我们需要用 ldconfig 刷新系统动态库的缓存。上面的构建过程会将 bladeRF 安装到 /usr/local 下,而其中的库文件目录 /usr/local/lib{,64} 不在 ldconfig 的默认搜索路径里。所以我们可以将它们添加到 /etc/ld.so.conf 里。添加之后文件内容如下:

/usr/local/lib
/usr/local/lib64
include ld.so.conf.d/*.conf

之后,用 sudo ldconfig 刷新缓存即可。可以用 ldd /usr/local/bin/bladeRF-cli 命令检查 bladeRF 库文件是否被找到。连上 bladeRF 设备,用 bladeRF-cli -p 命令看下是否能够发现设备。更多操作见于另一个维基页

构建 GNU Radio 与 gr-osmosdr

通过上述步骤,就可以操作 bladeRF 板卡了。但是,要想便捷地为 bladeRF 开发软件无线电应用,最好再构建一下 GNU Radio 和 gr-osmosdr。GNU Radio 是一个开源的软件无线电开发平台,提供众多的信号处理模块和简单易用的图形界面开发环境。gr-osmosdr 适配 GNU Radio,为众多硬件板卡(除了 bladeRF 之外还有 HackRF 等)提供一个统一的软件接口。

GNU Radio 依赖比较多,编译安装相对麻烦,一般推荐使用 build-gnuradio 脚本。但是因为其中涉及到从网络下载诸多软件以及编译安装,效率受网速和电脑硬件性能限制,耗时较长。另外,脚本的健壮性不高,所以很容易中途退出。这个脚本很长,但实际上是把整个构建过程划分为几个步骤,放在几个函数里先后执行的。我建议阅读这个 Shell 脚本,每次运行其中的一步或几步,必要时手动完成一些配置。对于新手,这会是一个很好的通过阅读代码学习 Shell 编程的机会。

具体的构建步骤可以在维基或这里找到,这里就不再赘述。只是提几点注意事项:

  • 如果你像我一样,除了 bladeRF 之外,还会使用 Ettus 公司的 USRP 系列设备,那么记得先构建 UHD,然后构建 GNU Radio。
  • build-gnuradio 脚本在 cmake 时,有时用了树外构建,但有时又没用。建议始终用树外构建。
  • 编译 GNU Radio 时,并行 make (make -j N 其中 N 大于 1)时有时会编译失败(竞态条件?),直接 make 就可以正常编译通过,虽然速度会慢很多。什么?make 也会出错?那考虑换一个 git 提交重新编译,并向上游报 BUG 吧。

构建成功 GNU Radio 后,构建 gr-osmosdr 就显得小菜一碟了,标准的 cmake 构建三部曲,项目不大,编译过程也能很快完成。

全部构建完成后,可以使用如下命令用 bladeRF 看一下频谱,检验是否大功告成。其中 FPGA 映像可以从 Nuand 网站下载。此外,最新固件也可以从官网下载。

osmocom_fft -a bladerf=0,fpga=<your FPGA image> -s 2000000 -f 446000000

致谢

本工作由星天科技赞助。

2月 032012
 

我的 connect6-ng 是在 connect6 的基础上进行的。原项目使用 SVN 做版本控制,但我更喜欢使用 Git。所以我在开始 connect6-ng 时先检出了 SVN 仓库里的最新版本然后取出其中源代码初始化了 Git 仓库,并没有继续 SVN 历史。

董渊老师建议我能把两段历史连接起来,以体现出项目的延续性。老师还帮忙使用 git-svn 在 Ubuntu 9.10 下将 connect6 项目的 SVN 历史转换到了 Git 仓库下:

mkdir connect6.git
cd connect6.git/
git-svn init http://connect6.googlecode.com/svn/ --no-metadata
git config svn.authorsfile ../authors.txt
git-svn fetch
git log
cd ..
tar -zcvf connect6.git.tgz connect6.git/

其中authors.txt的内容为:

qq280833822 = CHEN Shuang <qq280833822@gmail.com>
wanglei     = WANG Lei    <leopardguo25@gmail.com>

我收到 connect6.git.tgz 后在连接两段历史前,对前一段历史记录做了一些更改:使用 git filter-branch 删除了仓库里的 *.class 文件、/trunk/connect6.jar 文件,因为我觉得这些中间文件或目标文件放在仓库里意义不大。另外,我又将 trunk 目录做成了仓库的根目录,这和后面我的仓库更接近。处理后的仓库目录我命名为 connect6-shrinked/

参考 stackoverflow 中这个问题回答,我使用其中的第三种方法(refs/replace/) 将 SVN 仓库历史转换成的 git 历史添加在了 connect6-ng 提交历史的前面,连上了两段历史。不太详细的步骤如下:

切换到新项目 connect6-ng 的顶层目录,把 connect6-shrinked 加为一个远程仓库,命名为 history:

$ git remote add history file:///path/to/connect6-shrinked/

然后找出 connect6-ng 项目最初的提交(Initial commit)的 SHA1 值,保存到 $TAIL 变量中:

$ TAIL=$(git rev-list --topo-order master | tail -n 1)

接着找出要导入历史的旧项目的最近的一次提交,保存到 $TOP 变量中:

$ TOP=$(git rev-parse --verify history^0)

然后读取 $TAIL 这个 commit 对象的内容:

$ git cat-file commit $TAIL > TAIL_COMMIT

手工编辑 TAIL_COMMIT 这个文件,加入一行 parent $TOP(其中 $TOP 换成对应的 SHA-1 值),这使得新项目的初始提交有了旧项目的顶部作为父提交。将新的 TAIL_COMMIT 写入仓库:

$ NEW_TAIL=$(git hash-object -t commit -w TAIL_COMMIT)

最后使用 git replace

$ git replace $TAIL $NEW_TAIL

这样就连接好了两段历史记录,可以用 git log 等查看。

要把合并后的历史 push 出去,需要在自己仓库 .git/config 文件中对应 remote 部分加一行:

push = +refs/replace/*:refs/replace/*

在合并两段历史之前已经从 connect6-ng 远程仓库 clone 了代码仓库的同学,如果不做修改,还是只能看到较新的一段历史。要想看到旧的SVN导出的历史,需要修改自己的 .git/config 里 origin 部分(或者其他指向 connect6-ng 远程仓库的 remote 分支名)添加一行:

fetch = +refs/replace/*:refs/replace/*

这样之后 git fetchgit pull 就可以拉取 refs/replace/ 下的后来添加的历史了。

附注:本文参考了董渊老师和我的邮件、stackoverflow 上的回答等,一并感谢。