简介：面向AVR单片机开发者与嵌入式学习者整理的头文件集合，覆盖寄存器定义、I/O端口操作、程序存储区访问及看门狗等常用模块，可解决开发中头文件缺失、型号头文件不匹配和工程引用混乱的问题，适合入门配置与中高级项目移植时查阅。压缩包共307个文件，清一色为.h头文件，按芯片型号与功能模块收录ATmega、ATxmega等系列相关定义，包体约2.52MB，便于直接补入编译环境或对照现有工程查漏补缺。已有2504人学习下载，说明其在AVR开发群体中具有一定参考价值。读者可获得较完整的头文件索引，快速定位特定型号的寄存器与外设声明，减少自行查找和拼接声明的时间，也为理解avr/io.h、pgmspace.h、wdt.h等常用头文件的组织方式提供便利，适合作为本地资料库长期留存与按需检索。

1. 一套 AVR 头文件能干什么：从avr/io.h报错说起

前段时间帮人看一个从旧机器上拷过来的工程，代码本身没问题，make一跑就停在第一行：fatal error: avr/io.h: No such file or directory。打开源文件，#include <avr/io.h>下面还跟着util/delay.h、avr/interrupt.h、avr/pgmspace.h，一串全是工具链自带的头文件。工程里没有这些东西，是因为它们本来就该由avr-libc提供；可一旦换了编译环境、或者干脆想脱离 IDE 手动编译，这层依赖就成了关键。这份资源包解决的就是这个问题：把 AVR 系列各器件的寄存器定义头文件、avr/核心头、util/工具头完整摆出来，avr/io.h里那套avr/io.h→iom328p.h的分发链路可以直接读、直接改。适合两类人：一类是要在没有现成工具链的机器上把 AVR 工程编出来的人，另一类是想搞清楚PORTB这个宏到底展开成什么、寄存器地址从哪来的嵌入式新手。

2. 目录结构拆解：从avr/io.h一路找到iom328p.h

拿到一堆.h文件，最容易犯的错是把它当成“头文件大礼包”，一股脑塞进工程目录然后#include "io.h"，编译能过但行为诡异。这套头文件是有严格层级和命名约定的，先看懂摆放方式，后面所有问题都好办。

2.1 顶层分两棵树：include/avr和include/util

标准布局下，所有文件挂在一个include根目录下，分成两个子目录。avr/放的是器件相关和内核相关的定义，util/放的是与具体器件无关的工具宏。两者的区别在于：avr/下的文件用<>包含，是工具链级别的公共资源；util/下的文件虽然也用<>，但内容更偏“语法糖”，依赖编译器内建函数。

这张表不是让人背，而是让人形成条件反射：写代码时#include报错，先判断缺的是哪一类，再决定是补文件还是改-mmcu。

2.2 分发机制：-mmcu怎么变成iom328p.h

avr/io.h本身几乎没有寄存器内容，它是个纯粹的“选择器”。编译器在命令行被指定-mmcu=atmega328p之后，会预定义一个__AVR_ATmega328P__宏（不同工具链版本对大小写和下划线的处理略有差异，有的版本额外给一个__AVR_DEVICE_NAME__），io.h就靠这一长串条件判断把对应型号的文件拉进来。简化后的骨架如下：

/* avr/io.h 的分发骨架（简化，省略了上百个器件分支） */ #ifndef _AVR_IO_H_ #define _AVR_IO_H_ #include <avr/sfr_defs.h> /* 先拿到 _SFR_IO8 / _SFR_MEM8 这一层 */ #if defined(__AVR_ATmega8__) # include <avr/iom8.h> #elif defined(__AVR_ATmega328P__) # include <avr/iom328p.h> #elif defined(__AVR_ATmega2560__) # include <avr/iom2560.h> #elif defined(__AVR_ATtiny85__) # include <avr/iotn85.h> /* ... 其余型号一家一个分支 ... */ #else # error "device type not defined" #endif #endif /* _AVR_IO_H_ */

