尧图网站建设 
1. 项目概述为什么自定义板跑TouchGFX会让人头大先聊聊背景。TouchGFX是ST主推的GUI框架配合STM32的LTDC、DMA2D这些外设能做出很流畅的界面效果。官方评估板上一键生成工程、开箱即用但一旦换成自定义板子事情就完全不一样了。我最近在一个基于STM32H750的自定义硬件上移植TouchGFX前前后后折腾了将近两周踩了各种坑白屏、花屏、触摸坐标偏移、刷新率上不去甚至编译的时候直接报内存不足。老实说这些坑在官方板上几乎不可能遇到但自定义板完全暴露了TouchGFX底层设计里那些“约定俗成”但文档里没写透的东西。这篇内容适合谁看正在或准备在自己的板子上跑TouchGFX的嵌入式开发者尤其是用过官方评估板流畅跑起来、换到自研硬件后一脸懵的朋友。文章不会只给结论而是把每一步的为什么讲清楚比如为什么帧缓冲非要放在SDRAM、为什么触摸屏的坐标映射能差出十万八千里、为什么明明开了DMA2D加速帧率还是上不去。这些知识在官方文档里都有零散提及但确实需要有人把它们串起来讲一遍。项目本身不复杂MCU是STM32H750VBT6主频跑480MHz外挂8MB SDRAM屏幕是一块5寸RGB接口电容触摸屏分辨率800x480触摸芯片是GT911通过I2C连接。显示部分用LTDC直接驱动RGB屏没有经过任何转换芯片。TouchGFX版本是4.21CubeMX版本是6.8固件包版本是1.11.2。这些版本组合经过实测是稳定的后面会提到版本匹配的问题。整体来说这个项目的核心难点不在于TouchGFX本身而在于它和底层硬件的配合。LTDC的时序参数、SDRAM的带宽分配、DMA2D的Cache一致性、触摸屏的坐标变换每个环节单独看都不难但叠加在一起就会让人崩溃。我尽量把每个环节的排查思路和最终方案都记录下来方便大家直接对照参考。2. 移植方案的选型逻辑先搞清楚TouchGFX的“底牌”2.1 TouchGFX的架构决定了移植的复杂度TouchGFX的架构核心是三层应用层Application、中间件层MVP框架中的Presenter和Model、渲染层Renderer。渲染层直接操作帧缓冲Framebuffer它不关心帧缓冲在内存哪里、屏幕怎么点亮只关心“把像素数据写到这块内存”。这句话非常关键因为它意味着TouchGFX本身其实不挑剔硬件真正决定移植难度的是你怎么把帧缓冲和LTDC、SDRAM这些外设正确地串起来。官方评估板的厉害之处在于ST已经把这一切都配好了你甚至不需要知道帧缓冲在哪。但自定义板子的第一步就是回答几个问题像素格式选RGB565还是ARGB8888帧缓冲放内部RAM还是外部SDRAM单缓冲还是双缓冲这几个问题直接决定了后续所有配置的走向。我的选择是RGB565 SDRAM 双缓冲。为什么不用ARGB8888因为800x480的屏幕RGB565每像素2字节一帧需要8004802 768000字节约750KB。双缓冲就是1.5MB。H750的内部RAM总共512KB其中DTCM 128KB、AXI SRAM 256KB、SRAM1/2/3共128KB能连续分配给帧缓冲的最大块就是AXI SRAM的256KB单帧750KB显然放不下所以外部SDRAM是必然选择。ARGB8888单帧就要1.5MB双缓冲3MBSDRAM虽然够用但带宽占用翻倍没那个必要。像素格式这一层还有个隐藏坑LTDC本身支持各种格式但TouchGFX生成代码的时候会检查Application::getInstance()里注册的位图格式如果位图格式和帧缓冲格式不一致UI上的图片会以错误的格式解析表现就是颜色不对、透明通道丢失。我的建议是全链路统一用RGB565图片资源在TouchGFX Designer里导出时就转成RGB565这样最省事。2.2 外部SDRAM作为帧缓冲的注意事项SDRAM作为帧缓冲有好有坏。好处是容量大可以双缓冲甚至三缓冲坏处是带宽和延迟。H750的FMC接口跑SDRAM时钟频率最高约100MHz16位数据总线理论峰值带宽400MB/s100MHz * 2 * 16bit / 8。LTDC刷新800x48060Hz RGB565每秒需要的数据量是8004802*60 ≈ 46MB/s。DMA2D做图形加速的时候也会频繁读写SDRAM加上CPU访问总体带宽占用大概在20%-40%之间实测下来FMC能做到100MHz时系统还能稳定运行。但如果SDRAM频率跑超标比如110MHz甚至120MHz就会出现偶发花屏尤其是UI动效多的时候因为LTDC从SDRAM读数据出现超时画面就会出现横条纹撕裂。SDRAM初始化时序也是一个大坑。H750的FMC模块对SDRAM的时序配置项包括TRCD、TRP、TWR、TRC等这些参数必须和SDRAM芯片的数据手册严格对应。我用的SDRAM是W9825G6KHCAS Latency设为3TRCD3个时钟周期TRP3TWR2TRC8。CubeMX的SDRAM配置界面里有个“Load To Active Delay”和“Exit Self-Refresh Delay”之类的参数翻译得很绕其实对应的就是TRCD和TRC。如果不确定参考数据手册里的AC特性表找到典型值直接填进去。还有一个值得注意的点SDRAM初始化不能在系统时钟稳定之前执行否则FMC会偶发初始化失败。CubeMX生成的代码里MX_FMC_Init()是在SystemClock_Config()之后调用的顺序没问题。但如果自己写了bootloader从bootloader跳转到App前已经把SDRAM初始化过一遍App里再次初始化一般也没问题因为FMC寄存器会被重新写入。但如果bootloader里用了SDRAM做堆栈App再初始化SDRAM就会出问题这种场景建议在bootloader里做完SDRAM初始化后不要关掉FMC时钟。2.3 版本匹配这件事折磨人的程度超乎想象TouchGFX的版本、CubeMX的版本、STM32CubeF7/H7固件包的版本这三者必须匹配。我一开始用的是CubeMX 6.8搭配TouchGFX 4.21固件包却是1.10.1结果TouchGFX Designer生成的代码在编译时报了一堆“TouchGFXConfiguration”相关的错误还找不到头文件。排查了一圈发现是固件包里的Middlewares/ST/TouchGFX目录版本太老和4.21的代码不一致。后来我把固件包升到1.11.2问题就解决了。所以建议先看TouchGFX的Release Note里面会写清楚支持哪些STM32Cube固件包版本。另外TouchGFX Designer整合进CubeMX的插件版本也要保持一致否则会出现“CubeMX生成的代码和Designer导出的代码互相覆盖”的问题最常见的就是TouchGFX_Config.h里配置的帧缓冲地址和实际LTDC_DMA2D的地址不一致。版本匹配这里我吃过大亏写出来提醒一下如果你用的是老版本CubeMX建议先别急着升级TouchGFX因为TouchGFX生成代码的工程结构会变升级后旧工程很可能编译不过去。最稳妥的方式是记录当前的CubeMX版本去ST官网下载对应版本的固件包再下载与之匹配的TouchGFX Designer版本三者一起装。3. 核心环节实操从CubeMX配置到TouchGFX Designer导出的完整闭环3.1 LTDC时序配置屏幕不亮根因在HSYNC/VSYNC参数上RGB接口屏幕的数据手册里会有一张时序参数表配置LTDC时需要用到的核心参数包括HSPW行同步脉宽、HBP行后肩、HFP行前肩、VSPW帧同步脉宽、VBP帧后肩、VFP帧前肩以及像素时钟频率Pixel Clock。这些参数直接影响屏幕是否正常显示任何一个参数不对表现可能是白屏、画面偏移、闪烁或者屏幕直接不亮。以我手头这块5寸屏为例数据手册给出的参数是像素时钟9MHzHSPW1HBP40HFP40VSPW1VBP13VFP12。算一下总的水平周期800 1 40 40 881个像素时钟总的垂直周期480 1 13 12 506行。像素时钟9MHz下帧率就是9MHz / (881*506) ≈ 20Hz。20Hz刷新率太低了肉眼可见的闪烁。这里需要做一个关键计算LTDC的PixelClock怎么来的H750的LTDC时钟源是PLL3的Q输出通过RCC_PLL3CLKSOURCE选择我配置的是PLL3 Q 25MHz然后LTDC的Divider设置为2最终PixelClock 25/2 12.5MHz。调整后的帧率是12.5MHz / (881*506) ≈ 28Hz仍然偏慢。但实际用下来28Hz的刷新率在UI动效不多的时候已经能接受了而且TouchGFX默认的帧率是60fps实际LTDC刷新率和TouchGFX帧率是两回事——TouchGFX的帧率是渲染帧率LTDC刷新率是屏幕物理刷新率。只要TouchGFX的渲染时间低于屏幕刷新周期用户感知起来就是流畅的。这块屏的物理极限就在这没法改。如果你的屏像素时钟能跑到30MHz以上体验会好很多。所以我给个建议选屏的时候不要只看分辨率像素时钟上限直接决定刷新率上限这比分辨率更影响TouchGFX体验。CubeMX的LTDC配置界面里有一个“Timing”选项卡填好这些参数后下面会自动算出一个Vertical Blanking和Horizontal Blanking不用手动填。但要注意如果直接照抄数据手册的参数CubeMX可能会因为边界条件报错比如某些参数的最小值不满足。这个时候可以把HFP/HBP增大一些一般不会出问题但增大会降低刷新率所以尽量保持数据手册的值。3.2 帧缓冲地址设置CubeMX和TouchGFX之间的“暗线”LTDC配置完成后CubeMX里会有一个“Layer”选项卡可以配置LTDC Layerx的窗口位置、像素格式、帧缓冲地址等。生成代码后LTDC_LAYER的帧缓冲地址默认指向一个内部RAM数组。但TouchGFX的帧缓冲地址是在TouchGFX_Config.h或者stm32h7xx_hal_msp.c里通过LCD相关的宏定义指定的两者完全是两回事。更关键的是如果CubeMX自动生成的main.c里MX_LTDC_Init()已经把Layer的FrameBufferAddress设置成了一个内部RAM数组而TouchGFX在HAL::getInstance()初始化之后会重新配置LTDC的FrameBufferAddress为TouchGFX自己的帧缓冲地址这两个地址如果不一致就会出现“白屏”或者“显示的是残影”的现象。排查方法是在TouchGFXHAL::initialize()里打个断点等初始化完成之后读一下LTDC_Layer1-CFBAR寄存器看这个地址是不是等于你在TouchGFX里配置的帧缓冲地址。如果不等于说明有代码在TouchGFX跑完之后又改回了CubeMX默认的地址。这个问题的根源是TouchGFX的HAL::endFrame()函数在每次渲染完成后会更新LTDC的帧缓冲地址到当前帧但前提是LTDC配置里启用了多个LayerTouchGFX只管理它使用的那一层。我的方案是在CubeMX里直接不用LTDC Layer的初始配置把Layer的帧缓冲地址设为0然后在TouchGFX的HAL初始化后由它自己来设置。Layer的窗口坐标X0,Y0,X1,Y1还是在CubeMX里配好否则LTDC不会输出像素时钟。其实更省事的操作是CubeMX里生成工程后把main.c里MX_LTDC_Init()中的pLayerConfig.FrameBufferAddress改成一个SDRAM地址变量比如0xC0000000确保初始状态就有效。后面TouchGFX接管后会反复修改这个地址不会影响运行。3.3 TouchGFX Designer的工程配置分辨率、像素格式和平台集成TouchGFX Designer负责UI设计、资源导出和应用代码生成。新建工程时有个“Target”设置需要选择“STM32”系列和具体的“Board”。如果你用的自定义板不在列表里随便选一个比较接近的开发板然后再手动改touchgfx_conf.h和ApplicationFont相关的配置。我这里直接选了STM32H750B-DK这个开发板虽然它用的屏幕参数和我的不一样但Designer的代码结构是通用的后面手动改几个关键宏就行。关键配置项是分辨率。Designer里如果设置了800x480生成代码的HAL初始化里就会判断屏幕尺寸但真正决定LTDC输出分辨率的是CubeMX里的LTDC配置。如果两者不一致最典型的表现就是Designer里预览正常板子上显示的画面被裁剪或者只有左上角一部分。我的做法是Designer和CubeMX都统一用800x480避免节外生枝。像素格式在Designer里的设置路径是ProjectTargetColor Depth。选RGB565还是ARGB8888这一点和前面的架构选择要保持一致。如果选错颜色会发绿、发紫或者完全错乱因为TouchGFX的Bitmap格式和帧缓冲的PixelFormat不匹配时渲染器会做不必要的颜色转换浪费CPU周期和DMA2D带宽。完成设置后Designer会生成一个generated目录里面包含fonts、images、texts、videos等资源以及核心的MVP代码框架。在CubeMX工程里需要把TouchGFX Designer生成的代码目录路径加到编译器的Include路径里并在main.c里正确初始化。需要注意每次Designer生成之后generated目录都会被覆盖如果你手动改过generated下的文件下次生成前记得备份否则改动会被清掉。有个容易忽略的点Designer生成的TouchGFXConfiguration.cpp里会#include stm32h7xx_hal.h如果CubeMX工程里没有正确配置HAL头文件的搜索路径编译会直接失败。检查方法很简单在工程里搜stm32h7xx_hal.h确认它来自Drivers/STM32H7xx_HAL_Driver/Inc。3.4 双缓冲的关键配置渲染一帧显示一帧中间不打架TouchGFX的双缓冲机制是渲染器往BackBuffer写入同时LTDC从FrontBuffer读取显示渲染完成后交换两个缓冲区的角色。这个“交换”不是物理切换内存地址而是通过修改LTDC的帧缓冲地址寄存器LTDC_Layer1-CFBAR来实现的。在TouchGFXHAL::endFrame()里会调用HAL::setFrameBuffer()来切换地址这个过程需要一个关键机制等LTDC开始扫描到垂直消隐区VBlank再切换否则画面会在切换瞬间出现撕裂tearing。TouchGFX官方方案是使用LTDC的Line中断在VBlank中断里更新CFBAR。H7系列还可以使用LTDC_LAYER_CFBAR寄存器的更新机制配合双缓冲的情况下即使不特别处理撕裂概率也比较低但要做到完全无撕裂还是建议开启LTDC_LCD_TFT的垂直消隐中断。这里有个经典的错误配置如果在CubeMX里没有开启LTDC全局中断LTDC_IRQnTouchGFX的HAL::endFrame()里的VBlank等待函数就永远不会返回表现为界面卡在第一帧或者干脆黑屏。这个坑让我排查了很久。解决方案是在CubeMX的NVIC设置里把LTDC global interrupt设为Enable同时LTDC_ER_IRQn也建议设为Enable用于处理错误中断方便排查。双缓冲的另一个配置在touchgfx_conf.h里有一个FRAME_BUFFER_SIZE宏或者类似的地方需要确保它等于一帧的大小即800*480*2 768000。如果这个值配小了运行时会出现内存越界表现随机有时候是左上角花屏有时候是程序跑飞进HardFault。4. 实操过程实录一步步把TouchGFX跑起来4.1 CubeMX时钟树配置SDRAM要稳LTDC要准时钟树的配置是整个项目的基础。H750的最高主频是480MHz但LTDC和外设的时钟和它没有直接关系需要单独配置PLL。我的配置路径是外部晶振HSE25MHzSYSCLK480MHz通过PLL1AHB分频1480MHzAPB1120MHz、APB2120MHz。PLL3用于生成LTDC和FMC的时钟PLL3的M5、N160、P2、Q8这样PLL3的Q输出25/5160/8 100MHz供SDRAM使用PLL3的P输出25/5160/2 400MHz不直接用但没关系。LTDC的时钟源选了PLL3的Q然后在RCC的LTDC Clock Divider里设置为4这样LTDC的PixelClock 100MHz / 4 25MHz实际上我最终是配置Divider8获得12.5MHzDivider4获得25MHz但25MHz超出了屏的规格书上限9MHz所以还是用了12.5MHz。这里要特别提醒CubeMX的时钟树里有几个输入框容易让人迷路尤其是“PLL3 R”和“LTDC”之间的连线鼠标悬停才能看到最终频率。一定要确认实际生成的SystemClock_Config()里RCC_PLL3_DIVQ_VALUE和LTDC Divider的值和你在图形界面里看到的一致。不同版本的CubeMX对时钟树界面的展示逻辑有细微差别但都有实时频率提示照着提示调就行。FMC这边SDRAM的时钟就是PLL3Q的100MHz。注意FMC频率不能太高否则SDRAM的建立保持时间不够表现为偶发数据错误。100MHz是W9825G6KH的规格上限为了稳妥也可以把PLL3Q调到96MHzSDRAM性能损失几乎感知不到但稳定性提升明显。我最终选择了96MHzM5, N192, Q10这样整条链路的余量更足。4.2 启动文件与链接脚本SDRAM地址怎么暴露给TouchGFXH750的SDRAM地址在FMC bank1的映射区域具体是0xC0000000到0xC7FFFFFF根据SDRAM大小和FMC Bank选择而定。TouchGFX的帧缓冲要放到这个区域链接脚本必须把这个区域暴露给C代码使用。CubeMX生成的.ld链接脚本默认只包含内部RAM的MEMORY区域SDRAM需要手动添加。我的做法是新增一个MEMORY段MEMORY { FLASH (rx) : ORIGIN 0x08000000, LENGTH 128K DTCMRAM (xrw) : ORIGIN 0x20000000, LENGTH 128K RAM_D1 (xrw) : ORIGIN 0x24000000, LENGTH 512K SDRAM (xrw) : ORIGIN 0xC0000000, LENGTH 8M }H750的Flash只有128KB但代码量可能超过这个数需要开启L1 Cache配合XIP从外部QSPI Flash执行。这个先按下不表。关键是MRAM区域并非连续的H7的内存布局比F系列复杂一定要确认地址范围没有重叠。链接脚本里定义一个SDRAM的Section或者直接用一个全局变量指向SDRAM地址__attribute__((section(.sdram))) uint8_t framebuffer[800*480*2];然后在TouchGFX_Config.h里把FRAME_BUFFER_ADDRESS指向这个变量或者直接写0xC0000000。直接写地址有个注意点链接器不会帮你检查这个地址是否已被使用如果其他变量也放在SDRAM可能会被帧缓冲覆盖。我的做法是单独把帧缓冲数组放到SDRAM区域且在Section属性里加上aw声明其余SDRAM空间留给动态分配。这里还有个隐藏坑H7的D-Cache默认是开启的但SDRAM区域如果没有配置为Cacheable尤其被DMA2D访问时CPU和DMA2D看到的数据可能不一致。后面会专门讲Cache一致性问题。4.3 移植过程中最折磨人的一步TouchGFX HAL的底层对接TouchGFX的HAL层是个大杂烩包含HAL、HALTouchGFX、TouchGFXHAL、OSWrappers这些类和文件。CubeMX生成的代码里有一个TouchGFXHAL.cpp文件它是移植的“前线”。TouchGFXHAL的初始化流程大概是先调用基类构造函数传入Display接口、帧缓冲、尺寸等信息然后在initialize()里配置LTDC、触摸、DMA2D等。最关键的是HAL::getInstance()-setFrameBufferStartAddress()这个方法告诉TouchGFX帧缓冲的起始地址。在我的工程里TouchGFXHAL::initialize()里会调用一个LCD类的初始化函数这个LCD类在touchgfx/hal/BoardConfiguration.hpp里声明具体实现在CubeMX生成的TouchGFXHAL.cpp底部。如果LCD::init()里没有正确配置LTDC Layer的窗口大小或者像素格式画面输出就会歪掉。还有一个文件叫stm32h7xx_hal_msp.c里面是HAL库的底层回调。TouchGFX生成的工程里这个文件会被CubeMX覆盖所以如果修改了其中的LTDC初始化相关代码最好在CubeMX的User Code区注释里写保证重新生成代码时能被保留。4.4 触摸芯片GT911的坐标映射触摸和显示是两条线LTDC负责显示触摸通过I2C读取坐标。GT911是电容触摸控制器通过I2C接口通信地址有两种可选0x28/0x29由INT引脚电平决定。GT911上电后需要写入配置并且要等待它输出就绪信号。坐标映射的坑在于触摸屏的X轴方向和屏幕的X轴方向可能是反的Y轴同理。TouchGFX的TouchEvent给的坐标是原始屏幕坐标如果在初始化触摸驱动时方向映射没处理点击按钮就会点不到或者点左边弹右边。GT911会返回原始触摸坐标坐标系是触摸屏的物理坐标系常见的是左上角为原点但实际上取决于屏幕安装方向。我的做法是在驱动初始化后用一个简单的测试程序点击屏幕四个角落打印TouchGFX收到的坐标确认映射关系后在BoardConfiguration.cpp里对坐标做转换uint16_t x raw_x; uint16_t y raw_y; // 如果X方向反了 x SCREEN_WIDTH - 1 - raw_x; // 如果Y方向反了 y SCREEN_HEIGHT - 1 - raw_y;这里要特别注意GT911的坐标分辨率是1024不是屏幕的800x480。需要先确认GT911的配置里X/Y输出范围是否设置为屏幕分辨率否则需要缩放。GT911的配置寄存器0x8040-0x8041是X输出最大值0x8042-0x8043是Y输出最大值。如果默认是1024那坐标需要按比例缩放uint16_t scaled_x raw_x * SCREEN_WIDTH / 1024; uint16_t scaled_y raw_y * SCREEN_HEIGHT / 1024;实际测试下来GT911有一个很头疼的特性它在上电后需要延时约100ms才能访问配置寄存器否则I2C通信会无响应。如果板子用的GPIO模拟I2C或者I2C外设时钟不够稳定还会出现配置写入失败的情况。我的建议是在触摸初始化代码里AT24Cxx之类的EEPROM写入模式吗不GT911的配置是直接写ROM但要注意的是上电后的第一个I2C事务先用一个伪读取来“唤醒”GT911然后再发送配置。4.5 DMA2D加速不要让CPU去填充像素TouchGFX默认会用DMA2D来做2D加速例如填充背景色、复制图像、混合透明度。如果DMA2D配置不对界面不仅没有加速效果反而会因为CPU等待DMA2D完成而变得更慢。DMA2D的关键配置在于它的中断必须在NVIC里启用。TouchGFX的DMA2D驱动在等待传输完成时会进入__WFI等待中断唤醒如果DMA2D中断被关闭程序会卡死在等待循环里表现为界面卡死或者刷新率极低。这个坑在H7系列上尤其隐蔽因为CubeMX默认可能不会自动勾选DMA2D中断。DMA2D工作时还会涉及一个重要的内存一致性坑DMA2D写SDRAMCPU后续要读这块区域做逻辑判断但D-Cache缓存了旧数据读出来的可能还是旧值导致界面状态判断错乱。解决方式有两类关闭帧缓冲区域的Cache把SDRAM的内存属性配置为MT_NORMAL时使用Non-Cacheable或者专门给帧缓冲区域配置MPU为Non-Cacheable。手动维护Cache一致性在DMA2D传输完成后调用SCB_CleanDCache()写回或SCB_InvalidateDCache()失效。我的做法是给帧缓冲区域配置了MPU Region属性设置为Normal、Non-Cacheable这样CPU访问帧缓冲是直接走AHB访问SDRAM和DMA2D/LTDC访问保持一致不用每次手动处理Cache。但这种配置下CPU直接读帧缓冲做像素操作的效率会明显变低因为写缓冲都被绕过了。好在这个场景大部分工作由DMA2D承担CPU直接操作帧缓冲的地方不多实际影响可接受。如果你希望帧缓冲区域保持CacheableCPU访问更快也可以但必须在每次TouchGFX渲染完成、DMA2D写完帧缓冲之后调用SCB_CleanDCache_by_Addr把帧缓冲区域的Cache写回SDRAM再让LTDC控制器读取。注意LTDC本身是通过AXI总线DMA读的走的是AXI SRAM的路径所以它不受CPU Cache的影响这也是H7的AXI SRAM设计初衷之一。但这个方案有个副作用每次帧渲染完成都要Clean整个缓冲开销不小实测和Non-Cacheable方案对比性能差距不大。所以我最终选择了Non-Cacheable方案省心。5. 常见问题与排查技巧实录5.1 白屏、黑屏、花屏从信号链路上找根因白屏是最常见的现象含义是LTDC没有输出有效的像素数据屏幕背光亮了但画面全白或者屏幕直接黑。排查顺序非常重要第一步查LTDC时钟。通过调试器确认LTDC-GCR寄存器里的LTDCEN位是否为1同时检查LTDC-CDSR寄存器里的VCLK状态确认垂直和水平同步信号是否产生。这一步能定位是不是时钟配置问题。如果LTDCEN为0多半是MX_LTDC_Init()没有被调用或者调用时参数校验失败返回错误。第二步查Layer配置。确认LTDC_Layer1-CR的LEN位为1LTDC_Layer1-WHPCR和WVPCR寄存器值是否和你配置的分辨率一致。如果Layer被禁用了LTDC主时钟依然输出但像素数据层不使能屏幕显示白屏。第三步查帧缓冲地址。在LCD初始化后的主循环里读LTDC_Layer1-CFBAR如果值为0或者指向未初始化的RAM说明帧缓冲地址没有被正确设置。花屏的情况更复杂一点如果整个画面有规律地“左右错位”术语叫“行场错位”通常是HBP/HFP参数不合适导致LTDC的行同步信号和像素数据对不上。如果花屏是无规律的色块极大可能是SDRAM数据不稳定优先排查SDRAM的时序和FMC时钟。一个快速验证方法不停填充SDRAM区域为0xFFFF然后读回校验如果某个地址偶尔不对说明SDRAM时序有问题。5.2 触摸坐标偏移校准矩阵的两种方案触摸坐标偏移的原因有三种触摸屏本身的固有偏移、坐标分辨率不匹配、安装方向不一致。GT911的坐标输出是12位的范围0-4095但配置寄存器可以设置输出范围。我配置成800x480后坐标就是屏幕上按比例直接映射的。但如果你的屏幕模块是“组合屏”——触摸屏和液晶屏不是原厂贴合而是后期通过排线连接那么触摸屏的物理坐标系和显示坐标系会存在固定的偏移和旋转。这种情况就需要做校准。TouchGFX没有内置触摸校准库但可以自己实现。最简单的校准方式是基于四点的线性变换// 假设屏幕四点物理坐标 (x1,y1)-(x4,y4) // 对应触摸点采样坐标 (tx1,ty1)-(tx4,ty4) // 解一个仿射变换矩阵四点校准比三点更准确但实现复杂度也更高。实际上很多产品只做两点校准也够用分别在屏幕左上和右下采集两个触摸点算出X轴和Y轴的缩放比例和偏移量。我之前做过一个自动校准工具用TouchGFX的CustomWidget显示一个十字光标用户点一下记录坐标重复采集对角两个点后计算出参数固化到Flash里。这个方法对量产阶段的个体差异很有效。5.3 Cache一致性导致的“幽灵Bug”Cache一致性问题最典型的场景TouchGFX渲染完成后显示画面有时候是残影有时候画面有部分区域是上一帧的内容而且没有规律。排查方法也比较直接在endFrame()里关闭D-Cache或者用MPU把帧缓冲区域设为Non-Cacheable问题消失那基本就锁定是Cache一致性问题了。如果不想全局关闭Cache可以针对帧缓冲区域单独配置MPU。H7上配置MPU的代码可以在main.c的MPU_Config()里加MPU_Region_InitTypeDef MPU_InitStruct {0}; HAL_MPU_Disable(); MPU_InitStruct.Enable MPU_REGION_ENABLE; MPU_InitStruct.BaseAddress 0xC0000000; MPU_InitStruct.Size MPU_REGION_SIZE_8MB; MPU_InitStruct.AccessPermission MPU_REGION_FULL_ACCESS; MPU_InitStruct.IsBufferable MPU_REGION_NOT_BUFFERABLE; MPU_InitStruct.IsCacheable MPU_REGION_NOT_CACHEABLE; MPU_InitStruct.IsShareable MPU_REGION_NOT_SHAREABLE; HAL_MPU_ConfigRegion(MPU_InitStruct); HAL_MPU_Enable(MPU_CONTROL_HRDZENA);注意MPU Region的Size必须覆盖整个SDRAM但其实只把帧缓冲那块配成Non-Cacheable就够了其他SDRAM继续Cacheable。实际工程中为了省事我整片SDRAM都配成Non-Cacheable代价是SDRAM上的堆操作和内存拷贝速度略低但完全够用。还有个细节帧缓冲被MPU配置为Non-Cacheable之后CPU的写操作延迟会变高对BltImage这种逐像素操作有性能影响。实测从AXI SRAM往SDRAM拷贝一帧800x480 RGB565Cacheable vs Non-Cacheable的时间差异约在1.2倍左右对60fps的全局刷新影响不大但如果你的UI有很多渐变或大量复杂绘制建议用Cacheable方案在渲染完成后统一Clean再触发LTDC刷新。5.4 刷新率上不去卡顿怎么定位TouchGFX的卡顿问题要从两个角度来拆渲染瓶颈和显示瓶颈。渲染瓶颈看的是CPU或DMA2D处理一帧需要多久显示瓶颈看的是LTDC刷新一帧需要多久。通过TouchGFX的HAL::getInstance()-getFrameTime()可以拿到上一帧的渲染耗时。如果渲染耗时接近甚至超过屏幕刷新周期比如12.5MHz像素时钟下的约35ms那界面就会掉帧。解决办法是优化图片资源格式用RGB565缩小体积、减少透明混合使用透明区域会触发DMA2D的混合操作很耗时、避免大面积的重绘。还有一个不太直观的优化点TouchGFX默认的帧率是60fps但屏幕刷新率可能只有28Hz两个指标不匹配时TouchGFX还是会按照60fps去渲染产生很多无用的帧白白消耗CPU。可以在touchgfx_conf.h里调整FRAME_RATE相关的配置比如把它降到30fps让TouchGFX渲染节奏和屏幕刷新率匹配反而会感觉更流畅。如果确认是显示瓶颈也就是屏幕刷新率太低除了调整像素时钟和LTDC时序还有一个办法是开启LTDC的ITMImmediate Transfer Mode在垂直消隐期间触发帧切换减少画面撕裂感。这个模式在TouchGFX里通常默认开启但需要确认LTDC_ITRCR的IMTRANS寄存器位是否正确。6. 最后再分享几个提升效率的实操技巧第一个技巧把TouchGFX引擎的日志输出打开。TouchGFX里有个touchgfx_enable_debug编译宏开启了之后会在串口打印帧率、内存使用等信息对定位性能问题帮助极大。量产版本记得关掉否则串口中断会频繁触发反而影响性能。第二个技巧在调试阶段把LTDC的帧缓冲地址在空闲时手动改成一个单色填充值比如全红、全绿这样可以快速确认LTDC链路是否正常。如果屏幕能稳定显示纯色说明显示通路没问题剩下的才是TouchGFX应用层的问题。这个方法在排查“白屏但背光亮”的时候特别高效。第三个技巧给SDRAM区域起个专属Section然后通过链接脚本的__attribute__((section(.sdram)))把一个大数组放在那里调试时直接看这个数组的十六进制值就能判断SDRAM读写是否正常比用内存窗口观察快得多。我当时就是靠这个数组一眼发现了SDRAM低16位数据总线上的虚焊问题——数组数据每隔16位就会出现一个固定错误模式。最后说说我个人在这项目里最深的体会TouchGFX在自定义板上跑的难度其实大部分不在TouchGFX而在你怎么把它依赖的底层环境调稳妥。时钟、SDRAM、LTDC、DMA2D、Cache任何一个环节有小瑕疵最终都会以GUI异常的形式暴露出来而且表现千奇百怪。如果能把这几个模块在裸机环境下分别验证通过再接入TouchGFX整个流程会顺很多。否则就会出现“万能的白屏”你完全不知道是哪个环节出的问题。我后来养成的习惯是第一步编译烧录裸机例程点亮屏幕第二步用裸机跑一遍SDRAM读写测试第三步再跑TouchGFX的SimpleButton例程。三步走完后面基本都是应用层的事了。 STM32H750自定义板TouchGFX移植实战：搞定白屏花屏与触摸偏移
1. 项目概述为什么自定义板跑TouchGFX会让人头大先聊聊背景。TouchGFX是ST主推的GUI框架配合STM32的LTDC、DMA2D这些外设能做出很流畅的界面效果。官方评估板上一键生成工程、开箱即用但一旦换成自定义板子事情就完全不一样了。我最近在一个基于STM32H750的自定义硬件上移植TouchGFX前前后后折腾了将近两周踩了各种坑白屏、花屏、触摸坐标偏移、刷新率上不去甚至编译的时候直接报内存不足。老实说这些坑在官方板上几乎不可能遇到但自定义板完全暴露了TouchGFX底层设计里那些“约定俗成”但文档里没写透的东西。这篇内容适合谁看正在或准备在自己的板子上跑TouchGFX的嵌入式开发者尤其是用过官方评估板流畅跑起来、换到自研硬件后一脸懵的朋友。文章不会只给结论而是把每一步的为什么讲清楚比如为什么帧缓冲非要放在SDRAM、为什么触摸屏的坐标映射能差出十万八千里、为什么明明开了DMA2D加速帧率还是上不去。这些知识在官方文档里都有零散提及但确实需要有人把它们串起来讲一遍。项目本身不复杂MCU是STM32H750VBT6主频跑480MHz外挂8MB SDRAM屏幕是一块5寸RGB接口电容触摸屏分辨率800x480触摸芯片是GT911通过I2C连接。显示部分用LTDC直接驱动RGB屏没有经过任何转换芯片。TouchGFX版本是4.21CubeMX版本是6.8固件包版本是1.11.2。这些版本组合经过实测是稳定的后面会提到版本匹配的问题。整体来说这个项目的核心难点不在于TouchGFX本身而在于它和底层硬件的配合。LTDC的时序参数、SDRAM的带宽分配、DMA2D的Cache一致性、触摸屏的坐标变换每个环节单独看都不难但叠加在一起就会让人崩溃。我尽量把每个环节的排查思路和最终方案都记录下来方便大家直接对照参考。2. 移植方案的选型逻辑先搞清楚TouchGFX的“底牌”2.1 TouchGFX的架构决定了移植的复杂度TouchGFX的架构核心是三层应用层Application、中间件层MVP框架中的Presenter和Model、渲染层Renderer。渲染层直接操作帧缓冲Framebuffer它不关心帧缓冲在内存哪里、屏幕怎么点亮只关心“把像素数据写到这块内存”。这句话非常关键因为它意味着TouchGFX本身其实不挑剔硬件真正决定移植难度的是你怎么把帧缓冲和LTDC、SDRAM这些外设正确地串起来。官方评估板的厉害之处在于ST已经把这一切都配好了你甚至不需要知道帧缓冲在哪。但自定义板子的第一步就是回答几个问题像素格式选RGB565还是ARGB8888帧缓冲放内部RAM还是外部SDRAM单缓冲还是双缓冲这几个问题直接决定了后续所有配置的走向。我的选择是RGB565 SDRAM 双缓冲。为什么不用ARGB8888因为800x480的屏幕RGB565每像素2字节一帧需要8004802 768000字节约750KB。双缓冲就是1.5MB。H750的内部RAM总共512KB其中DTCM 128KB、AXI SRAM 256KB、SRAM1/2/3共128KB能连续分配给帧缓冲的最大块就是AXI SRAM的256KB单帧750KB显然放不下所以外部SDRAM是必然选择。ARGB8888单帧就要1.5MB双缓冲3MBSDRAM虽然够用但带宽占用翻倍没那个必要。像素格式这一层还有个隐藏坑LTDC本身支持各种格式但TouchGFX生成代码的时候会检查Application::getInstance()里注册的位图格式如果位图格式和帧缓冲格式不一致UI上的图片会以错误的格式解析表现就是颜色不对、透明通道丢失。我的建议是全链路统一用RGB565图片资源在TouchGFX Designer里导出时就转成RGB565这样最省事。2.2 外部SDRAM作为帧缓冲的注意事项SDRAM作为帧缓冲有好有坏。好处是容量大可以双缓冲甚至三缓冲坏处是带宽和延迟。H750的FMC接口跑SDRAM时钟频率最高约100MHz16位数据总线理论峰值带宽400MB/s100MHz * 2 * 16bit / 8。LTDC刷新800x48060Hz RGB565每秒需要的数据量是8004802*60 ≈ 46MB/s。DMA2D做图形加速的时候也会频繁读写SDRAM加上CPU访问总体带宽占用大概在20%-40%之间实测下来FMC能做到100MHz时系统还能稳定运行。但如果SDRAM频率跑超标比如110MHz甚至120MHz就会出现偶发花屏尤其是UI动效多的时候因为LTDC从SDRAM读数据出现超时画面就会出现横条纹撕裂。SDRAM初始化时序也是一个大坑。H750的FMC模块对SDRAM的时序配置项包括TRCD、TRP、TWR、TRC等这些参数必须和SDRAM芯片的数据手册严格对应。我用的SDRAM是W9825G6KHCAS Latency设为3TRCD3个时钟周期TRP3TWR2TRC8。CubeMX的SDRAM配置界面里有个“Load To Active Delay”和“Exit Self-Refresh Delay”之类的参数翻译得很绕其实对应的就是TRCD和TRC。如果不确定参考数据手册里的AC特性表找到典型值直接填进去。还有一个值得注意的点SDRAM初始化不能在系统时钟稳定之前执行否则FMC会偶发初始化失败。CubeMX生成的代码里MX_FMC_Init()是在SystemClock_Config()之后调用的顺序没问题。但如果自己写了bootloader从bootloader跳转到App前已经把SDRAM初始化过一遍App里再次初始化一般也没问题因为FMC寄存器会被重新写入。但如果bootloader里用了SDRAM做堆栈App再初始化SDRAM就会出问题这种场景建议在bootloader里做完SDRAM初始化后不要关掉FMC时钟。2.3 版本匹配这件事折磨人的程度超乎想象TouchGFX的版本、CubeMX的版本、STM32CubeF7/H7固件包的版本这三者必须匹配。我一开始用的是CubeMX 6.8搭配TouchGFX 4.21固件包却是1.10.1结果TouchGFX Designer生成的代码在编译时报了一堆“TouchGFXConfiguration”相关的错误还找不到头文件。排查了一圈发现是固件包里的Middlewares/ST/TouchGFX目录版本太老和4.21的代码不一致。后来我把固件包升到1.11.2问题就解决了。所以建议先看TouchGFX的Release Note里面会写清楚支持哪些STM32Cube固件包版本。另外TouchGFX Designer整合进CubeMX的插件版本也要保持一致否则会出现“CubeMX生成的代码和Designer导出的代码互相覆盖”的问题最常见的就是TouchGFX_Config.h里配置的帧缓冲地址和实际LTDC_DMA2D的地址不一致。版本匹配这里我吃过大亏写出来提醒一下如果你用的是老版本CubeMX建议先别急着升级TouchGFX因为TouchGFX生成代码的工程结构会变升级后旧工程很可能编译不过去。最稳妥的方式是记录当前的CubeMX版本去ST官网下载对应版本的固件包再下载与之匹配的TouchGFX Designer版本三者一起装。3. 核心环节实操从CubeMX配置到TouchGFX Designer导出的完整闭环3.1 LTDC时序配置屏幕不亮根因在HSYNC/VSYNC参数上RGB接口屏幕的数据手册里会有一张时序参数表配置LTDC时需要用到的核心参数包括HSPW行同步脉宽、HBP行后肩、HFP行前肩、VSPW帧同步脉宽、VBP帧后肩、VFP帧前肩以及像素时钟频率Pixel Clock。这些参数直接影响屏幕是否正常显示任何一个参数不对表现可能是白屏、画面偏移、闪烁或者屏幕直接不亮。以我手头这块5寸屏为例数据手册给出的参数是像素时钟9MHzHSPW1HBP40HFP40VSPW1VBP13VFP12。算一下总的水平周期800 1 40 40 881个像素时钟总的垂直周期480 1 13 12 506行。像素时钟9MHz下帧率就是9MHz / (881*506) ≈ 20Hz。20Hz刷新率太低了肉眼可见的闪烁。这里需要做一个关键计算LTDC的PixelClock怎么来的H750的LTDC时钟源是PLL3的Q输出通过RCC_PLL3CLKSOURCE选择我配置的是PLL3 Q 25MHz然后LTDC的Divider设置为2最终PixelClock 25/2 12.5MHz。调整后的帧率是12.5MHz / (881*506) ≈ 28Hz仍然偏慢。但实际用下来28Hz的刷新率在UI动效不多的时候已经能接受了而且TouchGFX默认的帧率是60fps实际LTDC刷新率和TouchGFX帧率是两回事——TouchGFX的帧率是渲染帧率LTDC刷新率是屏幕物理刷新率。只要TouchGFX的渲染时间低于屏幕刷新周期用户感知起来就是流畅的。这块屏的物理极限就在这没法改。如果你的屏像素时钟能跑到30MHz以上体验会好很多。所以我给个建议选屏的时候不要只看分辨率像素时钟上限直接决定刷新率上限这比分辨率更影响TouchGFX体验。CubeMX的LTDC配置界面里有一个“Timing”选项卡填好这些参数后下面会自动算出一个Vertical Blanking和Horizontal Blanking不用手动填。但要注意如果直接照抄数据手册的参数CubeMX可能会因为边界条件报错比如某些参数的最小值不满足。这个时候可以把HFP/HBP增大一些一般不会出问题但增大会降低刷新率所以尽量保持数据手册的值。3.2 帧缓冲地址设置CubeMX和TouchGFX之间的“暗线”LTDC配置完成后CubeMX里会有一个“Layer”选项卡可以配置LTDC Layerx的窗口位置、像素格式、帧缓冲地址等。生成代码后LTDC_LAYER的帧缓冲地址默认指向一个内部RAM数组。但TouchGFX的帧缓冲地址是在TouchGFX_Config.h或者stm32h7xx_hal_msp.c里通过LCD相关的宏定义指定的两者完全是两回事。更关键的是如果CubeMX自动生成的main.c里MX_LTDC_Init()已经把Layer的FrameBufferAddress设置成了一个内部RAM数组而TouchGFX在HAL::getInstance()初始化之后会重新配置LTDC的FrameBufferAddress为TouchGFX自己的帧缓冲地址这两个地址如果不一致就会出现“白屏”或者“显示的是残影”的现象。排查方法是在TouchGFXHAL::initialize()里打个断点等初始化完成之后读一下LTDC_Layer1-CFBAR寄存器看这个地址是不是等于你在TouchGFX里配置的帧缓冲地址。如果不等于说明有代码在TouchGFX跑完之后又改回了CubeMX默认的地址。这个问题的根源是TouchGFX的HAL::endFrame()函数在每次渲染完成后会更新LTDC的帧缓冲地址到当前帧但前提是LTDC配置里启用了多个LayerTouchGFX只管理它使用的那一层。我的方案是在CubeMX里直接不用LTDC Layer的初始配置把Layer的帧缓冲地址设为0然后在TouchGFX的HAL初始化后由它自己来设置。Layer的窗口坐标X0,Y0,X1,Y1还是在CubeMX里配好否则LTDC不会输出像素时钟。其实更省事的操作是CubeMX里生成工程后把main.c里MX_LTDC_Init()中的pLayerConfig.FrameBufferAddress改成一个SDRAM地址变量比如0xC0000000确保初始状态就有效。后面TouchGFX接管后会反复修改这个地址不会影响运行。3.3 TouchGFX Designer的工程配置分辨率、像素格式和平台集成TouchGFX Designer负责UI设计、资源导出和应用代码生成。新建工程时有个“Target”设置需要选择“STM32”系列和具体的“Board”。如果你用的自定义板不在列表里随便选一个比较接近的开发板然后再手动改touchgfx_conf.h和ApplicationFont相关的配置。我这里直接选了STM32H750B-DK这个开发板虽然它用的屏幕参数和我的不一样但Designer的代码结构是通用的后面手动改几个关键宏就行。关键配置项是分辨率。Designer里如果设置了800x480生成代码的HAL初始化里就会判断屏幕尺寸但真正决定LTDC输出分辨率的是CubeMX里的LTDC配置。如果两者不一致最典型的表现就是Designer里预览正常板子上显示的画面被裁剪或者只有左上角一部分。我的做法是Designer和CubeMX都统一用800x480避免节外生枝。像素格式在Designer里的设置路径是ProjectTargetColor Depth。选RGB565还是ARGB8888这一点和前面的架构选择要保持一致。如果选错颜色会发绿、发紫或者完全错乱因为TouchGFX的Bitmap格式和帧缓冲的PixelFormat不匹配时渲染器会做不必要的颜色转换浪费CPU周期和DMA2D带宽。完成设置后Designer会生成一个generated目录里面包含fonts、images、texts、videos等资源以及核心的MVP代码框架。在CubeMX工程里需要把TouchGFX Designer生成的代码目录路径加到编译器的Include路径里并在main.c里正确初始化。需要注意每次Designer生成之后generated目录都会被覆盖如果你手动改过generated下的文件下次生成前记得备份否则改动会被清掉。有个容易忽略的点Designer生成的TouchGFXConfiguration.cpp里会#include stm32h7xx_hal.h如果CubeMX工程里没有正确配置HAL头文件的搜索路径编译会直接失败。检查方法很简单在工程里搜stm32h7xx_hal.h确认它来自Drivers/STM32H7xx_HAL_Driver/Inc。3.4 双缓冲的关键配置渲染一帧显示一帧中间不打架TouchGFX的双缓冲机制是渲染器往BackBuffer写入同时LTDC从FrontBuffer读取显示渲染完成后交换两个缓冲区的角色。这个“交换”不是物理切换内存地址而是通过修改LTDC的帧缓冲地址寄存器LTDC_Layer1-CFBAR来实现的。在TouchGFXHAL::endFrame()里会调用HAL::setFrameBuffer()来切换地址这个过程需要一个关键机制等LTDC开始扫描到垂直消隐区VBlank再切换否则画面会在切换瞬间出现撕裂tearing。TouchGFX官方方案是使用LTDC的Line中断在VBlank中断里更新CFBAR。H7系列还可以使用LTDC_LAYER_CFBAR寄存器的更新机制配合双缓冲的情况下即使不特别处理撕裂概率也比较低但要做到完全无撕裂还是建议开启LTDC_LCD_TFT的垂直消隐中断。这里有个经典的错误配置如果在CubeMX里没有开启LTDC全局中断LTDC_IRQnTouchGFX的HAL::endFrame()里的VBlank等待函数就永远不会返回表现为界面卡在第一帧或者干脆黑屏。这个坑让我排查了很久。解决方案是在CubeMX的NVIC设置里把LTDC global interrupt设为Enable同时LTDC_ER_IRQn也建议设为Enable用于处理错误中断方便排查。双缓冲的另一个配置在touchgfx_conf.h里有一个FRAME_BUFFER_SIZE宏或者类似的地方需要确保它等于一帧的大小即800*480*2 768000。如果这个值配小了运行时会出现内存越界表现随机有时候是左上角花屏有时候是程序跑飞进HardFault。4. 实操过程实录一步步把TouchGFX跑起来4.1 CubeMX时钟树配置SDRAM要稳LTDC要准时钟树的配置是整个项目的基础。H750的最高主频是480MHz但LTDC和外设的时钟和它没有直接关系需要单独配置PLL。我的配置路径是外部晶振HSE25MHzSYSCLK480MHz通过PLL1AHB分频1480MHzAPB1120MHz、APB2120MHz。PLL3用于生成LTDC和FMC的时钟PLL3的M5、N160、P2、Q8这样PLL3的Q输出25/5160/8 100MHz供SDRAM使用PLL3的P输出25/5160/2 400MHz不直接用但没关系。LTDC的时钟源选了PLL3的Q然后在RCC的LTDC Clock Divider里设置为4这样LTDC的PixelClock 100MHz / 4 25MHz实际上我最终是配置Divider8获得12.5MHzDivider4获得25MHz但25MHz超出了屏的规格书上限9MHz所以还是用了12.5MHz。这里要特别提醒CubeMX的时钟树里有几个输入框容易让人迷路尤其是“PLL3 R”和“LTDC”之间的连线鼠标悬停才能看到最终频率。一定要确认实际生成的SystemClock_Config()里RCC_PLL3_DIVQ_VALUE和LTDC Divider的值和你在图形界面里看到的一致。不同版本的CubeMX对时钟树界面的展示逻辑有细微差别但都有实时频率提示照着提示调就行。FMC这边SDRAM的时钟就是PLL3Q的100MHz。注意FMC频率不能太高否则SDRAM的建立保持时间不够表现为偶发数据错误。100MHz是W9825G6KH的规格上限为了稳妥也可以把PLL3Q调到96MHzSDRAM性能损失几乎感知不到但稳定性提升明显。我最终选择了96MHzM5, N192, Q10这样整条链路的余量更足。4.2 启动文件与链接脚本SDRAM地址怎么暴露给TouchGFXH750的SDRAM地址在FMC bank1的映射区域具体是0xC0000000到0xC7FFFFFF根据SDRAM大小和FMC Bank选择而定。TouchGFX的帧缓冲要放到这个区域链接脚本必须把这个区域暴露给C代码使用。CubeMX生成的.ld链接脚本默认只包含内部RAM的MEMORY区域SDRAM需要手动添加。我的做法是新增一个MEMORY段MEMORY { FLASH (rx) : ORIGIN 0x08000000, LENGTH 128K DTCMRAM (xrw) : ORIGIN 0x20000000, LENGTH 128K RAM_D1 (xrw) : ORIGIN 0x24000000, LENGTH 512K SDRAM (xrw) : ORIGIN 0xC0000000, LENGTH 8M }H750的Flash只有128KB但代码量可能超过这个数需要开启L1 Cache配合XIP从外部QSPI Flash执行。这个先按下不表。关键是MRAM区域并非连续的H7的内存布局比F系列复杂一定要确认地址范围没有重叠。链接脚本里定义一个SDRAM的Section或者直接用一个全局变量指向SDRAM地址__attribute__((section(.sdram))) uint8_t framebuffer[800*480*2];然后在TouchGFX_Config.h里把FRAME_BUFFER_ADDRESS指向这个变量或者直接写0xC0000000。直接写地址有个注意点链接器不会帮你检查这个地址是否已被使用如果其他变量也放在SDRAM可能会被帧缓冲覆盖。我的做法是单独把帧缓冲数组放到SDRAM区域且在Section属性里加上aw声明其余SDRAM空间留给动态分配。这里还有个隐藏坑H7的D-Cache默认是开启的但SDRAM区域如果没有配置为Cacheable尤其被DMA2D访问时CPU和DMA2D看到的数据可能不一致。后面会专门讲Cache一致性问题。4.3 移植过程中最折磨人的一步TouchGFX HAL的底层对接TouchGFX的HAL层是个大杂烩包含HAL、HALTouchGFX、TouchGFXHAL、OSWrappers这些类和文件。CubeMX生成的代码里有一个TouchGFXHAL.cpp文件它是移植的“前线”。TouchGFXHAL的初始化流程大概是先调用基类构造函数传入Display接口、帧缓冲、尺寸等信息然后在initialize()里配置LTDC、触摸、DMA2D等。最关键的是HAL::getInstance()-setFrameBufferStartAddress()这个方法告诉TouchGFX帧缓冲的起始地址。在我的工程里TouchGFXHAL::initialize()里会调用一个LCD类的初始化函数这个LCD类在touchgfx/hal/BoardConfiguration.hpp里声明具体实现在CubeMX生成的TouchGFXHAL.cpp底部。如果LCD::init()里没有正确配置LTDC Layer的窗口大小或者像素格式画面输出就会歪掉。还有一个文件叫stm32h7xx_hal_msp.c里面是HAL库的底层回调。TouchGFX生成的工程里这个文件会被CubeMX覆盖所以如果修改了其中的LTDC初始化相关代码最好在CubeMX的User Code区注释里写保证重新生成代码时能被保留。4.4 触摸芯片GT911的坐标映射触摸和显示是两条线LTDC负责显示触摸通过I2C读取坐标。GT911是电容触摸控制器通过I2C接口通信地址有两种可选0x28/0x29由INT引脚电平决定。GT911上电后需要写入配置并且要等待它输出就绪信号。坐标映射的坑在于触摸屏的X轴方向和屏幕的X轴方向可能是反的Y轴同理。TouchGFX的TouchEvent给的坐标是原始屏幕坐标如果在初始化触摸驱动时方向映射没处理点击按钮就会点不到或者点左边弹右边。GT911会返回原始触摸坐标坐标系是触摸屏的物理坐标系常见的是左上角为原点但实际上取决于屏幕安装方向。我的做法是在驱动初始化后用一个简单的测试程序点击屏幕四个角落打印TouchGFX收到的坐标确认映射关系后在BoardConfiguration.cpp里对坐标做转换uint16_t x raw_x; uint16_t y raw_y; // 如果X方向反了 x SCREEN_WIDTH - 1 - raw_x; // 如果Y方向反了 y SCREEN_HEIGHT - 1 - raw_y;这里要特别注意GT911的坐标分辨率是1024不是屏幕的800x480。需要先确认GT911的配置里X/Y输出范围是否设置为屏幕分辨率否则需要缩放。GT911的配置寄存器0x8040-0x8041是X输出最大值0x8042-0x8043是Y输出最大值。如果默认是1024那坐标需要按比例缩放uint16_t scaled_x raw_x * SCREEN_WIDTH / 1024; uint16_t scaled_y raw_y * SCREEN_HEIGHT / 1024;实际测试下来GT911有一个很头疼的特性它在上电后需要延时约100ms才能访问配置寄存器否则I2C通信会无响应。如果板子用的GPIO模拟I2C或者I2C外设时钟不够稳定还会出现配置写入失败的情况。我的建议是在触摸初始化代码里AT24Cxx之类的EEPROM写入模式吗不GT911的配置是直接写ROM但要注意的是上电后的第一个I2C事务先用一个伪读取来“唤醒”GT911然后再发送配置。4.5 DMA2D加速不要让CPU去填充像素TouchGFX默认会用DMA2D来做2D加速例如填充背景色、复制图像、混合透明度。如果DMA2D配置不对界面不仅没有加速效果反而会因为CPU等待DMA2D完成而变得更慢。DMA2D的关键配置在于它的中断必须在NVIC里启用。TouchGFX的DMA2D驱动在等待传输完成时会进入__WFI等待中断唤醒如果DMA2D中断被关闭程序会卡死在等待循环里表现为界面卡死或者刷新率极低。这个坑在H7系列上尤其隐蔽因为CubeMX默认可能不会自动勾选DMA2D中断。DMA2D工作时还会涉及一个重要的内存一致性坑DMA2D写SDRAMCPU后续要读这块区域做逻辑判断但D-Cache缓存了旧数据读出来的可能还是旧值导致界面状态判断错乱。解决方式有两类关闭帧缓冲区域的Cache把SDRAM的内存属性配置为MT_NORMAL时使用Non-Cacheable或者专门给帧缓冲区域配置MPU为Non-Cacheable。手动维护Cache一致性在DMA2D传输完成后调用SCB_CleanDCache()写回或SCB_InvalidateDCache()失效。我的做法是给帧缓冲区域配置了MPU Region属性设置为Normal、Non-Cacheable这样CPU访问帧缓冲是直接走AHB访问SDRAM和DMA2D/LTDC访问保持一致不用每次手动处理Cache。但这种配置下CPU直接读帧缓冲做像素操作的效率会明显变低因为写缓冲都被绕过了。好在这个场景大部分工作由DMA2D承担CPU直接操作帧缓冲的地方不多实际影响可接受。如果你希望帧缓冲区域保持CacheableCPU访问更快也可以但必须在每次TouchGFX渲染完成、DMA2D写完帧缓冲之后调用SCB_CleanDCache_by_Addr把帧缓冲区域的Cache写回SDRAM再让LTDC控制器读取。注意LTDC本身是通过AXI总线DMA读的走的是AXI SRAM的路径所以它不受CPU Cache的影响这也是H7的AXI SRAM设计初衷之一。但这个方案有个副作用每次帧渲染完成都要Clean整个缓冲开销不小实测和Non-Cacheable方案对比性能差距不大。所以我最终选择了Non-Cacheable方案省心。5. 常见问题与排查技巧实录5.1 白屏、黑屏、花屏从信号链路上找根因白屏是最常见的现象含义是LTDC没有输出有效的像素数据屏幕背光亮了但画面全白或者屏幕直接黑。排查顺序非常重要第一步查LTDC时钟。通过调试器确认LTDC-GCR寄存器里的LTDCEN位是否为1同时检查LTDC-CDSR寄存器里的VCLK状态确认垂直和水平同步信号是否产生。这一步能定位是不是时钟配置问题。如果LTDCEN为0多半是MX_LTDC_Init()没有被调用或者调用时参数校验失败返回错误。第二步查Layer配置。确认LTDC_Layer1-CR的LEN位为1LTDC_Layer1-WHPCR和WVPCR寄存器值是否和你配置的分辨率一致。如果Layer被禁用了LTDC主时钟依然输出但像素数据层不使能屏幕显示白屏。第三步查帧缓冲地址。在LCD初始化后的主循环里读LTDC_Layer1-CFBAR如果值为0或者指向未初始化的RAM说明帧缓冲地址没有被正确设置。花屏的情况更复杂一点如果整个画面有规律地“左右错位”术语叫“行场错位”通常是HBP/HFP参数不合适导致LTDC的行同步信号和像素数据对不上。如果花屏是无规律的色块极大可能是SDRAM数据不稳定优先排查SDRAM的时序和FMC时钟。一个快速验证方法不停填充SDRAM区域为0xFFFF然后读回校验如果某个地址偶尔不对说明SDRAM时序有问题。5.2 触摸坐标偏移校准矩阵的两种方案触摸坐标偏移的原因有三种触摸屏本身的固有偏移、坐标分辨率不匹配、安装方向不一致。GT911的坐标输出是12位的范围0-4095但配置寄存器可以设置输出范围。我配置成800x480后坐标就是屏幕上按比例直接映射的。但如果你的屏幕模块是“组合屏”——触摸屏和液晶屏不是原厂贴合而是后期通过排线连接那么触摸屏的物理坐标系和显示坐标系会存在固定的偏移和旋转。这种情况就需要做校准。TouchGFX没有内置触摸校准库但可以自己实现。最简单的校准方式是基于四点的线性变换// 假设屏幕四点物理坐标 (x1,y1)-(x4,y4) // 对应触摸点采样坐标 (tx1,ty1)-(tx4,ty4) // 解一个仿射变换矩阵四点校准比三点更准确但实现复杂度也更高。实际上很多产品只做两点校准也够用分别在屏幕左上和右下采集两个触摸点算出X轴和Y轴的缩放比例和偏移量。我之前做过一个自动校准工具用TouchGFX的CustomWidget显示一个十字光标用户点一下记录坐标重复采集对角两个点后计算出参数固化到Flash里。这个方法对量产阶段的个体差异很有效。5.3 Cache一致性导致的“幽灵Bug”Cache一致性问题最典型的场景TouchGFX渲染完成后显示画面有时候是残影有时候画面有部分区域是上一帧的内容而且没有规律。排查方法也比较直接在endFrame()里关闭D-Cache或者用MPU把帧缓冲区域设为Non-Cacheable问题消失那基本就锁定是Cache一致性问题了。如果不想全局关闭Cache可以针对帧缓冲区域单独配置MPU。H7上配置MPU的代码可以在main.c的MPU_Config()里加MPU_Region_InitTypeDef MPU_InitStruct {0}; HAL_MPU_Disable(); MPU_InitStruct.Enable MPU_REGION_ENABLE; MPU_InitStruct.BaseAddress 0xC0000000; MPU_InitStruct.Size MPU_REGION_SIZE_8MB; MPU_InitStruct.AccessPermission MPU_REGION_FULL_ACCESS; MPU_InitStruct.IsBufferable MPU_REGION_NOT_BUFFERABLE; MPU_InitStruct.IsCacheable MPU_REGION_NOT_CACHEABLE; MPU_InitStruct.IsShareable MPU_REGION_NOT_SHAREABLE; HAL_MPU_ConfigRegion(MPU_InitStruct); HAL_MPU_Enable(MPU_CONTROL_HRDZENA);注意MPU Region的Size必须覆盖整个SDRAM但其实只把帧缓冲那块配成Non-Cacheable就够了其他SDRAM继续Cacheable。实际工程中为了省事我整片SDRAM都配成Non-Cacheable代价是SDRAM上的堆操作和内存拷贝速度略低但完全够用。还有个细节帧缓冲被MPU配置为Non-Cacheable之后CPU的写操作延迟会变高对BltImage这种逐像素操作有性能影响。实测从AXI SRAM往SDRAM拷贝一帧800x480 RGB565Cacheable vs Non-Cacheable的时间差异约在1.2倍左右对60fps的全局刷新影响不大但如果你的UI有很多渐变或大量复杂绘制建议用Cacheable方案在渲染完成后统一Clean再触发LTDC刷新。5.4 刷新率上不去卡顿怎么定位TouchGFX的卡顿问题要从两个角度来拆渲染瓶颈和显示瓶颈。渲染瓶颈看的是CPU或DMA2D处理一帧需要多久显示瓶颈看的是LTDC刷新一帧需要多久。通过TouchGFX的HAL::getInstance()-getFrameTime()可以拿到上一帧的渲染耗时。如果渲染耗时接近甚至超过屏幕刷新周期比如12.5MHz像素时钟下的约35ms那界面就会掉帧。解决办法是优化图片资源格式用RGB565缩小体积、减少透明混合使用透明区域会触发DMA2D的混合操作很耗时、避免大面积的重绘。还有一个不太直观的优化点TouchGFX默认的帧率是60fps但屏幕刷新率可能只有28Hz两个指标不匹配时TouchGFX还是会按照60fps去渲染产生很多无用的帧白白消耗CPU。可以在touchgfx_conf.h里调整FRAME_RATE相关的配置比如把它降到30fps让TouchGFX渲染节奏和屏幕刷新率匹配反而会感觉更流畅。如果确认是显示瓶颈也就是屏幕刷新率太低除了调整像素时钟和LTDC时序还有一个办法是开启LTDC的ITMImmediate Transfer Mode在垂直消隐期间触发帧切换减少画面撕裂感。这个模式在TouchGFX里通常默认开启但需要确认LTDC_ITRCR的IMTRANS寄存器位是否正确。6. 最后再分享几个提升效率的实操技巧第一个技巧把TouchGFX引擎的日志输出打开。TouchGFX里有个touchgfx_enable_debug编译宏开启了之后会在串口打印帧率、内存使用等信息对定位性能问题帮助极大。量产版本记得关掉否则串口中断会频繁触发反而影响性能。第二个技巧在调试阶段把LTDC的帧缓冲地址在空闲时手动改成一个单色填充值比如全红、全绿这样可以快速确认LTDC链路是否正常。如果屏幕能稳定显示纯色说明显示通路没问题剩下的才是TouchGFX应用层的问题。这个方法在排查“白屏但背光亮”的时候特别高效。第三个技巧给SDRAM区域起个专属Section然后通过链接脚本的__attribute__((section(.sdram)))把一个大数组放在那里调试时直接看这个数组的十六进制值就能判断SDRAM读写是否正常比用内存窗口观察快得多。我当时就是靠这个数组一眼发现了SDRAM低16位数据总线上的虚焊问题——数组数据每隔16位就会出现一个固定错误模式。最后说说我个人在这项目里最深的体会TouchGFX在自定义板上跑的难度其实大部分不在TouchGFX而在你怎么把它依赖的底层环境调稳妥。时钟、SDRAM、LTDC、DMA2D、Cache任何一个环节有小瑕疵最终都会以GUI异常的形式暴露出来而且表现千奇百怪。如果能把这几个模块在裸机环境下分别验证通过再接入TouchGFX整个流程会顺很多。否则就会出现“万能的白屏”你完全不知道是哪个环节出的问题。我后来养成的习惯是第一步编译烧录裸机例程点亮屏幕第二步用裸机跑一遍SDRAM读写测试第三步再跑TouchGFX的SimpleButton例程。三步走完后面基本都是应用层的事了。