14. 快速参考卡
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Linux DMA API 快速参考卡 ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ ┃
┃ 🔧 初始化 ┃
┃ ───────────────────────────────────── ┃
┃ dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32)) ┃
┃ ┃
┃ 📦 一致性DMA (长期缓冲区) ┃
┃ ───────────────────────────────────── ┃
┃ 分配: v = dma_alloc_coherent(dev, sz, &dma, GFP_KERNEL)┃
┃ 使用: 直接读写v，设备用dma地址，无需sync ┃
┃ 释放: dma_free_coherent(dev, sz, v, dma) ┃
┃ ┃
┃ 🌊 流式DMA (临时映射) ┃
┃ ───────────────────────────────────── ┃
┃ 映射: dma = dma_map_single(dev, buf, sz, dir) ┃
┃ 检查: if (dma_mapping_error(dev, dma)) 处理错误 ┃
┃ 传输: 设备用dma地址访问数据 ┃
┃ 取消: dma_unmap_single(dev, dma, sz, dir) ┃
┃ ┃
┃ 🔄 流式DMA同步 (重用映射) ┃
┃ ───────────────────────────────────── ┃
┃ CPU取回: dma_sync_single_for_cpu(dev, dma, sz, dir) ┃
┃ CPU修改: memcpy(buf, data, sz) ┃
┃ 交给设备: dma_sync_single_for_device(dev, dma, sz, dir)┃
┃ ┃
┃ 📋 Scatter-Gather ┃
┃ ───────────────────────────────────── ┃
┃ 创建: sg_alloc_table(&sgt, n, GFP_KERNEL) ┃
┃ 设置: sg_set_buf(sg, buf, len) 对每个条目 ┃
┃ 映射: cnt = dma_map_sg(dev, sgt.sgl, n, dir) ┃
┃ 读取: sg_dma_address(sg), sg_dma_len(sg) ┃
┃ 取消: dma_unmap_sg(dev, sgt.sgl, n, dir) 用原始n! ┃
┃ 释放: sg_free_table(&sgt) ┃
┃ ┃
┃ 🏊 DMA Pool (小块分配) ┃
┃ ───────────────────────────────────── ┃
┃ 创建: pool = dma_pool_create(name, dev, sz, align, 0) ┃
┃ 分配: v = dma_pool_alloc(pool, GFP_KERNEL, &dma) ┃
┃ 归还: dma_pool_free(pool, v, dma) ┃
┃ 销毁: dma_pool_destroy(pool) ┃
┃ ┃
┃ 🚂 DMA Engine ┃
┃ ───────────────────────────────────── ┃
┃ 请求: chan = dma_request_chan(dev, "tx") ┃
┃ 配置: dmaengine_slave_config(chan, &cfg) ┃
┃ 准备: desc = dmaengine_prep_slave_single(...) ┃
┃ 回调: desc->callback = func; desc->callback_param = p ┃
┃ 提交: cookie = dmaengine_submit(desc) ┃
┃ 启动: dma_async_issue_pending(chan) ┃
┃ 等待: wait_for_completion() 或 poll is_tx_complete() ┃
┃ 释放: dma_release_channel(chan) ┃
┃ ┃
┃ ⚠️ 方向说明 ┃
┃ ───────────────────────────────────── ┃
┃ DMA_TO_DEVICE: CPU→设备 (发送) map=flush cache ┃
┃ DMA_FROM_DEVICE: 设备→CPU (接收) map=inv cache ┃
┃ DMA_BIDIRECTIONAL: 双向 map=flush+inv ┃
┃ ┃
┃ ❌ 常见错误 ┃
┃ ───────────────────────────────────── ┃
┃ 1. 栈/vmalloc缓冲区做DMA ┃
┃ 2. 忘记检查dma_mapping_error() ┃
┃ 3. map/unmap不配对（泄漏） ┃
┃ 4. DMA方向错误 ┃
┃ 5. 设备拥有期间CPU访问缓冲区 ┃
┃ 6. unmap_sg用mapped_nents而非原始nents ┃
┃ 7. DMA完成前释放缓冲区 ┃
┃ 8. coherent/streaming API混用 ┃
┃ 9. 回调中调用可睡眠函数 ┃
┃ 10.Cache Line共享问题 ┃
┃ ┃
┃ 🔍 调试工具 ┃
┃ ───────────────────────────────────── ┃
┃ CONFIG_DMA_API_DEBUG=y ┃
┃ /sys/kernel/debug/dma-api/{errors,dump} ┃
┃ ftrace: events/dma/enable ┃
┃ dynamic_debug: file spi_oled_dma.c +p ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
文件清单总结
spi_oled_dma/
├── spi_oled_dma.h # 头文件(数据结构+DMA概念注释)
├── spi_oled_dma.c # 主驱动(DMA初始化+传输+sysfs)
├── spi_oled_streaming_reuse.c # 流式DMA重用+乒乓+异步演示
├── spi_oled_dma_errors.c # DMA常见错误汇编(10个典型错误)
├── Makefile # 编译系统
├── dts/
│ └── spi_oled_overlay.dts # 设备树(含DMA通道配置说明)
├── test/
│ └── test_oled.c # 用户空间测试(图案+性能对比)
└── scripts/├── run_test.sh # 自动化测试套件(8个测试项)└── trace_dma.sh # ftrace DMA跟踪工具