这段代码里有个关键点值得注意：#include <avr/sfr_defs.h>必须排在器件头文件之前，因为iom328p.h里所有寄存器宏都依赖_SFR_IO8和_SFR_MEM8。如果有人为了“精简”把头文件拆散、只拷贝iom328p.h到工程目录，编译时就会在#define PORTB _SFR_IO8(0x05)这一行报_SFR_IO8未定义——这不是缺少寄存器定义，而是缺了底层宏定义。

另一个易忽略的细节是#error "device type not defined"这个分支。它存在意味着：只要-mmcu写错、或者压根没写，编译不会静默通过，而是直接停下来。反过来，一旦看到这个报错，就不要去翻io.h的内容，直接检查命令行和 Makefile 里的MCU变量。

2.3 一个寄存器的三层定义

同一颗引脚在头文件里会出现三种形态，理解这三层，后面读任何型号的头文件都不迷路。以 ATmega328P 的PORTB为例：

• 第一层是地址宏：#define PORTB _SFR_IO8(0x05)，0x05是 I/O 地址，不是内存地址，中间还差一个__SFR_OFFSET（通常为0x20）。
• 第二层是位号宏：#define PB0 0一直到PB7 7，这些是纯数字，用来配合_BV()做位移。
• 第三层是复合位名宏：#define PORTB0 0，部分型号还提供#define DDB0 0之类的别名，方便从数据手册原样抄代码。

多数人写代码只用到第一层和_BV()的组合，但在维护别人代码时，经常会遇到直接写裸地址*(volatile uint8_t*)0x25 = 0xFF的老代码，这时候能不能快速换算成PORTB对应的值，就决定了调试速度。

3. 核心头文件逐个拆：宏展开、向量表和 Flash 访问

结构看完，进入真正写代码时天天碰到的那几个文件。这一层搞清楚了，很多“玄学”问题会自动消失——比如为什么_delay_ms(1000)在 8MHz 下变成一瞬间、为什么ISR()里改了全局变量主循环看不到。

3.1sfr_defs.h：_SFR_IO8和_BV到底展开成什么

这个文件只有一百多行，却是整套头文件的地基。核心宏不过五六个，但每一个都直接对应一条 AVR 指令或者一种寻址方式：

/* avr/sfr_defs.h 中的关键宏（保留语义，略去条件编译） */ #include <avr/portpins.h> /* PB0..PB7 之类的位号 */ #define __SFR_OFFSET 0x20 /* I/O 空间到数据空间的偏移 */ #define _MMIO_BYTE(mem_addr) (*(volatile uint8_t *)(mem_addr)) #define _SFR_MEM8(mem_addr) _MMIO_BYTE(mem_addr) #define _SFR_IO8(io_addr) _MMIO_BYTE((io_addr) + __SFR_OFFSET) #define _BV(bit) (1 << (bit)) #define bit_is_set(sfr, bit) (_SFR_BYTE(sfr) & _BV(bit)) #define bit_is_clear(sfr, bit) (!(_SFR_BYTE(sfr) & _BV(bit))) #define loop_until_bit_is_set(sfr, bit) do { } while (bit_is_clear(sfr, bit)) #define loop_until_bit_is_clear(sfr, bit) do { } while (bit_is_set(sfr, bit))

_MMIO_BYTE是整条链的终点：把一个整数地址强转成volatile uint8_t *再解引用。volatile必须在这里出现，否则编译器在-O2下会把“连续写三次同一个寄存器”优化成一次，而硬件外设恰恰依赖写入次数。

_SFR_IO8和_SFR_MEM8的区别不只是地址范围。AVR 的IN/OUT指令可以单周期访问0x00–0x1F这段 I/O 空间，所以对PORTB这类寄存器使用_SFR_IO8(0x05)，编译器有机会生成OUT指令；而_SFR_MEM8(0x100)只能走STS/LDS，多一个周期。用avr-gcc -E展开就能看到实际地址：

# 让编译器只做预处理，看 PORTB 最终展开成什么 echo '#include <avr/io.h> PORTB = 0xFF;' | avr-gcc -mmcu=atmega328p -E -P -x c - # 典型输出： (*(volatile uint8_t *)((0x05) + 0x20)) = 0xFF;

