NOTES

模块 004：PS/A53 UART 运行时

入口是 `ZCU106/ps_app/nl_uart_app/src/nl_uart_app.c`。应用在 A53 bare-metal 环境中运行；默认从 UART0 收输入，并向 UART0 输出，UART1 可用时也输出。

Qwen2.5/modules/004_ps_uart_runtime.md 2026-07-13 约 5 分钟阅读

入口和状态

入口是 ZCU106/ps_app/nl_uart_app/src/nl_uart_app.c。应用在 A53 bare-metal 环境中运行；默认从 UART0 收输入，并向 UART0 输出，UART1 可用时也输出。

它维护以下内存状态：

状态	容量/类型	用途
`g_prompt_ids`	128 个 `uint32_t`	`NL_PROMPT_IDS` 保存的 token prompt。
`g_text_tokens`	512 个 `uint32_t`	`TEXT_PROMPT` 的编码结果。
`g_text_prompt`	512 字节	最近一次文本 prompt。
`g_model`	64 字节字符串	`LOAD_MODEL` 保存的模型名。
`g_runtime_bundle` / `g_runtime_encode`	tokenizer view	已打开 `Q25TOKRT` 的 section 视图。
`g_runtime_info`	image metadata	version、section 数和每类 section 的字节数。
`g_p4_runtime`	P4 stub state	model loaded、最近 token、token/text step 计数。

启动流程

sequenceDiagram
    participant Boot as A53 main
    participant Image as Q25TOKRT image
    participant UART as UART loop
    Boot->>Boot: q25_runtime_image_init
    alt 已编译 image 地址与大小
        Boot->>Image: q25_nl_tokenizer_runtime_image_open
        Image-->>Boot: bundle/encode/info 或错误码
    end
    Boot->>UART: NL_BOOT + HELP
    loop 每行输入
        UART->>UART: dispatch
        UART-->>UART: 写入协议响应
    end

流程或关系图。

Q25_NL_RUNTIME_IMAGE_ADDR 与 Q25_NL_RUNTIME_IMAGE_SIZE 是编译期宏。二者均为零时，应用进入 runtime_image=not_configured，文本命令改用 q25_byte_utf8_v1 fallback。

文本处理

命令	处理	输出字段
`TEXT_PROMPT text`	image 已打开时调用 `q25_nl_tokenizer_bundle_encode_bpe_bounded`；否则调用 `q25_tokenize_utf8_bytes`。	`TEXT_PROMPT bytes=... tokens=...` 与 `TEXT_PROMPT_IDS ...`
`TEXT_GENERATE n`	从保存的 token 开始，加入固定 `" ok"` 的 token；image 路径用 bundle detokenize，fallback 用 byte detokenize。	`TEXT_GENERATE ...` 与 `TEXT_RESULT bytes=... text=...`
`STATUS`	读取当前模型、tokenizer、文本 token 数和 image metadata。	`NL_STATUS ...`

P4 命令样板

q25_p4_runtime_cmd_stub.c 将新增命令与旧协议隔离。

命令	state 变化	响应行为
`MODEL_LOAD model=...`	`model_loaded=1`，清零计数和最后 token	报告 `tokenizer=stub tensors=stub scheduler=ps_hls_runtime_cmd_stub`。
`TOKEN_STEP token_id=... position=... context=...`	`last_token_id=token_id+1`，递增 token step 计数	返回 `token_id+1`、`logit=0`、`status=stub`。
`TEXT_STEP text` 或 `utf8_hex=...`	递增 text step 计数	统计输入字节，返回固定 `utf8_hex=6f6b text=ok`。

未接入的调用点

应用当前没有 MMIO 寄存器访问、HLS 启动、DDR tensor manifest 打开、KV cache 管理、transformer 层循环、lm_head 采样。P4 文档定义了这些未来接口的形状，但 C 代码中对应命令由样板实现处理。