做嵌入式这些年跨平台移植的活儿我接过不少但像这次“龙芯K平台 ST驱动迁移”的组合还是有点特别。项目代号叫“走马观碑”听起来挺文雅实际干起来就是一堆寄存器、中断号和时序对齐的问题。简单说就是要把原本跑在ST意法半导体平台上的外设驱动在龙芯处理器环境下重新落地保证外设能正常工作上层应用不用大改。这篇文章就复盘一下我们组的整个移植过程包括思路拆解、实际操作和踩过的坑。当初接这个任务的时候团队内部对“ST驱动移植”的理解并不统一。有人以为是简单地把STM32的HAL库拿过来重新编译有人以为只要把寄存器地址改一改就行。等真正开始梳理代码才发现问题远没有这么简单。ST驱动和龙芯平台之间不只是CPU指令集不同整个硬件架构、中断路由、时钟树、外设寄存器布局几乎全变了。“移植”的本质根本不是代码搬运而是把驱动里的“逻辑层”和“硬件层”拆开然后针对目标平台重新设计一套硬件适配层。这才是所有工作的核心。1. 项目背景与需求拆解1.1 “走马观碑”这个项目到底要做什么先交代一下背景。我们手里有一套成熟的工业控制板卡原方案用的是ST主控外设包括串口、GPIO、SPI Flash、I2C传感器和一块LCD显示屏。整套驱动代码在老平台上跑了几年稳定性和实时性都验证过。现在因为供应链和国产化替代的需求要把主控换成龙芯平台操作系统也切到了麒麟系统。硬件板卡重新画但外设型号不变这就给软件留了一个很大的空间——底层外设驱动必须重写但上层业务逻辑应该完全复用。“走马观碑”这个代号其实是组里起的意思是希望我们在极短时间内快速浏览、理解原有的ST驱动代码同时又要在新平台上重建一整套驱动体系像“走马观碑”一样既要速度又要记得住细节。这个项目的核心目标有四个把原有ST平台的所有外设驱动功能完整迁移到龙芯平台功能不能缺失。对外提供的API接口尽量保持一致让上层应用感知不到底层硬件换了。保证关键外设的时序和中断响应能力不能出现因为驱动移植导致的性能劣化。整个过程要有可复现的文档和适配层设计方便后续继续扩展新外设。如果你也在做类似的芯片替代、平台迁移会发现这四个目标基本是通用的。尤其是第二点保持API兼容看起来简单实际最容易翻车。因为ST的HAL库、标准外设库自带一套命名和初始化逻辑而龙芯平台通常用的是Linux内核驱动框架或者裸机寄存器操作两者对上层的接口风格完全不同怎么在中间做一个干净的转换层是考验设计功力的地方。1.2 ST驱动与龙芯平台的本质差异很多初次接触平台移植的人会陷入一个误区以为只要CPU支持相同的外设接口比如都有UART、I2C驱动代码就能直接复用。但实际上驱动代码是由“控制逻辑”和“寄存器操作”两大部分组成的。控制逻辑跟芯片无关比如处理数据缓冲、状态机切换、超时重试寄存器操作则完全依赖具体芯片包括寄存器地址、位域定义、写入顺序、时钟使能方式。以GPIO为例STM32的GPIO配置是通过BSRR、CRL、CRH等寄存器完成的需要先开启GPIO所在的总线时钟再配置端口模式、输出类型、速度、上下拉。而龙芯平台的GPIO控制器完全不是这套逻辑它往往挂在某个SoC内部的总线桥上寄存器基地址、位宽、中断使能方式都不同。哪怕同样是“把某个引脚拉高”对应到寄存器操作上也是完全不同的代码。除了寄存器差异另一个巨大差异是中断系统。STM32使用NVIC中断号是固定的每个外设对应一个中断向量而龙芯平台的中断控制器层级更复杂有内核中断、IP中断、外部中断的区别外设中断往往需要通过中断控制器级联映射。这就导致驱动的中断处理函数注册方式、中断号的获取方式完全不一样。再往下还有时钟系统。STM32的时钟树有AHB、APB1、APB2总线每个外设的时钟频率可以通过RCC寄存器分频配置龙芯平台的时钟管理通常由PMPower Management或时钟控制器统一管理外设时钟的使能、分频、频率来源都不同。如果移植时没有理清时钟关系很容易出现串口波特率算不对、I2C时序不稳定之类的问题。1.3 为什么不能简单换个编译链直接编译我先总结一下结论直接编译肯定不行哪怕侥幸过了编译器那关跑起来也会出各种诡异问题。原因有三条。第一寄存器定义完全不同。ST的CMSIS头文件里定义了GPIOA、USART1等外设的基地址这些地址在龙芯的地址空间里根本不存在编译不可能通过。就算强行手动替换地址外设寄存器的位域划分、读写特性、保护位也和龙芯不同等于拿北京的驾照在上海开车规则虽然都是靠右行驶但路口的标线和信号灯完全不一样。第二中断处理机制不兼容。ST驱动中大量使用HAL_Delay、HAL_UART_Receive_IT这类依赖于SysTick和NVIC的接口龙芯平台没有这些硬件单元直接编译出来的代码根本无法响应中断。即便用软件模拟也很难保证实时性。第三操作系统抽象层不匹配。原ST驱动可能是跑裸机或者RTOS如FreeRTOS的而现在要跑在麒麟系统上。这是一个虚拟内存、进程调度、内核态和用户态完全不同的环境。裸机驱动可以直接用指针访问物理地址Linux用户态驱动则可能需要通过mmap映射物理内存或者写成内核驱动通过file_operations接口与用户态交互。这个差异比寄存器差异更伤筋动骨。所以我们“走马观碑”组的整体策略是不复用ST驱动的代码而是复用ST驱动的“逻辑”——也就是每个外设的功能流程、参数配置经验、异常处理思路然后在龙芯平台上重新实现一套适配层。2. 移植前的准备梳理依赖与搭建环境2.1 先画清代码依赖图再动手正式移植之前先花了一周时间做代码梳理。原始的ST驱动工程里有几百个源文件很多是中间层和应用层代码真正需要移植的外设驱动程序只有那么十几个文件。这时候如果眉毛胡子一把抓把整个工程拖过来改那就是给自己挖坑。我的做法是给每个驱动文件画一张依赖关系表重点标出三类状态纯逻辑型完全不涉及硬件寄存器只做数据解析、协议处理。比如Modbus协议栈、CRC校验、环形缓冲区。这类文件应该原封不动保留。半硬件型主体是逻辑但中间调用了HAL库函数或者寄存器操作。比如LCD驱动的底层写像素函数、传感器的I2C读写函数。这类文件需要抽象出硬件接口再针对新平台实现。纯硬件型整个文件都是寄存器操作和中断处理。比如UART底层、GPIO初始化、I2C控制器驱动。这类文件是重写的重点。梳理完之后把文件分成三类目录common/原样保留、hal/需要重写硬件接口、platform/完全新写。这样做的好处是后续编译时能明确知道哪些代码要重点测试哪些代码基本可以信任。表格化整理之后整个工程的脉络就清晰了原驱动模块依赖情况移植策略环形缓冲区无硬件依赖原样保留CRC/校验算法无硬件依赖原样保留Modbus从站协议调用串口收发接口保留逻辑替换串口底层LCD画点/画线调用SPI/I2C底层保留逻辑替换总线底层GPIO控制直接操作寄存器完全重写UART驱动直接操作寄存器中断完全重写I2C驱动直接操作寄存器中断完全重写定时器延时直接操作寄存器完全重写这个表看起来简单但实际操作起来非常管用。到了后面调试阶段每次出问题我都能快速定位是哪个模块的问题不用再从整个工程里漫无目的地查。2.2 龙芯平台的环境认知在动笔写代码之前得先把龙芯平台本身摸清楚。我们用的这块板子是龙芯2K系列处理器内核指令集和ST的ARM Cortex-M系列完全不同外设控制器也各不相同。这里说的“龙芯K”在当前上下文里可以理解为我们项目中对龙芯2K系列平台的内部代号“K”既有2K的含义也有Kernel内核的意思表示这是一套从板级到内核适配的完整方案。龙芯平台的系统环境和ST裸机环境完全是两个世界。我们这次跑的是麒麟系统基于Linux内核。这意味着驱动的存在形态有两种选择一种是把驱动编进内核走标准Linux驱动框架另一种是写成用户态程序通过mmap直接映射物理地址操作寄存器。两种方式都有应用场景前者适合正式交付、性能要求高的场合后者适合快速验证、调试阶段。原来的ST平台上驱动跑在裸机上没有MMU没有虚拟地址所有指针都是物理地址直接访问。到了麒麟系统上用户态程序默认访问的是虚拟地址必须通过mmap把物理地址映射到用户空间后才能操作寄存器。这个映射关系如果搞错轻则读取的数据不对重则直接段错误崩掉。另外同事还提到过一个问题麒麟系统上默认启用了针对mips架构的SSH等网络服务这部分和驱动移植没有直接关系但在调试过程中很有用。我们通过SSH在开发机和目标板之间传输代码、远程执行交叉编译效率比反复插拔SD卡高很多。如果你的开发环境也是这种“目标板跑Linux开发机交叉编译”的模式建议优先把网络调试通道打通。2.3 工具链与编译环境的搭建驱动移植的编译环境搭建比想象中更花时间。ST平台之前用的是arm-none-eabi-gcc加Makefile或者直接用IDE。龙芯平台上则要分两种场景处理内核模块方式使用龙芯官方提供的交叉编译工具链比如loongarch64-linux-gnu-gcc编译出的.ko文件在目标板上insmod加载。用户态方式可以直接在目标板上用自带的gcc编译或者用交叉编译链编译后拷贝到板上运行。我们组里实际的做法是两种都用。调试阶段用用户态方式因为迭代快改完代码直接编译运行出问题也好用gdb调试确认稳定之后再改写成内核模块做正式集成。交叉编译的时候有几个容易踩坑的地方。第一头文件路径要指向目标平台的内核源码目录不能指向开发机的Linux头文件目录第二Makefile里的obj-m和KERNELDIR变量要配置正确否则编出来的模块一加载就报版本不匹配第三用户的程序中如果引用了内核头文件可能会因为用户态和内核态的头文件冲突导致编译失败这时候需要单独用-I指定路径隔离。说实话搭建编译环境这一步是整个项目中技术含量最低但痛苦指数最高的环节。很多时间都耗在版本不匹配、路径不对、权限问题上。我的建议是一定要写好一个标准的构建脚本把交叉编译链、内核源码目录、输出路径都固化下来最好再写一个简单的Dockerfile保证组内任何人拿到环境都能一键编译。3. 核心移植实操从GPIO到串口再到中断3.1 GPIO模块移植——先弄懂“内外部上拉”的差异GPIO是所有外设驱动里最基础也最容易轻视的模块。ST的GPIO有很丰富的配置输入输出模式、推挽/开漏、上拉/下拉、复用功能选择、速度等级每个引脚都可以独立配置。龙芯的GPIO控制器没那么复杂但有它自己的特点尤其要注意寄存器的读写方式。我们在移植GPIO驱动时第一步是看一下龙芯SoC的寄存器手册找到GPIO控制器的基地址。以我们用的龙芯2K系列为例GPIO的寄存器通常包括方向寄存器、数据寄存器和控制寄存器。操作逻辑其实不难把方向寄存器对应的位置1设为输出、清0设为输入读写数据寄存器控制引脚电平。但这里有一个容易出问题的细节上下拉电阻的配置方式。ST芯片里上下拉是GPIO内部的配置寄存器里写明即可龙芯平台有的引脚默认内部上拉有的默认没有上拉而且上拉的可配置性不如ST灵活。我们在点亮一块LCD屏幕的时候发现背光控制和复位引脚的电平不太对排查了半天最后发现是复位引脚的内部下拉导致按键电平不稳定。解决的办法是在板级电路上加上外部上拉电阻或者先在初始化代码中把该引脚配置成带内部上拉的输入模式。GPIO移植的经验我总结了两条不要依赖寄存器的复位默认值每个用到的引脚必须显式初始化。如果外设对引脚电平有严格要求比如LCD复位时序、SD卡检测引脚最好在初始化完成后读取一次寄存器确认实际配置生效再做后续操作。3.2 UART串口驱动的移植串口是调试的“生命线”串口驱动移植顺利与否直接影响整个项目的节奏。ST的UART驱动通常需要初始化GPIO复用为串口功能、配置波特率、数据位、停止位、校验位然后使能接收中断或DMA。龙芯平台的串口控制器不太一样早期的龙芯SoC往往集成的是兼容16650的UART寄存器布局和PC上的传统串口类似操作更简单。移植的时候重点要关注三个地方时钟源频率、波特率分频计算和中断使能。以16650兼容串口为例波特率分频值的计算公式是divisor (uart_clock_freq) / (16 * baud_rate)比如UART输入时钟频率是1.8432MHz波特率设为9600那么divisor 1.8432MHz / (16 * 9600) 12。这些计算看起来简单但要命的是不同平台串口的时钟频率来源并不一样有的固定来自系统时钟分频有的可以通过寄存器选择时钟源。算错时钟频率波特率就是错的打印出来的日志全是乱码。我们当时遇到一个很诡异的问题串口在uboot阶段输出正常进入Linux内核后乱码。排查下来发现是uboot里配置的串口时钟源和Linux设备树里配置的串口时钟源不一致导致Linux下的串口驱动计算分频系数时基准频率错误。这个问题的根源不是代码写错而是时钟配置不一致。建议在做串口移植的时候先写一个最简单的回环测试程序把TX和RX短接然后发送一串数据看能否原样收回。这个测试通过了再继续做中断接收和DMA否则后面出了问题很难分清是硬件问题还是驱动问题。3.3 中断控制器与ISR的适配外设驱动里最考验功底的就是中断处理。原来的ST驱动里串口接收中断、定时器中断、外部IO中断各自注册了处理函数中断优先级通过NVIC配置。移植到龙芯平台后中断机制变化很大。龙芯平台的中断系统通常有多个层级处理器核上的中断线IP2、IP3等分别对应不同的中断控制器。外设的中断先汇聚到中断控制器再由中断控制器向CPU核上报。这个过程中会有一个“中断号映射”的概念外设中断号不等于CPU中断线中间需要查一张映射表或者通过设备树来解析。在Linux内核框架下中断处理相对简单注册一个request_irq传一个中断号内核会处理底层的映射和回调。但在我们的实际场景中有一部分驱动跑在用户态裸机环境下没有内核帮你管理中断就需要自己写中断处理入口并且要处理“中断上下文”的问题比如保存现场、禁止嵌套中断、清除中断标志位。这里有一个很重要的坑中断标志位必须及时清除但清除时机不对又可能丢失中断。有些外设的中断状态寄存器是写1清除write-1-to-clear的有些是读清除的有些则是写0清除的。如果沿用ST驱动的习惯性操作在龙芯的外设上可能就会误触发或漏触发中断。我们在调试一个外部IO中断时反复进入中断函数但读到的外部事件值却不对。后来用示波器抓电平发现是中断标志清除操作写错了导致中断一直挂着系统不停地响应。改成正确的清除方式后一切正常。这类问题建议在调试时不要急着看业务逻辑先写一个精简的中断测试函数只做一件事进入中断后翻转一个GPIO上位机用示波器观察GPIO翻转频率是否正常。频率正常说明中断本身没问题再去检查业务逻辑。3.4 I2C和SPI等总线型外设的移植I2C和SPI的移植思路与GPIO、UART类似但更麻烦一点因为总线型外设涉及的时序更多。ST的I2C外设内置了时序计算寄存器基于APB时钟自动计算SCL频率。龙芯平台的I2C控制器则通常需要手动配置时钟分频而且一次传输的字节数、起始停止条件控制方式都不尽相同。我们这次移植了I2C接口的温湿度传感器原驱动逻辑很简单初始化I2C、发送设备地址、写寄存器地址、读数据、解析。移植过程中发现的主要问题是时序不满足。ST的I2C因为时钟设置方便SCL频率可以做到400kHz乃至1MHz龙芯平台I2C寄存器配置不当的话实际SCL频率可能会偏差很大导致传感器不响应或者数据错误。用示波器看波形是最好的调试方式。如果没有示波器可以先用逻辑分析仪抓I2C波形确认起始条件、地址、数据位是否正常。我们当时抓完波形后发现ACK信号一直拉不低问题出在I2C外设配置的“输入滤波器持续时间”太长导致接收端采样不到从设备拉低的ACK。调整滤波器参数后恢复正常。SPI方面主要问题是时钟极性和相位的匹配。ST的SPI可以很方便地配置CPOL和CPHA龙芯平台有些SPI控制器的配置方式更隐晦。对应的方法就是仔细对照LCD或者Flash芯片的数据手册找到要求的时序模式再翻龙芯SoC手册找到对应的寄存器位。这一点没有捷径就是看手册反复验证。4. 操作系统适配让驱动在麒麟系统里跑起来4.1 Linux内核驱动还是用户态驱动怎么选当目标系统是麒麟Linux内核时驱动落地方式的选择直接影响后续的工作量。我们这次实际用到了两种方式简单对比一下对比项内核驱动用户态驱动性能高无上下文切换损耗稍低有系统调用开销调试便利性较难一个oops可能整机崩溃容易gdb直接调试开发速度慢编译内核模块耗时快迭代周期短安全稳定性高有内核保护机制低非法地址直接段错误与系统集成可热插拔、设备模型管理需要自己管理资源我的个人建议是前期快速验证用用户态驱动后期正式交付用内核驱动。用户态驱动通过mmap把外设物理地址映射到用户空间相当于在用户态直接操作寄存器。这种方式写起来快遇到段错误也能立即定位到具体的代码行非常适合驱赶开发节奏。等到功能全部调通再把关键外设改写成内核模块性能更好也符合Linux社区的开发惯例。4.2 设备树的关键作用在Linux内核环境下驱动与硬件的匹配主要靠设备树Device Tree。设备树描述了一个板子上有哪些外设、各自的寄存器基地址、中断号、时钟源等信息。内核在启动时解析设备树然后把相应资源传递给驱动。我们移植ST驱动时一个非常关键的步骤就是为新板卡写设备树节点。比如串口节点要指定compatible属性、reg属性寄存器基地址和长度、interrupts属性中断号和触发方式、clocks属性时钟源。这些信息在ST平台上往往写死在HAL库的配置结构体里而在龙芯Linux环境下则要写进设备树。设备树写错的一个典型问题是中断号配置错误。因为设备树里填的中断号是软件中断号需要经过中断控制器驱动翻译成实际硬件中断源。翻译规则在不同SoC上不一样只能靠芯片手册和官方的设备树文件来对照。我们当时串口中断一直不触发后来发现设备树里填的interrupt-cells个数不对导致中断号解析错误。改对后一切正常。如果你用的是用户态驱动方式就不需要设备树直接读芯片手册找到物理地址然后mmap映射即可。这种方式灵活但代码可复用性差换一块板卡就得改代码。长期来看还是设备树内核驱动的方式更适合维护。4.3 应用层兼容层让上层业务无感切换这次移植最让团队欣慰的是应用层几乎没有改动。原因是在驱动和上层业务之间加了一层“兼容接口层”——这一层对外提供了和原ST驱动几乎相同风格的API内部则根据平台编译宏调用不同架构的具体实现。拿一个简单的drv_spi_write_read函数举例在ST平台下它内部调用HAL_SPI_TransmitReceive在龙芯平台下它内部调用用户态mmap映射后封装的SPI读写函数。上层代码不需要知道这个函数的内部实现只要传入同样的参数拿到同样的返回值业务逻辑就可以原封不动地运行。这一层的设计原则是接口尽量简单、参数尽量少、返回值尽量规范。别想着把ST驱动的所有特性都暴露给上层那只会让接口越来越臃肿。比如我们针对LCD屏只暴露了初始化、写命令、写数据、设置坐标四个接口。上层画点画线、显示字符的代码完全不需要关心底层用的是SPI还是I2C也不需要关心寄存器怎么操作。这个兼容层还有一个额外的好处可以在编译时加入一层“模拟驱动”在没有真实硬件的开发机上用软件模拟外设行为方便上层逻辑的联调。这在ST和龙芯硬件同时缺货的时候特别有用。5. 调试实录踩过的坑和排查思路5.1 时钟配置与波特率异常我们最早遇到的一个奇怪问题是串口能打印数据但打印的内容是乱码。起初怀疑是代码里的波特率配置有问题用示波器去抓TX引脚的波形发现一个字符位的宽度完全不是期望的9600波特率所对应的脉宽。搜索了龙芯的时钟框架才发现UART模块的时钟源来自一个可以选择的MUX默认选择的是低频时钟跟设备树里设置的时钟频率不一致。这个坑的排查过程让我印象很深代码没问题、寄存器配置也对但就是实际频率和你预想的不一样。单纯靠读代码很难发现问题必须靠示波器实测信号再反推时钟链路。日志乱码的问题解决后又出现了“偶尔丢字符”的现象。排查后发现是接收FIFO的中断触发方式设置问题。16550兼容UART可以设置FIFO触发等级默认是1字节就触发中断但若中断处理函数里读数据太慢新到的数据就会溢出丢掉。把FIFO触发等级调高比如到8字节再触发就能有效降低溢出概率。5.2 中断号映射导致的中断不触发中断不触发是驱动移植里最闹心的问题。因为不报错、不死机就是功能不工作。我们在移植一个外部按键中断时代码逻辑已经在ST平台上验证过无数次了到龙芯平台上却始终不进入中断回调。排查步骤是这样的第一步检查GPIO是否配置成输入模式测试读取电平能够正确反映按键状态。这一步通过了说明GPIO基础配置没问题。第二步检查中断触发条件是用上升沿还是下降沿设备树里是否配置正确。第三步检查中断号。这里最容易出问题。设备树里写的中断号必须对应中断控制器驱动中注册的hwirq。有时候还要看interrupt-parent属性指向的是哪个控制器如果写错控制器节点中断号解析就会错位。最终我们发现问题果然出在设备树的中断号上。官方SDK里的参考设备树文件写的是另一个外设的中断我直接复制过来改了一下GPIO编号忘了改interrupt-parent。改对之后按键中断马上正常。5.3 DMA传输与缓存一致性问题如果用DMA做大数据传输比如从串口接收一大包数据或者向LCD显存写入数据就绕不开缓存一致性问题。在ST平台上Cortex-M内核和DMA之间的缓存一致性通常由硬件自动保证或者通过简单的__disable_irq就能暂时规避。但龙芯平台上如果要走DMA情况更复杂。Linux内核中处理DMA的常规做法是使用dma_alloc_coherent分配一致性的DMA缓冲区这种方式能保证CPU和设备看到的数据是一致的。如果用的是普通kmalloc内存需要在DMA传输前调用dma_map_single做地址映射传输完成后调用dma_unmap_single并选择合适的dma_sync方向刷新缓存。我们第一次做DMA接收时传输标志位看起来一切正常数据长度也对但读取的数据内容全是乱的。后来发现就是没有正确处理CPU缓存DMA把数据写到了内存但CPU读到的还是缓存里的旧值。这个问题如果你不做DMA可能一辈子碰不到但只要做DMA就得把整个cache维护流程刻在脑子里。5.4 调试效率提升的技巧整个项目做下来收获最大的其实不是代码而是调试方法。首先一定不要打“printf漫游”战术要在关键路径上设计好调试接口。比如每个外设驱动都暴露一个自检函数可以单独运行、单独验证。这样出问题时能快速缩小排查范围。其次善用示波器和逻辑分析仪。驱动移植本质上是在和电信号打交道很多逻辑上怎么看怎么对的问题用示波器一看波形就全明白了。再次把内核日志等级调整好。通过echo 8 /proc/sys/kernel/printk可以把内核调试信息全部打出来虽然信息量很大但关键时候能救命。最后保持一个“最小化复现”的思维。遇到问题先不要急着分析业务功能为什么不正常而是写一个最简单的测试程序单独测试对应模块把问题降到最底层再逐层向上定位。写在最后龙芯K平台的ST驱动移植技术上听起来很高大上实际做下来就是一件一件枯燥的比对、调试、验证工作。最难的从来不是某一段代码怎么写而是面对一个陌生的处理器平台如何把已有的逻辑和经验正确地“翻译”过去。这次项目能顺利推进很大程度上归功于一开始对驱动代码的依赖梳理和对ST与龙芯平台差异的充分认识。在这个过程里我个人最大的体会是移植驱动不要执着于“把代码搬过来”而要想清楚“这个驱动到底在做什么、依赖哪些硬件特性、新的平台如何提供这些特性”。想明白了这个剩下的写代码就是体力活。另外调试工具一定要配齐示波器、逻辑分析仪、串口调试线这些硬件的投入远比多写几年代码更能节省时间。希望这篇复盘能给你在类似平台适配的工作中带来一点参考少踩几个我们踩过的坑。
龙芯K平台ST驱动迁移实战：从寄存器到中断的嵌入式移植攻略
做嵌入式这些年跨平台移植的活儿我接过不少但像这次“龙芯K平台 ST驱动迁移”的组合还是有点特别。项目代号叫“走马观碑”听起来挺文雅实际干起来就是一堆寄存器、中断号和时序对齐的问题。简单说就是要把原本跑在ST意法半导体平台上的外设驱动在龙芯处理器环境下重新落地保证外设能正常工作上层应用不用大改。这篇文章就复盘一下我们组的整个移植过程包括思路拆解、实际操作和踩过的坑。当初接这个任务的时候团队内部对“ST驱动移植”的理解并不统一。有人以为是简单地把STM32的HAL库拿过来重新编译有人以为只要把寄存器地址改一改就行。等真正开始梳理代码才发现问题远没有这么简单。ST驱动和龙芯平台之间不只是CPU指令集不同整个硬件架构、中断路由、时钟树、外设寄存器布局几乎全变了。“移植”的本质根本不是代码搬运而是把驱动里的“逻辑层”和“硬件层”拆开然后针对目标平台重新设计一套硬件适配层。这才是所有工作的核心。1. 项目背景与需求拆解1.1 “走马观碑”这个项目到底要做什么先交代一下背景。我们手里有一套成熟的工业控制板卡原方案用的是ST主控外设包括串口、GPIO、SPI Flash、I2C传感器和一块LCD显示屏。整套驱动代码在老平台上跑了几年稳定性和实时性都验证过。现在因为供应链和国产化替代的需求要把主控换成龙芯平台操作系统也切到了麒麟系统。硬件板卡重新画但外设型号不变这就给软件留了一个很大的空间——底层外设驱动必须重写但上层业务逻辑应该完全复用。“走马观碑”这个代号其实是组里起的意思是希望我们在极短时间内快速浏览、理解原有的ST驱动代码同时又要在新平台上重建一整套驱动体系像“走马观碑”一样既要速度又要记得住细节。这个项目的核心目标有四个把原有ST平台的所有外设驱动功能完整迁移到龙芯平台功能不能缺失。对外提供的API接口尽量保持一致让上层应用感知不到底层硬件换了。保证关键外设的时序和中断响应能力不能出现因为驱动移植导致的性能劣化。整个过程要有可复现的文档和适配层设计方便后续继续扩展新外设。如果你也在做类似的芯片替代、平台迁移会发现这四个目标基本是通用的。尤其是第二点保持API兼容看起来简单实际最容易翻车。因为ST的HAL库、标准外设库自带一套命名和初始化逻辑而龙芯平台通常用的是Linux内核驱动框架或者裸机寄存器操作两者对上层的接口风格完全不同怎么在中间做一个干净的转换层是考验设计功力的地方。1.2 ST驱动与龙芯平台的本质差异很多初次接触平台移植的人会陷入一个误区以为只要CPU支持相同的外设接口比如都有UART、I2C驱动代码就能直接复用。但实际上驱动代码是由“控制逻辑”和“寄存器操作”两大部分组成的。控制逻辑跟芯片无关比如处理数据缓冲、状态机切换、超时重试寄存器操作则完全依赖具体芯片包括寄存器地址、位域定义、写入顺序、时钟使能方式。以GPIO为例STM32的GPIO配置是通过BSRR、CRL、CRH等寄存器完成的需要先开启GPIO所在的总线时钟再配置端口模式、输出类型、速度、上下拉。而龙芯平台的GPIO控制器完全不是这套逻辑它往往挂在某个SoC内部的总线桥上寄存器基地址、位宽、中断使能方式都不同。哪怕同样是“把某个引脚拉高”对应到寄存器操作上也是完全不同的代码。除了寄存器差异另一个巨大差异是中断系统。STM32使用NVIC中断号是固定的每个外设对应一个中断向量而龙芯平台的中断控制器层级更复杂有内核中断、IP中断、外部中断的区别外设中断往往需要通过中断控制器级联映射。这就导致驱动的中断处理函数注册方式、中断号的获取方式完全不一样。再往下还有时钟系统。STM32的时钟树有AHB、APB1、APB2总线每个外设的时钟频率可以通过RCC寄存器分频配置龙芯平台的时钟管理通常由PMPower Management或时钟控制器统一管理外设时钟的使能、分频、频率来源都不同。如果移植时没有理清时钟关系很容易出现串口波特率算不对、I2C时序不稳定之类的问题。1.3 为什么不能简单换个编译链直接编译我先总结一下结论直接编译肯定不行哪怕侥幸过了编译器那关跑起来也会出各种诡异问题。原因有三条。第一寄存器定义完全不同。ST的CMSIS头文件里定义了GPIOA、USART1等外设的基地址这些地址在龙芯的地址空间里根本不存在编译不可能通过。就算强行手动替换地址外设寄存器的位域划分、读写特性、保护位也和龙芯不同等于拿北京的驾照在上海开车规则虽然都是靠右行驶但路口的标线和信号灯完全不一样。第二中断处理机制不兼容。ST驱动中大量使用HAL_Delay、HAL_UART_Receive_IT这类依赖于SysTick和NVIC的接口龙芯平台没有这些硬件单元直接编译出来的代码根本无法响应中断。即便用软件模拟也很难保证实时性。第三操作系统抽象层不匹配。原ST驱动可能是跑裸机或者RTOS如FreeRTOS的而现在要跑在麒麟系统上。这是一个虚拟内存、进程调度、内核态和用户态完全不同的环境。裸机驱动可以直接用指针访问物理地址Linux用户态驱动则可能需要通过mmap映射物理内存或者写成内核驱动通过file_operations接口与用户态交互。这个差异比寄存器差异更伤筋动骨。所以我们“走马观碑”组的整体策略是不复用ST驱动的代码而是复用ST驱动的“逻辑”——也就是每个外设的功能流程、参数配置经验、异常处理思路然后在龙芯平台上重新实现一套适配层。2. 移植前的准备梳理依赖与搭建环境2.1 先画清代码依赖图再动手正式移植之前先花了一周时间做代码梳理。原始的ST驱动工程里有几百个源文件很多是中间层和应用层代码真正需要移植的外设驱动程序只有那么十几个文件。这时候如果眉毛胡子一把抓把整个工程拖过来改那就是给自己挖坑。我的做法是给每个驱动文件画一张依赖关系表重点标出三类状态纯逻辑型完全不涉及硬件寄存器只做数据解析、协议处理。比如Modbus协议栈、CRC校验、环形缓冲区。这类文件应该原封不动保留。半硬件型主体是逻辑但中间调用了HAL库函数或者寄存器操作。比如LCD驱动的底层写像素函数、传感器的I2C读写函数。这类文件需要抽象出硬件接口再针对新平台实现。纯硬件型整个文件都是寄存器操作和中断处理。比如UART底层、GPIO初始化、I2C控制器驱动。这类文件是重写的重点。梳理完之后把文件分成三类目录common/原样保留、hal/需要重写硬件接口、platform/完全新写。这样做的好处是后续编译时能明确知道哪些代码要重点测试哪些代码基本可以信任。表格化整理之后整个工程的脉络就清晰了原驱动模块依赖情况移植策略环形缓冲区无硬件依赖原样保留CRC/校验算法无硬件依赖原样保留Modbus从站协议调用串口收发接口保留逻辑替换串口底层LCD画点/画线调用SPI/I2C底层保留逻辑替换总线底层GPIO控制直接操作寄存器完全重写UART驱动直接操作寄存器中断完全重写I2C驱动直接操作寄存器中断完全重写定时器延时直接操作寄存器完全重写这个表看起来简单但实际操作起来非常管用。到了后面调试阶段每次出问题我都能快速定位是哪个模块的问题不用再从整个工程里漫无目的地查。2.2 龙芯平台的环境认知在动笔写代码之前得先把龙芯平台本身摸清楚。我们用的这块板子是龙芯2K系列处理器内核指令集和ST的ARM Cortex-M系列完全不同外设控制器也各不相同。这里说的“龙芯K”在当前上下文里可以理解为我们项目中对龙芯2K系列平台的内部代号“K”既有2K的含义也有Kernel内核的意思表示这是一套从板级到内核适配的完整方案。龙芯平台的系统环境和ST裸机环境完全是两个世界。我们这次跑的是麒麟系统基于Linux内核。这意味着驱动的存在形态有两种选择一种是把驱动编进内核走标准Linux驱动框架另一种是写成用户态程序通过mmap直接映射物理地址操作寄存器。两种方式都有应用场景前者适合正式交付、性能要求高的场合后者适合快速验证、调试阶段。原来的ST平台上驱动跑在裸机上没有MMU没有虚拟地址所有指针都是物理地址直接访问。到了麒麟系统上用户态程序默认访问的是虚拟地址必须通过mmap把物理地址映射到用户空间后才能操作寄存器。这个映射关系如果搞错轻则读取的数据不对重则直接段错误崩掉。另外同事还提到过一个问题麒麟系统上默认启用了针对mips架构的SSH等网络服务这部分和驱动移植没有直接关系但在调试过程中很有用。我们通过SSH在开发机和目标板之间传输代码、远程执行交叉编译效率比反复插拔SD卡高很多。如果你的开发环境也是这种“目标板跑Linux开发机交叉编译”的模式建议优先把网络调试通道打通。2.3 工具链与编译环境的搭建驱动移植的编译环境搭建比想象中更花时间。ST平台之前用的是arm-none-eabi-gcc加Makefile或者直接用IDE。龙芯平台上则要分两种场景处理内核模块方式使用龙芯官方提供的交叉编译工具链比如loongarch64-linux-gnu-gcc编译出的.ko文件在目标板上insmod加载。用户态方式可以直接在目标板上用自带的gcc编译或者用交叉编译链编译后拷贝到板上运行。我们组里实际的做法是两种都用。调试阶段用用户态方式因为迭代快改完代码直接编译运行出问题也好用gdb调试确认稳定之后再改写成内核模块做正式集成。交叉编译的时候有几个容易踩坑的地方。第一头文件路径要指向目标平台的内核源码目录不能指向开发机的Linux头文件目录第二Makefile里的obj-m和KERNELDIR变量要配置正确否则编出来的模块一加载就报版本不匹配第三用户的程序中如果引用了内核头文件可能会因为用户态和内核态的头文件冲突导致编译失败这时候需要单独用-I指定路径隔离。说实话搭建编译环境这一步是整个项目中技术含量最低但痛苦指数最高的环节。很多时间都耗在版本不匹配、路径不对、权限问题上。我的建议是一定要写好一个标准的构建脚本把交叉编译链、内核源码目录、输出路径都固化下来最好再写一个简单的Dockerfile保证组内任何人拿到环境都能一键编译。3. 核心移植实操从GPIO到串口再到中断3.1 GPIO模块移植——先弄懂“内外部上拉”的差异GPIO是所有外设驱动里最基础也最容易轻视的模块。ST的GPIO有很丰富的配置输入输出模式、推挽/开漏、上拉/下拉、复用功能选择、速度等级每个引脚都可以独立配置。龙芯的GPIO控制器没那么复杂但有它自己的特点尤其要注意寄存器的读写方式。我们在移植GPIO驱动时第一步是看一下龙芯SoC的寄存器手册找到GPIO控制器的基地址。以我们用的龙芯2K系列为例GPIO的寄存器通常包括方向寄存器、数据寄存器和控制寄存器。操作逻辑其实不难把方向寄存器对应的位置1设为输出、清0设为输入读写数据寄存器控制引脚电平。但这里有一个容易出问题的细节上下拉电阻的配置方式。ST芯片里上下拉是GPIO内部的配置寄存器里写明即可龙芯平台有的引脚默认内部上拉有的默认没有上拉而且上拉的可配置性不如ST灵活。我们在点亮一块LCD屏幕的时候发现背光控制和复位引脚的电平不太对排查了半天最后发现是复位引脚的内部下拉导致按键电平不稳定。解决的办法是在板级电路上加上外部上拉电阻或者先在初始化代码中把该引脚配置成带内部上拉的输入模式。GPIO移植的经验我总结了两条不要依赖寄存器的复位默认值每个用到的引脚必须显式初始化。如果外设对引脚电平有严格要求比如LCD复位时序、SD卡检测引脚最好在初始化完成后读取一次寄存器确认实际配置生效再做后续操作。3.2 UART串口驱动的移植串口是调试的“生命线”串口驱动移植顺利与否直接影响整个项目的节奏。ST的UART驱动通常需要初始化GPIO复用为串口功能、配置波特率、数据位、停止位、校验位然后使能接收中断或DMA。龙芯平台的串口控制器不太一样早期的龙芯SoC往往集成的是兼容16650的UART寄存器布局和PC上的传统串口类似操作更简单。移植的时候重点要关注三个地方时钟源频率、波特率分频计算和中断使能。以16650兼容串口为例波特率分频值的计算公式是divisor (uart_clock_freq) / (16 * baud_rate)比如UART输入时钟频率是1.8432MHz波特率设为9600那么divisor 1.8432MHz / (16 * 9600) 12。这些计算看起来简单但要命的是不同平台串口的时钟频率来源并不一样有的固定来自系统时钟分频有的可以通过寄存器选择时钟源。算错时钟频率波特率就是错的打印出来的日志全是乱码。我们当时遇到一个很诡异的问题串口在uboot阶段输出正常进入Linux内核后乱码。排查下来发现是uboot里配置的串口时钟源和Linux设备树里配置的串口时钟源不一致导致Linux下的串口驱动计算分频系数时基准频率错误。这个问题的根源不是代码写错而是时钟配置不一致。建议在做串口移植的时候先写一个最简单的回环测试程序把TX和RX短接然后发送一串数据看能否原样收回。这个测试通过了再继续做中断接收和DMA否则后面出了问题很难分清是硬件问题还是驱动问题。3.3 中断控制器与ISR的适配外设驱动里最考验功底的就是中断处理。原来的ST驱动里串口接收中断、定时器中断、外部IO中断各自注册了处理函数中断优先级通过NVIC配置。移植到龙芯平台后中断机制变化很大。龙芯平台的中断系统通常有多个层级处理器核上的中断线IP2、IP3等分别对应不同的中断控制器。外设的中断先汇聚到中断控制器再由中断控制器向CPU核上报。这个过程中会有一个“中断号映射”的概念外设中断号不等于CPU中断线中间需要查一张映射表或者通过设备树来解析。在Linux内核框架下中断处理相对简单注册一个request_irq传一个中断号内核会处理底层的映射和回调。但在我们的实际场景中有一部分驱动跑在用户态裸机环境下没有内核帮你管理中断就需要自己写中断处理入口并且要处理“中断上下文”的问题比如保存现场、禁止嵌套中断、清除中断标志位。这里有一个很重要的坑中断标志位必须及时清除但清除时机不对又可能丢失中断。有些外设的中断状态寄存器是写1清除write-1-to-clear的有些是读清除的有些则是写0清除的。如果沿用ST驱动的习惯性操作在龙芯的外设上可能就会误触发或漏触发中断。我们在调试一个外部IO中断时反复进入中断函数但读到的外部事件值却不对。后来用示波器抓电平发现是中断标志清除操作写错了导致中断一直挂着系统不停地响应。改成正确的清除方式后一切正常。这类问题建议在调试时不要急着看业务逻辑先写一个精简的中断测试函数只做一件事进入中断后翻转一个GPIO上位机用示波器观察GPIO翻转频率是否正常。频率正常说明中断本身没问题再去检查业务逻辑。3.4 I2C和SPI等总线型外设的移植I2C和SPI的移植思路与GPIO、UART类似但更麻烦一点因为总线型外设涉及的时序更多。ST的I2C外设内置了时序计算寄存器基于APB时钟自动计算SCL频率。龙芯平台的I2C控制器则通常需要手动配置时钟分频而且一次传输的字节数、起始停止条件控制方式都不尽相同。我们这次移植了I2C接口的温湿度传感器原驱动逻辑很简单初始化I2C、发送设备地址、写寄存器地址、读数据、解析。移植过程中发现的主要问题是时序不满足。ST的I2C因为时钟设置方便SCL频率可以做到400kHz乃至1MHz龙芯平台I2C寄存器配置不当的话实际SCL频率可能会偏差很大导致传感器不响应或者数据错误。用示波器看波形是最好的调试方式。如果没有示波器可以先用逻辑分析仪抓I2C波形确认起始条件、地址、数据位是否正常。我们当时抓完波形后发现ACK信号一直拉不低问题出在I2C外设配置的“输入滤波器持续时间”太长导致接收端采样不到从设备拉低的ACK。调整滤波器参数后恢复正常。SPI方面主要问题是时钟极性和相位的匹配。ST的SPI可以很方便地配置CPOL和CPHA龙芯平台有些SPI控制器的配置方式更隐晦。对应的方法就是仔细对照LCD或者Flash芯片的数据手册找到要求的时序模式再翻龙芯SoC手册找到对应的寄存器位。这一点没有捷径就是看手册反复验证。4. 操作系统适配让驱动在麒麟系统里跑起来4.1 Linux内核驱动还是用户态驱动怎么选当目标系统是麒麟Linux内核时驱动落地方式的选择直接影响后续的工作量。我们这次实际用到了两种方式简单对比一下对比项内核驱动用户态驱动性能高无上下文切换损耗稍低有系统调用开销调试便利性较难一个oops可能整机崩溃容易gdb直接调试开发速度慢编译内核模块耗时快迭代周期短安全稳定性高有内核保护机制低非法地址直接段错误与系统集成可热插拔、设备模型管理需要自己管理资源我的个人建议是前期快速验证用用户态驱动后期正式交付用内核驱动。用户态驱动通过mmap把外设物理地址映射到用户空间相当于在用户态直接操作寄存器。这种方式写起来快遇到段错误也能立即定位到具体的代码行非常适合驱赶开发节奏。等到功能全部调通再把关键外设改写成内核模块性能更好也符合Linux社区的开发惯例。4.2 设备树的关键作用在Linux内核环境下驱动与硬件的匹配主要靠设备树Device Tree。设备树描述了一个板子上有哪些外设、各自的寄存器基地址、中断号、时钟源等信息。内核在启动时解析设备树然后把相应资源传递给驱动。我们移植ST驱动时一个非常关键的步骤就是为新板卡写设备树节点。比如串口节点要指定compatible属性、reg属性寄存器基地址和长度、interrupts属性中断号和触发方式、clocks属性时钟源。这些信息在ST平台上往往写死在HAL库的配置结构体里而在龙芯Linux环境下则要写进设备树。设备树写错的一个典型问题是中断号配置错误。因为设备树里填的中断号是软件中断号需要经过中断控制器驱动翻译成实际硬件中断源。翻译规则在不同SoC上不一样只能靠芯片手册和官方的设备树文件来对照。我们当时串口中断一直不触发后来发现设备树里填的interrupt-cells个数不对导致中断号解析错误。改对后一切正常。如果你用的是用户态驱动方式就不需要设备树直接读芯片手册找到物理地址然后mmap映射即可。这种方式灵活但代码可复用性差换一块板卡就得改代码。长期来看还是设备树内核驱动的方式更适合维护。4.3 应用层兼容层让上层业务无感切换这次移植最让团队欣慰的是应用层几乎没有改动。原因是在驱动和上层业务之间加了一层“兼容接口层”——这一层对外提供了和原ST驱动几乎相同风格的API内部则根据平台编译宏调用不同架构的具体实现。拿一个简单的drv_spi_write_read函数举例在ST平台下它内部调用HAL_SPI_TransmitReceive在龙芯平台下它内部调用用户态mmap映射后封装的SPI读写函数。上层代码不需要知道这个函数的内部实现只要传入同样的参数拿到同样的返回值业务逻辑就可以原封不动地运行。这一层的设计原则是接口尽量简单、参数尽量少、返回值尽量规范。别想着把ST驱动的所有特性都暴露给上层那只会让接口越来越臃肿。比如我们针对LCD屏只暴露了初始化、写命令、写数据、设置坐标四个接口。上层画点画线、显示字符的代码完全不需要关心底层用的是SPI还是I2C也不需要关心寄存器怎么操作。这个兼容层还有一个额外的好处可以在编译时加入一层“模拟驱动”在没有真实硬件的开发机上用软件模拟外设行为方便上层逻辑的联调。这在ST和龙芯硬件同时缺货的时候特别有用。5. 调试实录踩过的坑和排查思路5.1 时钟配置与波特率异常我们最早遇到的一个奇怪问题是串口能打印数据但打印的内容是乱码。起初怀疑是代码里的波特率配置有问题用示波器去抓TX引脚的波形发现一个字符位的宽度完全不是期望的9600波特率所对应的脉宽。搜索了龙芯的时钟框架才发现UART模块的时钟源来自一个可以选择的MUX默认选择的是低频时钟跟设备树里设置的时钟频率不一致。这个坑的排查过程让我印象很深代码没问题、寄存器配置也对但就是实际频率和你预想的不一样。单纯靠读代码很难发现问题必须靠示波器实测信号再反推时钟链路。日志乱码的问题解决后又出现了“偶尔丢字符”的现象。排查后发现是接收FIFO的中断触发方式设置问题。16550兼容UART可以设置FIFO触发等级默认是1字节就触发中断但若中断处理函数里读数据太慢新到的数据就会溢出丢掉。把FIFO触发等级调高比如到8字节再触发就能有效降低溢出概率。5.2 中断号映射导致的中断不触发中断不触发是驱动移植里最闹心的问题。因为不报错、不死机就是功能不工作。我们在移植一个外部按键中断时代码逻辑已经在ST平台上验证过无数次了到龙芯平台上却始终不进入中断回调。排查步骤是这样的第一步检查GPIO是否配置成输入模式测试读取电平能够正确反映按键状态。这一步通过了说明GPIO基础配置没问题。第二步检查中断触发条件是用上升沿还是下降沿设备树里是否配置正确。第三步检查中断号。这里最容易出问题。设备树里写的中断号必须对应中断控制器驱动中注册的hwirq。有时候还要看interrupt-parent属性指向的是哪个控制器如果写错控制器节点中断号解析就会错位。最终我们发现问题果然出在设备树的中断号上。官方SDK里的参考设备树文件写的是另一个外设的中断我直接复制过来改了一下GPIO编号忘了改interrupt-parent。改对之后按键中断马上正常。5.3 DMA传输与缓存一致性问题如果用DMA做大数据传输比如从串口接收一大包数据或者向LCD显存写入数据就绕不开缓存一致性问题。在ST平台上Cortex-M内核和DMA之间的缓存一致性通常由硬件自动保证或者通过简单的__disable_irq就能暂时规避。但龙芯平台上如果要走DMA情况更复杂。Linux内核中处理DMA的常规做法是使用dma_alloc_coherent分配一致性的DMA缓冲区这种方式能保证CPU和设备看到的数据是一致的。如果用的是普通kmalloc内存需要在DMA传输前调用dma_map_single做地址映射传输完成后调用dma_unmap_single并选择合适的dma_sync方向刷新缓存。我们第一次做DMA接收时传输标志位看起来一切正常数据长度也对但读取的数据内容全是乱的。后来发现就是没有正确处理CPU缓存DMA把数据写到了内存但CPU读到的还是缓存里的旧值。这个问题如果你不做DMA可能一辈子碰不到但只要做DMA就得把整个cache维护流程刻在脑子里。5.4 调试效率提升的技巧整个项目做下来收获最大的其实不是代码而是调试方法。首先一定不要打“printf漫游”战术要在关键路径上设计好调试接口。比如每个外设驱动都暴露一个自检函数可以单独运行、单独验证。这样出问题时能快速缩小排查范围。其次善用示波器和逻辑分析仪。驱动移植本质上是在和电信号打交道很多逻辑上怎么看怎么对的问题用示波器一看波形就全明白了。再次把内核日志等级调整好。通过echo 8 /proc/sys/kernel/printk可以把内核调试信息全部打出来虽然信息量很大但关键时候能救命。最后保持一个“最小化复现”的思维。遇到问题先不要急着分析业务功能为什么不正常而是写一个最简单的测试程序单独测试对应模块把问题降到最底层再逐层向上定位。写在最后龙芯K平台的ST驱动移植技术上听起来很高大上实际做下来就是一件一件枯燥的比对、调试、验证工作。最难的从来不是某一段代码怎么写而是面对一个陌生的处理器平台如何把已有的逻辑和经验正确地“翻译”过去。这次项目能顺利推进很大程度上归功于一开始对驱动代码的依赖梳理和对ST与龙芯平台差异的充分认识。在这个过程里我个人最大的体会是移植驱动不要执着于“把代码搬过来”而要想清楚“这个驱动到底在做什么、依赖哪些硬件特性、新的平台如何提供这些特性”。想明白了这个剩下的写代码就是体力活。另外调试工具一定要配齐示波器、逻辑分析仪、串口调试线这些硬件的投入远比多写几年代码更能节省时间。希望这篇复盘能给你在类似平台适配的工作中带来一点参考少踩几个我们踩过的坑。