看到0x05 + 0x20 = 0x25，就和数据手册里“PORTB 的 I/O 地址 0x05、数据地址 0x25”对上了。这一步验证很有价值，尤其是在怀疑头文件和芯片型号不匹配的时候。

3.2iom328p.h：从PORTB到中断向量号

型号头文件的内容大致分三块：寄存器地址宏、位号宏、中断向量号宏。前两块前面已经讲过，第三块在写中断时最关键：

/* avr/iom328p.h 中的片段（节选） */ #define PORTB _SFR_IO8(0x05) #define DDRB _SFR_IO8(0x04) #define PINB _SFR_IO8(0x03) #define PB0 0 #define PB5 5 /* 中断向量号 */ #define INT0_vect_num 1 #define INT1_vect_num 2 #define PCINT0_vect_num 3 #define USART_RX_vect_num 19 #define USART_UDRE_vect_num 20 #define _VECTOR(N) __vector_ ## N #define INT0_vect _VECTOR(1) #define USART_RX_vect _VECTOR(19)

_VECTOR(19)会被拼成__vector_19，这是编译器认识的固定符号名。ISR(USART_RX_vect)展开后就是定义__vector_19这个函数，链接器再把中断向量表里第 19 项指向它。所以如果两个源文件都写了ISR(USART_RX_vect)，链接时就会报重复定义——报错的符号名是__vector_19，而报错位置在interrupt.h里，第一次见到很容易懵。

同样的道理，如果换了一颗片子和头文件不匹配，向量号会整体错位。表现是中断能进，但进的不是你以为的那个函数，比如明明发的是串口数据，却跑进了定时器中断。这种问题单看代码永远找不到，必须先确认-mmcu和设备型号。

3.3interrupt.h：ISR()背后做了什么

avr/interrupt.h里最常用的是三个东西：sei()、cli()和ISR()。前两个是SREG第 7 位的置位和清零，可以用内联汇编，也可以让编译器生成SEI/CLI指令：

#include <avr/io.h> #include <avr/interrupt.h> static volatile uint8_t rx_flag = 0; static volatile uint8_t rx_data = 0; /* 串口接收完成中断：注意函数不能有返回值，不能带参数 */ ISR(USART_RX_vect) { rx_data = UDR0; /* 读数据寄存器会同时清 RXC 标志 */ rx_flag = 1; } int main(void) { UBRR0L = 16; /* 16MHz / 16 / 57600 - 1，实际值按 F_CPU 算 */ UCSR0B = _BV(RXEN0) | _BV(TXEN0) | _BV(RXCIE0); UCSR0C = _BV(UCSZ01) | _BV(UCSZ00); /* 8 位数据，1 位停止 */ sei(); /* 全局中断使能，写在初始化之后 */ while (1) { if (rx_flag) { rx_flag = 0; /* 主循环处理，不与中断抢时间 */ } } }

这里有几个必须说清的点。ISR()展开后会给函数加上__attribute__((signal))（旧版本是interrupt），编译器据此在函数出入口自动保存和恢复被用到的寄存器，并在末尾生成RETI而不是RET。所以不要自己手写reti()，也不要给 ISR 加return值。

其次是rx_data和rx_flag必须加volatile。主循环里if (rx_flag)如果没加volatile，编译器在-O1以上会认为这个变量在循环中不会被改变，直接优化成死循环或者干脆读一次寄存器缓存下来——现象就是“串口能收，但主循环毫无反应”，这类问题排查起来非常费时间。

最后是sei()的位置。放在外设初始化之前，有可能在配置还没完成时就进中断，读到半初始化的状态；放在之后更稳妥。如果确实需要在临界区里操作多字节变量，用util/atomic.h的ATOMIC_BLOCK(ATOMIC_RESTORESTATE)包起来，它会保存并恢复SREG，比手动cli()/sei()安全，因为不会把原本就已经关着的中断状态强行打开。

3.4pgmspace.h、eeprom.h与util/delay.h：三类最常用的扩展

