企业官网建设流程全解析

#define BT_GATT_SERVICE_DEFINE(_name, ...) const struct bt_gatt_attr attr_##_name[] = { __VA_ARGS__ }; const STRUCT_SECTION_ITERABLE(bt_gatt_service_static, _name) = BT_GATT_SERVICE(attr_##_name)

struct bt_gatt_attr { const struct bt_uuid *uuid; // 属性类型 UUID uint8_t perm; // 权限（READ/WRITE/ENCRYPT...） bt_gatt_attr_read_func_t read; // 读回调 bt_gatt_attr_write_func_t write; // 写回调 void *user_data; // 属性值 uint16_t handle; // 句柄（注册时分配） };

int bt_gatt_service_register(struct bt_gatt_service *svc) { ... bt_gatt_service_init(); // 确保核心服务（GAP/GATT）已初始化 ... k_sched_lock(); err = gatt_register(svc); // ★ 真正的注册 ... sc_indicate(svc->attrs[0].handle, ...); // 发 Service Changed indication db_changed(); k_sched_unlock(); return 0; }

BT_L2CAP_CHANNEL_DEFINE(z_att_fixed_chan, BT_L2CAP_CID_ATT, bt_att_accept, NULL);

static struct bt_l2cap_chan_ops ops = { ... .recv = bt_att_recv, // att.c:3839 ← L2CAP 收到 ATT 数据就调这个 };

static int bt_att_recv(struct bt_l2cap_chan *chan, struct net_buf *buf) { struct bt_att_hdr *hdr; const struct att_handler *handler; hdr = net_buf_pull_mem(buf, sizeof(*hdr)); // 取出第一个字节 = opcode for (i = 0, handler = NULL; i < ARRAY_SIZE(handlers); i++) { if (hdr->code == handlers[i].op) { // ★ 按 opcode 查表 handler = &handlers[i]; break; } } ... err = handler->func(att_chan, buf); // ★ 调用对应处理函数 ... }

static const struct att_handler { uint8_t op; uint8_t expect_len; att_type_t type; uint8_t (*func)(struct bt_att_chan *chan, struct net_buf *buf); } handlers[] = { { BT_ATT_OP_MTU_REQ, ..., ATT_REQUEST, att_mtu_req }, { BT_ATT_OP_READ_REQ, ..., ATT_REQUEST, att_read_req }, { BT_ATT_OP_READ_BLOB_REQ, ..., ATT_REQUEST, att_read_blob_req }, { BT_ATT_OP_WRITE_REQ, ..., ATT_REQUEST, att_write_req }, { BT_ATT_OP_PREPARE_WRITE_REQ, ..., ATT_REQUEST, att_prepare_write_req }, { BT_ATT_OP_EXEC_WRITE_REQ, ..., ATT_REQUEST, att_exec_write_req }, ... };

static uint8_t att_read_req(struct bt_att_chan *chan, struct net_buf *buf) { struct bt_att_read_req *req = (void *)buf->data; uint16_t handle = sys_le16_to_cpu(req->handle); return att_read_rsp(chan, BT_ATT_OP_READ_REQ, BT_ATT_OP_READ_RSP, handle, 0); }

static uint8_t att_read_rsp(struct bt_att_chan *chan, uint8_t op, uint8_t rsp, uint16_t handle, uint16_t offset) { struct read_data data; ... bt_gatt_foreach_attr(handle, handle, read_cb, &data); // ★ 查找属性 ... }

static uint8_t read_cb(const struct bt_gatt_attr *attr, uint16_t handle, void *user_data) { struct read_data *data = user_data; />
这条链路里最值得记住的是bt_gatt_foreach_attr这个函数。它是 ATT 层和 GATT 数据库之间的唯一接口——ATT 层拿到 handle 后，不直接访问数据库结构，而是通过 foreach 加回调的方式查找。这种设计让 ATT 层和 GATT 层解耦，ATT 只管"我要这个 handle 的属性"，怎么找、找到没有，是 GATT 层的事。
七、写请求的完整链路：权限和授权多一道关
写请求的链路和读请求结构上几乎一样，但多了一道授权检查。
第一步，att_write_req（att.c:2146）从 buf 取出 handle，调att_write_rsp。注意写请求除了 handle 还带着要写的 value 和 len：
static uint8_t att_write_req(struct bt_att_chan *chan, struct net_buf *buf) { uint16_t handle = net_buf_pull_le16(buf); return att_write_rsp(chan, BT_ATT_OP_WRITE_REQ, BT_ATT_OP_WRITE_RSP, handle, 0, buf->data, buf->len); }
第二步，att_write_rsp（att.c:2091）同样调bt_gatt_foreach_attr查找属性：
static uint8_t att_write_rsp(struct bt_att_chan *chan, uint8_t req, uint8_t rsp, uint16_t handle, uint16_t offset, const void *value, uint16_t len) { struct write_data data; ... bt_gatt_foreach_attr(handle, handle, write_cb, &data); // ★ 查找属性 ... }
第三步，write_cb（att.c:2049）比read_cb多一步。先查写权限，权限不过返回BT_GATT_ITER_STOP；权限过了还要调attr_write_authorize做授权检查——这是给应用一个拦截机会，应用可以注册授权回调决定这个写操作允不允许。授权也过了，才调attr->write，也就是你注册的写回调：
static uint8_t write_cb(const struct bt_gatt_attr *attr, uint16_t handle, void *user_data) { struct write_data *data = user_data; >八、可靠写：Prepare Write + Exec Write 两步走
对于长数据或需要原子性的写，单条 Write Request 不够用——ATT 的 PDU 有长度限制，而且多个单独写中间断了会留下半成品状态。ATT 用 Prepare Write + Exec Write 两步解决这个问题。
att_prepare_write_req把数据先存进prep_pool队列（net_buf_alloc(&prep_pool, ...)，att.c:2205），并调用attr->write带BT_GATT_WRITE_FLAG_PREPARE标志让应用预检。这一步只准备不提交，数据进队列，应用可以先校验。
att_exec_write_req把队列里所有 prepared write 一次性提交，执行attr->write带BT_GATT_WRITE_FLAG_EXECUTE标志；或者全部丢弃，队列清空。这样要么全写成功，要么全不写，保证了原子性。
这个机制对应 BLE 规范里的 Reliable Writes。实际开发中，写一个需要多包才能传完的配置，或者要保证一组写操作原子生效，就用这套。框架已经帮你接好了，你只要在 write 回调里处理BT_GATT_WRITE_FLAG_PREPARE和BT_GATT_WRITE_FLAG_EXECUTE这两个标志就行。
九、主动上报：Notify 和 Indicate
前面讲的都是对端主动请求、server 被动响应。反过来，server 主动发数据给对端，用的是bt_gatt_notify和bt_gatt_indicate（在gatt.c）。
这两个函数直接构造 ATT PDU（BT_ATT_OP_NOTIFY或BT_ATT_OP_INDICATE），通过bt_att_chan_send发出去，不需要请求-响应配对。区别在于：Notify 是发了就完事，对端不确认；Indicate 需要等对端回BT_ATT_OP_CONFIRM确认，没收到会重发。
这是 GATT 数据流里唯一方向相反的路径——前面读写的方向是对端到 server，Notify 和 Indicate 是 server 到对端。应用里做心率上报、传感器数据推送，都用这两个 API。用的时候注意 CCC（Client Characteristic Configuration）描述符，对端要先写 CCC 订阅，server 才能发 Notify 或 Indicate，否则发了也没人收。
十、一张图总结 GATT 收发
把整条链路串起来看一次，以对端发 Read By Type Request 为例。
对端发 Read By Type Request，经 radio → controller →hci_acl→ host 的hci_acl()→bt_l2cap_recv()。L2CAP 按 CID=ATT 找到 att 通道，调ops.recv即bt_att_recv()。bt_att_recv查handlers[]表，命中BT_ATT_OP_READ_TYPE_REQ，调att_read_type_req()。att_read_type_req调att_read_type_rsp()，里面调bt_gatt_foreach_attr(start, end, read_type_cb, &data)。GATT 层的 foreach 遍历db链表，handle 命中后调read_type_cb()。read_type_cb调attr->read()，也就是你注册的读回调。回调返回值后，把值编码进 Read By Type Response PDU，经bt_att_chan_send_rsp()→ l2cap → controller → 空中发回对端。
这条链路把前面讲的所有环节串起来了：L2CAP 通道分发、ATT handlers 分发表、GATT foreach 查属性、属性回调。每一环都是注册-触发模型，初始化时注册好，数据到来时按表分发。你写的代码只在两端——注册时定义服务和回调，运行时在回调里处理数据，中间七八层转发协议栈全帮你接好了。
十一、动手跟读建议
想真正吃透这条链路，建议照着源码跟读一遍。
打开zephyr/samples/bluetooth/peripheral/src/main.c，看BT_GATT_SERVICE_DEFINE怎么用，这是最直观的入口。然后在gatt.h:856看宏展开，追BT_GATT_CHARACTERISTIC到BT_GATT_ATTRIBUTE，看它怎么变成两个属性。在gatt.c:1743读bt_gatt_service_register，再读gatt_register（1264），看 handle 怎么分配、db链表怎么链。在att.c:2738读handlers[]表，对照att.c:2934的bt_att_recv分发逻辑。然后跟读读请求att_read_req（1707）到att_read_rsp（1662）到read_cb（1624）到attr->read，再跟读写请求att_write_req（2177）到att_write_rsp（2123）到write_cb（2081）到attr->write。
跟读的时候重点抓三个东西：handle 在哪里分配、怎么用 handle 在db链表里查属性、权限和授权在哪一步检查。这三点搞清楚，GATT 收发的骨架就立起来了。
写在最后
GATT Server 的收发链路看起来长，拆开看就一条主线：属性在注册时进数据库分配 handle，ATT 层收到请求后用 handle 查属性，查到就调属性自带的回调。GATT 层只是数据库管理器，ATT 层才是协议处理的核心。把BT_GATT_SERVICE_DEFINE的链接器段机制、handlers[]分发表、bt_gatt_foreach_attr查属性这三点想通，后面调试任何 GATT 收发问题，都能顺着这条链路定位到是哪一环出了问题。
下一篇会展开讲编译一个 demo 程序的整个框架，看 Zephyr 的构建系统怎么把你的应用代码、协议栈、Controller、链接脚本拼成一个可烧录的固件。
如果你正在啃 Zephyr BLE 协议栈，建议照着源码行号跟读一遍这条 GATT 收发链路，从BT_GATT_SERVICE_DEFINE一直跟到attr->write，走一遍比看十遍文档都管用。
标签：#Zephyr #BLE #GATT #ATT #嵌入式开发 #NCS #nRF54L #协议栈 #蓝牙开发