avr/pgmspace.h解决的是 RAM 不够用的问题。AVR 是哈佛架构，Flash 和 RAM 地址空间分开，普通const数组在 C 里仍然可能占用 RAM（取决于编译器版本和-mrelax等选项），要真正放进 Flash 必须显式标注：

#include <avr/io.h> #include <avr/pgmspace.h> /* PROGMEM 把表放进 Flash，运行时不能用普通下标访问 */ const uint8_t font_table[] PROGMEM = { 0x3F, 0x06, 0x5B, 0x4F, 0x66 }; /* 字符串同理，PSTR 会顺带做类型转换 */ const char msg[] PROGMEM = "boot ok"; void show_char(uint8_t idx) { uint8_t seg = pgm_read_byte(&font_table[idx]); /* 必须走 pgm_read_* */ PORTD = seg; }

参数说明：pgm_read_byte(addr)的入参是 Flash 空间地址，返回一个字节；同族还有pgm_read_word、pgm_read_dword、pgm_read_float，以及memcpy_P、strlen_P、strcmp_P这类带_P后缀的字符串函数。最容易出错的是对PROGMEM数组直接写font_table[0]，编译不报错，运行读到的是 RAM 里那块地址的内容，通常全是 0。

avr/eeprom.h的关键是EEMEM段属性和eeprom_update_*系列函数。eeprom_write_byte无论值是否相同都会写一次，擦写寿命有限；eeprom_update_byte会先读再比，只在变化时写，实际项目里优先用它：

#include <avr/eeprom.h> uint16_t EEMEM saved_counter = 0; /* 链接器分配到 EEPROM 空间 */ void save(uint16_t v) { eeprom_update_word(&saved_counter, v); /* 内部先读后写，省擦写次数 */ } uint16_t load(void) { return eeprom_read_word(&saved_counter); }

util/delay.h的坑最集中。_delay_ms依赖F_CPU宏，且要求参数是编译期常量（__builtin_constant_p检查不过会报错），同时有上限：在默认实现里单次最大约 262 毫秒（对应F_CPU较小时），超过会被截断或告警。所以_delay_ms(1000)是个典型翻车写法，正确做法是循环调用，或者干脆改用定时器。

4. 把工程跑起来：最小 Makefile、Blink 与串口回环

头文件看得再明白，不编一次都是纸上谈兵。这一章给一套能直接抄的最小工程，命令逐条解释，跑通之后再回头改。

4.1 最小工程骨架与编译命令

目录就三个文件：main.c、Makefile，加上这套头文件所在的include目录。

# 目录约定 # project/ # ├── main.c # ├── Makefile # └── include/avr/*.h include/util/*.h <- 资源包里的头文件 # 单条命令编译，先确认工具链本身没问题 avr-gcc -mmcu=atmega328p -DF_CPU=16000000UL -Os -std=gnu99 \ -I./include -o main.elf main.c # 生成 hex，供烧录器使用 avr-objcopy -O ihex -R .eeprom main.elf main.hex # 看资源占用，确认没有把 Flash 撑爆 avr-size --mcu=atmega328p --format=avr main.elf

参数逐个说明：-mmcu=atmega328p决定__AVR_ATmega328P__是否被定义，进而决定io.h选哪个型号头；-DF_CPU=16000000UL是给util/delay.h和util/setbaud.h用的，漏了会直接编译失败；-Os在 AVR 上几乎必选，因为默认-O0生成的代码体积能大出三四倍；-I./include指向这套头文件，如果有系统级avr-libc，这一行可以省掉。

avr-size的输出分三栏：Program（Flash）、Data（RAM 静态占用）、EEPROM。新手常忽略Data，直到某天数组加着加着程序就跑飞了——AVR 的 RAM 只有 2KB 量级，栈空间就压在静态数据上面，Data逼近上限时表现是“函数调用着调用着就复位了”，非常隐蔽。

4.2 Blink：寄存器直写版本

先不引入任何封装，直接用寄存器点亮 LED，目的是验证头文件和芯片对得上：

#include <avr/io.h> #include <util/delay.h> int main(void) { /* DDRB 的第 5 位置 1，把 PB5 配成输出 */ DDRB |= _BV(PB5); while (1) { PORTB |= _BV(PB5); /* 输出高电平 */ _delay_ms(500); PORTB &= ~_BV(PB5); /* 输出低电平 */ _delay_ms(500); } }

DDRB |= _BV(PB5)这一行的读写改三步，编译器会生成SBI（置位 I/O 寄存器某一位）或者读改写序列，取决于优化等级。PORTB &= ~_BV(PB5)里的取反是在编译期算好的常量，运行时不额外消耗指令。如果换成PORTB = _BV(PB5)，那就把其余 7 位全清零了，同端口上的其他引脚会一起被拉低——这种写法在只用一个引脚时看不出问题，等到第二路输出接上去就开始出问题。

编译烧录后如果灯闪的频率明显不对，第一检查F_CPU是否和实际晶振一致，第二检查熔丝位里时钟源选的是内部 RC 还是外部晶振。_delay_ms本身没有错，错的是它相信了F_CPU。

4.3 串口回环：中断接收加主循环回发

Blink 只验证了输出，接下来验证中断和串口，这段代码基本能覆盖interrupt.h、sfr_defs.h和io.h三者的协作：

#include <avr/io.h> #include <avr/interrupt.h> #include <util/atomic.h> #define BAUD 9600 #include <util/setbaud.h> /* 用 UBRR_VALUE / UBRRHI_VALUE 自动算好分频 */ static volatile uint8_t buf[32]; static volatile uint8_t head = 0; ISR(USART_RX_vect) { buf[head++ & 0x1F] = UDR0; /* 环形缓冲，掩码保证下标不越界 */ } int main(void) { UBRR0H = UBRRH_VALUE; UBRR0L = UBRRL_VALUE; UCSR0B = _BV(RXEN0) | _BV(TXEN0) | _BV(RXCIE0); UCSR0C = _BV(UCSZ01) | _BV(UCSZ00); DDRB |= _BV(PB5); sei(); for (;;) { uint8_t n; ATOMIC_BLOCK(ATOMIC_RESTORESTATE) { /* 读 head 时不能被打断 */ n = head; } while (n) { while (!(UCSR0A & _BV(UDRE0))) { } /* 等发送寄存器空 */ UDR0 = buf[--n & 0x1F]; } } }

99util/setbaud.h会根据F_CPU和BAUD算出UBRR_VALUE，同时给出UBRRHI_VALUE表示是否需要写高字节。如果只写了UBRR0L而波特率较高、分频值超过 255，实际波特率会错得离谱，现象是“能收到但全是乱码”。

ATOMIC_BLOCK这里包住的其实只有一次字节读取，因为head是uint8_t，单字节读写在 AVR 上是原子的。真正需要保护的是 16 位变量：比如在主循环里读uint16_t计数器，读高字节时被中断打断、中断里又更新了低字节，就会拼出一个不存在的值。这种错误概率低、复现难，属于典型的需要靠习惯预防的问题。

4.4 验证：反汇编看指令，avr-size看资源

代码跑起来只是第一步，确认编译器真的按预期生成了指令，才能建立信任。常用两条命令：

# 反汇编，查看 PORTB 赋值被编译成什么指令 avr-objdump -d main.elf | grep -A3 -B3 "0x25" # 导出预处理后的完整源码，检查头文件展开结果 avr-gcc -mmcu=atmega328p -DF_CPU=16000000UL -I./include -E main.c -o main.i

反汇编里如果看到sbi 0x04, 0x05（对DDRB的PB5置位）和out 0x05, r24这类指令，说明_SFR_IO8走的确实是 I/O 空间寻址，编译器正确识别了地址范围。如果看到的是sts 0x0025，那说明这个寄存器被当成了数据空间访问——一般出现在用了_SFR_MEM8或者头文件把地址写错的情况下。

-E导出的main.i会非常长，但值得搜一下自己关心的寄存器。搜PORTB能看到它被展开成(*(volatile uint8_t *)((0x05) + 0x20))，搜ISR能看到__vector_19的函数定义。这一步做几次之后，再看任何型号的头文件都不会觉得陌生。

5. 避坑与排查：五类现场问题对照表

这一章把实际调试中遇到频率最高的五类问题集中列出，每条按“现象 → 原因 → 解决”走一遍。

5.1 编译期问题：找不到头文件、重复定义

现象一：fatal error: avr/io.h: No such file or directory。 原因：编译命令里没有-I指向这套头文件，或者系统里压根没装对应的库。 解决：加上-I./include；如果头文件是拷进工程目录的，注意包含路径要指向include的父目录，而不是include/avr本身，否则#include <avr/io.h>会去找include/avr/avr/io.h。

现象二：multiple definition of '__vector_19'。 原因：两个源文件写了同一个ISR(USART_RX_vect)，或者中断服务函数被写在了头文件里、被多个.c包含。 解决：中断服务函数只放在一个.c里；头文件里只放声明，不放定义。

5.2 运行期问题：寄存器写了没反应

现象：PORTB赋值后引脚电平不变，或者只在第一次赋值时生效。 原因：一是DDRB没配对，引脚还在输入状态；二是寄存器指针没加volatile，被编译器优化掉了。 解决：先确认方向寄存器；再检查是不是自己包了一层宏把volatile丢了。用-E展开看最终表达式里有没有volatile。

现象：_delay_ms(1000)实际只有很短的延时。 原因：F_CPU定义了但和真实晶振不符，或者单次延时超过了库函数的实现上限。 解决：核对-DF_CPU；把长延时拆成循环，改用定时器更稳。

5.3 中断相关问题：能进中断但行为不对

现象：中断里改的全局变量，主循环读不到。 原因：全局变量没加volatile，主循环那段被优化成了死循环。 解决：中断和主循环共享的变量一律加volatile，并在主循环里用ATOMIC_BLOCK保护 16 位以上的读写。

现象：中断进得去但进错了函数。 原因：-mmcu指定的型号和实际芯片不一致，iomXXX.h里的向量号整体偏移。 解决：先编译一个只翻转引脚的空程序，确认基本功能正常，再排查中断。

5.4 型号不匹配与地址对不上

现象：同一个寄存器的读写正常，但某个外设完全没反应。 原因：iom328p.h这类头文件里，不同封装的同型号芯片外设数量可能不同，也有把_SFR_MEM8和_SFR_IO8混用的情况。 解决：打开对应的iomXXX.h，找到该寄存器的定义，和数据手册里的地址表逐项对照；0x20这个偏移量是最常见的差异来源。

6. 二次开发：给新器件补头文件与封装板级定义

真到了项目里，往往会遇到两种改造需求：手上这颗芯片在avr/io.h的分支里找不到，或者想把一堆寄存器操作封装成板级 API。第一种情况不要硬改io.h的主体结构，正确做法是照着现有文件写一个新的iomXXXX.h，把寄存器地址、位号、向量号三段填齐，然后在io.h的分支链里加一行#elif。写完先跑avr-gcc -E展开，确认每个_SFR_IO8的地址和数据手册对得上，再上板子。

第二种情况建议单独建一个board.h，只做三件事：给引脚起业务名字、定义方向寄存器掩码、把常用组合操作写成static inline。关键在于static inline而不是宏，既能保持零开销，又能在调试时看到符号名。

验证方法很简单：准备一个只做引脚翻转的最小程序，加上-Wall -Wextra编译一遍，看有没有未定义宏和类型不匹配的告警；再avr-objdump -d确认翻转那几行生成的是sbi/cbi而不是一串读改写。如果封装层级深，还可以把预处理结果导出来，用肉眼顺着board.h里的宏一路追到最终的地址表达式。

有个细节我吃过亏：往工程里拷头文件时把avr/version.h一起拷了过去，结果和工具链自带的版本冲突，编译期检查版本号的宏直接报错。从那以后我每次把新头文件并进工程，都会先跑一遍预处理、再全量编译、最后上板验证，三步缺一不可。希望帮到你。

本文还有配套的精品资源，点击获取