• 一个简单的需求：我们希望当用户输入的提示词长度过大时，textarea 的高度能随之伸展，将所有提示词内容显示出来。

• 相关代码：

  1 2 3 4 5 6 7 8

  function adjustUI() { if (!textareaRef) { logger.error(" textareaRef is undefined, unable to reset textarea height. "); return; } textareaRef.style.height = "auto"; textareaRef.style.height = `${textareaRef.scrollHeight <= 500 ? textareaRef.scrollHeight : 500}px`; }

  • 其中，textareaRef 是通过 bind 和 textarea element 绑定在一起的：

    1 2 3 4 5

    <textarea bind:this={textareaRef} oninput={adjustUI} // ... ></textarea>

• 同时，在用户提交输入之后需要将输入框复原：

  1	textareaRef.style.height = "auto";

LLM 回复状态层

• 期初的问题是：如何在用户发送消息之后在 UI 上渲染一个 Skeleton 消息来向用户表示“正在请求回复”。

• 一开始我是直接在消息数组中插入一个假消息作为 placeholder：

  1 2 3 4 5 6

  { id: messageId, role: "assistant", timestamp: getCurrentTimestamp(), content: "Fetching response..." }

• 然后在 Chat.svelte 中判断 messages 的最后一条消息 content 是否为 “Fetching response…”，如果是，那么就将他渲染为 Placeholder 组件。

• 很显然，这是个非常丑陋的方案。我在与 ChatGPT 探讨一番后定下了一个设计：

  1 2 3 4 5

  export type LLMResponseState = { messageId: string; phase: "idle" | "pending" | "streaming" | "error"; error: string; };

• 在父组件 App.svelte 中定义一个新的 state 来追踪当前 LLM 的回复状态。这样一来，不只是等待回复中的 UI 提示便于设计，整个插件应用在用户的使用周期中的行为顺序设定也有了一个“抓手”。

flowchart TDA[idle] -->|_user submits prompt_| B[pending]B -->|user message already added \n assistantMessageId reserved \n no assistant MessageFeed yet \n `Chat.svelte` renders visual placeholder| C[streaming: first chunk]C -->| create assistant MessageFeed with reserved id \n content starts as '' \n append first chunk \n Chat now renders the real assistant message | D[streaming: more chunks]D -->|append chunk by messageId| E[idle]

• 此外，callLLM 函数中接受一个 callback 对象：

  1 2 3 4 5

  export type LLMCallback = { onStream: (chunk: string) => void; onDone: () => void; onError: (error: string) => void; };

  1. onStream 负责将流式传输获取的 chunk 填入当前接收 LLM 消息输出的 MessageFeed，再籍由 Svelte 5 提供的深度状态机制自动触发 UI 更新
  2. onDone 负责在每条消息传输完成之后将对话内容持久化，即存储到 localStorage
  3. onError 负责触发 error 信息。（ 目前还未实现错误处理的 UI ）

• 这样一来，一次请求的周期，以及各自的状态变更和相对应的流程就非常明确了。

对话内容的持久化存储

• wxt 提供了一个 storage 模块，可以操作浏览器插件的 browser.storage.local：

  1	import { storage } from "wxt/utils/storage";

• 目前插件对于用户创建对话的处理流程是：

      flowchart TD  A[no conversation] --->|user input| B[add user prompt \n **store conversation**]  B --->|stream llm message| C[stream llm message chunks into messageFeed \n **store conversation**]

• 可以看到，存储对话信息的时间在 用户消息发送之后 ，以及 LLM 消息传输完成之后 。这意味着如果用户在流式传输的过程中关闭插件侧板，将会导致流式传输中断，并且不会触发保存机制。

• 目前来说，这是预期内行为，因为我感觉将 API 请求和流式传输搬到 background.ts 实在是有些笨重。或许将来会考虑这样做。

• 值得一提的是，浏览器插件的 storage 毕竟不是数据库，并不支持 根据 sessionId 来存取对应的 Conversation 这种行为，因此笔者决定采用 Key Prefixing 的方式——直接将 sessionId 当作 key 存在 Storage 中：

  1 2 3

  export function getConversationKey(sessionId: UUID): `local:${string}` { return `local:conversation:${sessionId}`; }

• 这样一来就可以在某种程度上实现 根据 sessionId 来存取对应的 Conversation 的行为。

Streaming 消息的流式传输

• 流式传输——这是一个 LLM 应用前端的“典中典”功能，其在 OpenAI 官方提供的第三方库的帮助下，实现意外的简单。

• callback 函数中的 onStream 如下所示：

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

  /** * @param messageId the target message feed reserved for LLM response * @param chunk new arrived chunk ready for streaming * * @description update message with id `messageId` in `messageFeed` by adding `chunk` to its content */ function streamMessage(messageId: UUID, chunk: string) { const index = conversation?.messages.findIndex((m) => m.id === messageId); if (index === -1) { logger.error("target messageId does not exist: ", messageId); return; } llmResponse.phase = "streaming"; // NOTE: requires svelte 5 deep state conversation.messages[index].content += chunk; }

• 至于 callLLM 中的流式传输逻辑：

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

  // LLM API integration try { const stream = await client.chat.completions.create({ model: params.modelName, messages: completeContext, stream: true }); // update message with LLM stream response for await (const chunk of stream) { const chunkContent = chunk.choices[0]?.delta?.content || ""; if (chunkContent) params.callback.onStream(chunkContent); } params.callback.onDone(); } catch (error) { params.callback.onError(String(error)); throw error; }

  client 是一个 OpenAI 对象

• 我还真是第一次在 js/ts 中遇到这种“异步循环” for await，看了一下 MDN：

  The for await...of statement creates a loop iterating over async iterable objects as well as sync iterables. This statement can only be used in contexts where await can be used, which includes inside an async function body and in a module.

• 倘若如此的话，stream 应该是一个 async iterable object ？查看其类型，发现是 Stream<ChatCompletionChunk> & { _request_id?: string | null | undefined }。

• 翻看 OpenAI 文档 得知参数 stream ：

  stream: optional boolean
  Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a data: [DONE] message.

• 所以简而言之，client.chat.completions.create 中将 stream 参数设置为 true 即可让其返回在 resolve 后返回一个特殊的 iterable object (Stream<ChatCompletionChunk>) 的 APIPromise；对这个特殊的可迭代对象使用 for-await 循环即可渐进的取得流式传输的输出。

1
2
3
4
5
6
7
8
9
10
11
12

export class Stream<Item> implements AsyncIterable<Item> {
controller: AbortController;
#client: OpenAI | undefined;

constructor(
    private iterator: () => AsyncIterator<Item>,
    controller: AbortController,
    client?: OpenAI,
) {
    this.controller = controller;
    this.#client = client;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

export class Completions extends APIResource {
messages: MessagesAPI.Messages = new MessagesAPI.Messages(this._client);

/**
* Creates a model response for the given chat conversation. Learn more in the
* [text generation](https://platform.openai.com/docs/guides/text-generation),
* [vision](https://platform.openai.com/docs/guides/vision), and
* [audio](https://platform.openai.com/docs/guides/audio) guides.
*
* Returns a chat completion object, or a streamed sequence of chat completion
* chunk objects if the request is streamed.
*/
create(body: ChatCompletionCreateParamsNonStreaming, options?: RequestOptions): APIPromise<ChatCompletion>;
create(
    body: ChatCompletionCreateParamsStreaming,
    options?: RequestOptions,
): APIPromise<Stream<ChatCompletionChunk>>;
create(
    body: ChatCompletionCreateParamsBase,
    options?: RequestOptions,
): APIPromise<Stream<ChatCompletionChunk> | ChatCompletion>;
create(
    body: ChatCompletionCreateParams,
    options?: RequestOptions,
): APIPromise<ChatCompletion> | APIPromise<Stream<ChatCompletionChunk>> {
    return this._client.post('/chat/completions', { body, ...options, stream: body.stream ?? false }) as
    | APIPromise<ChatCompletion>
    | APIPromise<Stream<ChatCompletionChunk>>;
}

1
2
3
4
5
6
7
8
9
10
11
12
13

export interface ChatCompletionCreateParamsStreaming extends ChatCompletionCreateParamsBase {
    /**
     * If set to true, the model response data will be streamed to the client as it is
     * generated using
     * [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).
     * See the
     * [Streaming section below](https://platform.openai.com/docs/api-reference/chat/streaming)
     * for more information, along with the
     * [streaming responses](https://platform.openai.com/docs/guides/streaming-responses)
     * guide for more information on how to handle the streaming events.
     */
    stream: true;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

private parse(): Promise<WithRequestID<T>> {
    if (!this.parsedPromise) {
        this.parsedPromise = this.responsePromise.then((data) =>
            this.parseResponse(this.#client, data),
        ) as any as Promise<WithRequestID<T>>;
    }
    return this.parsedPromise;
}

override then<TResult1 = WithRequestID<T>, TResult2 = never>(
    onfulfilled?: ((value: WithRequestID<T>) => TResult1 | PromiseLike<TResult1>) | undefined | null,
    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
): Promise<TResult1 | TResult2> {
    return this.parse().then(onfulfilled, onrejected);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

/**
* API Client for interfacing with the OpenAI API.
*/
export class OpenAI {
    apiKey: string;
    organization: string | null;
    project: string | null;
    // ...

    post<Rsp>(path: string, opts?: PromiseOrValue<RequestOptions>): APIPromise<Rsp> {
        return this.methodRequest('post', path, opts);
    }

    private methodRequest<Rsp>(
        method: HTTPMethod,
        path: string,
        opts?: PromiseOrValue<RequestOptions>,
    ): APIPromise<Rsp> {
        return this.request(
            Promise.resolve(opts).then((opts) => {
                return { method, path, ...opts };
            }),
        );
    }

    request<Rsp>(
        options: PromiseOrValue<FinalRequestOptions>,
        remainingRetries: number | null = null,
    ): APIPromise<Rsp> {
        return new APIPromise(this, this.makeRequest(options, remainingRetries, undefined));
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

export class APIPromise<T> extends Promise<WithRequestID<T>> {
private parsedPromise: Promise<WithRequestID<T>> | undefined;
#client: OpenAI;
    constructor(
        client: OpenAI,
        private responsePromise: Promise<APIResponseProps>,
        private parseResponse: (
            client: OpenAI,
            props: APIResponseProps,
        ) => PromiseOrValue<WithRequestID<T>> = defaultParseResponse,
    ) {
        super((resolve) => {
            // this is maybe a bit weird but this has to be a no-op to not implicitly
            // parse the response body; instead .then, .catch, .finally are overridden
            // to parse the response
            resolve(null as any);
        });
        this.#client = client;
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

export async function defaultParseResponse<T>(
    client: OpenAI,
    props: APIResponseProps,
): Promise<WithRequestID<T>> {
    const { response, requestLogID, retryOfRequestLogID, startTime } = props;
    const body = await (async () => {
        if (props.options.stream) {
            // ...

            return Stream.fromSSEResponse(
                response,
                props.controller,
                client,
                props.options.__synthesizeEventData,
            ) as any;
        }

1
2
3
4
5
6
7
8
9
10
11
12
13

class Stream {
    constructor(iterator, controller, client) {
        this.iterator = iterator;
        // ...
    }
    static fromSSEResponse(response, controller, client, synthesizeEventData) {
        let consumed = false;
        const logger = client ? (0, log_1.loggerFor)(client) : console;
        async function* iterator() {
            // iterator implementation
        }
        return new Stream(iterator, controller, client);
    }

• 说实话，感觉这种 Stainless API 生成的 SDK 代码读起来好像并不是那么有价值。

题外话

• 说点题外话——我感觉开发/学习这个网页插件的方式和传统的方式大有不同。具体来说，我已经变的非常依赖 LLM 了。

• 尽管我自称所谓“轻度维新派”，坚持自己写代码，对于 LLM 生成的代码则每一行都自己审计并尝试理解，改正其错误或者根据 codebase 变化进行魔改。但不可否认的是，我对于许多开发过程中所需要的知识都是通过 LLM 获得的，我发现自己变的非常依赖 LLM 提供的 SOTA 技术选型/起步框架，辅助阅读源码的能力以及设计模式方面的建议。

• 倒也不是感到恐慌，能够普及的新技术自有其优势和用处，若是要依靠传统的教程 + 搜索引擎 + 论坛 + 官方技术文档的方式写插件，那怕是费老鼻子劲了。

• 但确实，这让我再次对于 LLM 介入开发的程度感觉到一种模糊的摇摆之感——在“古法编码”和“vibe coding”之间的平衡点，到底在哪里呢？

• 倘若将来这些大型科技公司因为“没有故事可讲”，“没有对得起估值的盈利方式”而无法再提供这样的 API 服务，又或者是让价格大幅上涨，限额进一步缩减，我还能以同等的效率学习/写出同等质量的代码吗？

• 查阅 wxt 相关 README

  1	pnpm i @wxt-dev/webextension-polyfill webextension-polyfill

• 以及在 wxt.config.ts 中加入：

  1 2 3 4 5

  export default defineConfig({ //... modules: ["@wxt-dev/webextension-polyfill"] //... });

• 此外，还需要 @types/webextension-polyfill 以及 @types/firefox-webext-browser 来扩展 browser 的 Firefox 成员。

  1	pnpm i -D @types/firefox-webext-browser

括号作为行开头

• 这就是 JavaScript ASI 吗，给我整笑了。

默认打开 Side Panel

Firefox

• 经测试，manifest.json 中的 sidebar_action 或者 side_panel 事实上没有任何作用。

• 也可能是 WXT 抹平了这其中的一些坑，没有细究。

• 对于 Firefox，点击扩展图标触发 listener 函数的机制和 default_popup 是 冲突 的，这意味着如果浏览器发现 manifest 中的 action 一项中存在 default_popup，那么点击扩展图标只会打开 popup 窗口而不会触发 background.ts 中挂载的 listener 函数。

• 因此，想要默认打开侧板，需要删除 entrypoints 中的 popup 来防止 wxt 自动在 manifest.json 中生成 default_popup。

  • 也可以通过一种奇怪的方式来让 WXT 忽略 popup:

    https://github.com/wxt-dev/wxt/issues/1433

• 但是不能完全删去 action，因为这样一来background.ts 就无法访问 browser.browserAction 或者 browser.action。

  https://github.com/wxt-dev/wxt/issues/669
  https://wxt.dev/guide/essentials/config/manifest.html#action-without-popup

  • 可以在 wxt.config.ts 中的 manifest 部分添加一个空的 action，如下所示：

    1 2 3 4 5 6 7 8 9

    export default defineConfig({ // ... manifest: { // ... action: {} // ... } // ... });

• 然后在 background.ts 中注册监听函数：

  1 2 3 4 5

  if (import.meta.env.MANIFEST_VERSION === 3) { browser.action.onClicked.addListener(sidePanelManager.open); } else { browser.browserAction.onClicked.addListener(sidePanelManager.open); }

Chrome

• 同样的，需要 manifest.json 中包含 action，且需要删除 popup：

  https://developer.chrome.com/docs/extensions/reference/api/sidePanel#open-action-icon

• 经测试，当 PanelBehavior 中的 openPanelOnActionClick 被设为 true 的时候，点击扩展图标同样不会触发 background.ts 中挂载的 listener 函数。

• openPanelOnActionClick 默认设置为 false，保险起见再手动设置一遍：

  1 2 3 4 5 6 7

  // Chrome specific: Disable the default declarative behavior to ensure // the onClicked event is dispatched to our listener. if (import.meta.env.CHROME && typeof chrome.sidePanel?.setPanelBehavior === "function") { chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: false }).catch((error) => { console.error("[Chrome] Error resetting panel behavior: ", error); }); }

完整代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

import { Tabs } from "webextension-polyfill";

/**
 * Defines the contract for side panel operations across different browsers.
 * This abstraction allows the rest of the extension to trigger UI components
 * without platform-specific branching.
 */
export interface SidePanelManager {
    /**
     * Toggles or opens the side panel depending on the browser's capabilities.
     * @param tab The current active tab.
     */
    open: (tab: Tabs.Tab) => Promise<void>;
}

/**
 * Chrome implementation using the MV3 sidePanel API.
 * @requires "sidePanel" permission in manifest.json
 */
async function ChromeOpenSidePanel(tab: Tabs.Tab) {
    // Ensure the API exists
    if (typeof chrome.sidePanel?.open !== "function") {
        console.error(
            "[Chrome] sidePanel.open is not available. Check 'sidePanel' permission and ensure Chrome version >= 116"
        );
        return;
    }

    // Ensure a valid `windowId`
    const windowId = tab.windowId ?? chrome.windows.WINDOW_ID_CURRENT;

    try {
        await chrome.sidePanel.open({ windowId: tab.windowId });
        console.log("[Chrome] Side panel opened via action click.");
    } catch (error) {
        console.error("[Chrome] Failed to open side panel: ", error);
    }
}

/**
 * Firefox implementation using the sidebarAction API.
 * @requires "sidebar_action" definition in manifest.json
 */
async function FirefoxOpenSidePanel(tab: Tabs.Tab) {
    try {
        await browser.sidebarAction.open();
        console.log("[Firefox] Side panel opened via action click.");
    } catch (error) {
        console.error("[Firefox] Failed to open side panel: ", error);
    }
}

const panelImpl: Record<string, SidePanelManager> = {
    chrome: { open: ChromeOpenSidePanel },
    firefox: { open: FirefoxOpenSidePanel }
};

/**
 * A platform-aware manager instance.
 * WXT optimizes this at build-time, removing the unused platform implementation.
 */
export const sidePanelManager: SidePanelManager =
    panelImpl[import.meta.env.BROWSER] ?? panelImpl["chrome"];

/**
 * Configures the extension icon to open the side panel as the default behavior.
 *
 * @description
 * This function registers a listener to the extension's action icon.
 * - **Chrome**: Triggers `chrome.sidePanel.open`. Requires `openPanelOnActionClick: false`.
 * - **Firefox**: Triggers `sidebarAction.open`.
 *
 * @architecture
 * Uses `browser.action` for MV3 and fallbacks to `browser.browserAction` for MV2 (Firefox).
 * The imperative approach is used here to allow potential pre-open side effects.
 */
export function openSidePanelAsDefault() {
    // TODO: When in need of multiple listener functions, define a main listener
    // function and call the others inside it to maintain order
    // FIXME: async function registered as callback causing problem?
    if (import.meta.env.MANIFEST_VERSION === 3) {
        browser.action.onClicked.addListener(sidePanelManager.open);
    } else {
        browser.browserAction.onClicked.addListener(sidePanelManager.open);
    }

    // Chrome specific: Disable the default declarative behavior to ensure
    // the onClicked event is dispatched to our listener.
    if (import.meta.env.CHROME && typeof chrome.sidePanel?.setPanelBehavior === "function") {
        chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: false }).catch((error) => {
            console.error("[Chrome] Error resetting panel behavior: ", error);
        });
    }
}

• 我想要一个浏览器中的“生成网页总结”侧板很久了。此前我一直使用的是 Brave 浏览器的 Leo，使用其免费的 Claude Haiku 模型用来生成网页总结，以及问答一些网页信息。

• 更换浏览器到 Zen 之后，Leo 肯定是没法用了，但是经过搜索我发现主流的两个基于 LLM 的网页总结 Harpa 和 Sider 都只支持 chromium，且都不开源。

• 我只好选用 Page Assist，本质上是一个用于使用本地 Ollma 模型的 Web UI。正如其窗口名称所言：

  Page Assist - A Web UI for Local AI Models

上下文长度问题

• 我在测试 Chat with current page 功能的时候发现，模型只能获取一部分的上下文。于是我把所有的 context 复制出来，发现其确实截断了网页内容。

• 但是我在这个插件的设置页面里找了半天也没找着任何和 context window 有关的设置选项，最后在 GitHub Issues 里通过搜索关键词 citation 找到了这样的解决方案：

  I just did workaround by increasing the limit of content size:

  RAG Settings -> Retrieval Settings -> Maximum Content Size for Full Context Mode

  Default is 7028, so I just change it to 100000 (I use mistral-large-latest in most cases).

• 也是神奇，上下文长度的设置选项会放在 RAG Settings 里？这也没有用到 embedding model 和向量数据库吧。

• 将这个设置改为 128000 后内容截断的问题立马消失了。

自定义提示词

• 说实话，我对于自定义提示词并不是很熟悉。我对于那些“定义角色，划清职责，结构化输出”的提示词说实话，是非常不信任的。倒也没有什么具体的原因，就是一种感觉有种直觉上的“莫名其妙”。

• 话虽如此，我还是希望能声明模型在这个侧栏里的需求，因此定义了如下两个 prompt：

  分析当前网页内容。

  1. 内容定性：直接指出它是深度分析、新闻快讯、营销软文还是其他类型的内容。
  2. 核心摘要：用最简短的话说明页面在讲什么，以及它的核心价值点。
  3. 定位回答：回答我的问题（如果有，没有则罗列网页内容的结构和各部分概要），并注明信息在文中的大概位置（如：开头、[XX]标题下、中部）。
  4. 诚实原则：如果内容空洞或我问的信息文中没有，请直接告知，不要润色或编造。

• 以及：

  作为一个技术文档提取工具，请执行以下操作：

  1. 技术概览：快速列出该项目的主要功能（Features）和技术栈。
  2. 精确检索：根据我的提问，寻找特定的 API、配置参数或功能描述。
  3. 位置映射：给出该信息所在的具体章节标题或路径，以便我快速定位到原文。
  4. 无则申明：如果文档中没提到我寻找的内容，直接回复“未找到相关描述”，严禁基于常识进行推测。

  要求： 仅负责信息的“提取”与“定位”，保持技术术语原样，回答要干练。

• 总的来说效果还可以，但是在后续关于某些具体信息提问的时候他居然还会按照这个流程来回答……哎哟，再说吧。

愿景

• 不得不承认，当前的方案虽然有效，但属于是一种妥协。这个插件本质上并不是“通过 LLM 帮助用户快速的、更好的浏览网页”而设计的，他本质是一个本地大模型的 Web UI，那个 Chat with current page 更像是一个附带的额外功能。

• 此外，支持 Firefox 的开源插件，我在 GitHub 和 Firefox Extension Store 里搜索了一番几乎找不到几个可用的。

• 我在想，或许我可以自己写一个？我心中对于这样的插件的预期大概有这么几个点：

  1. 总结网页，提供内容评估，标注信息来源，可以一键跳转
  2. 对于技术文档，严谨的查询 api 和文档说明，原样复述
  3. 访问文中的超链接，一并总结（可能需要限制数量）
  4. 对于懒加载内容的网页，加载过的部分予以缓存

• 这些功能感觉并不是很难做，慢慢探索一下吧。

Exception Handling/Interruption

• riscv32 uses instruction ecall for self-trapping. Once the cpu recieved an ecall instruction, it would then store the current address pointed by pc to CSR mepc and push its status(context) on to the stack, and jump to an exception handler function.

• This design is required because of privilege implementation. We want the application’s behavior to be limited, and let the OS do the ‘sensitive’ works, like file read/write or memory allocation.

• See also :

  riscv-privileged-20211203.pdf - page.37

CSR: Control and Status Register

DeepSeek: CSRs are special registers in RISC-V processors used to control and monitor the CPU’s operation. They manage system-level functions such as interrupts, exceptions, and processor modes.

• Basically, CSRs are registers which stores data related to the control and status of the CPU.

• In PA3, we would implement four CSRs for riscv32-nemu, which are:

  • mepc – Machine Exception Program Counter: Stores the address of the instruction where execution should resume after handling an exception or interrupt.
  • mcause – Machine Cause Register: Indicates the reason for an exception or interrupt.
  • mstatus – Machine Status Register: Tracks the processor’s current state, including interrupt enable bits and processor mode.
  • mtvec – Machine Trap Vector Base Address Register: Holds the base address for the exception/interruption handler.

• As we do not care about priviledge mode in PA, mstatus does not require much attention.

• Also, mtvec is set to ‘direct mode’, which means that all exceptions jump to the same address, which is function __am_asm_trap which we set its address into mtvec in Trap.S(See down below).

Trap.S

• The error handler function is registerred to CSR mtvec when initializing cte module:

  1 2 3 4 5 6 7 8 9

  bool cte_init(Context *(*handler)(Event, Context *)) { // initialize exception entry asm volatile("csrw mtvec, %0" : : "r"(__am_asm_trap)); // register event handler user_handler = handler; return true; }

• In this code snippet, function __am_asm_trap is defined in a file named Trap.S. The reason why it’s written in assembly is that it is an architecture specific script, which means that the way the emulated cpu stores and restores context varies as the architecture varies, and that requires completely differenct implementation.

• Content in Trap.S:

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

  .align 3 .globl __am_asm_trap __am_asm_trap: addi sp, sp, -CONTEXT_SIZE MAP(REGS, PUSH) csrr t0, mcause csrr t1, mstatus csrr t2, mepc STORE t0, OFFSET_CAUSE(sp) STORE t1, OFFSET_STATUS(sp) STORE t2, OFFSET_EPC(sp) # set mstatus.MPRV to pass difftest li a0, (1 << 17) or t1, t1, a0 csrw mstatus, t1 mv a0, sp jal __am_irq_handle LOAD t1, OFFSET_STATUS(sp) LOAD t2, OFFSET_EPC(sp) csrw mstatus, t1 csrw mepc, t2 MAP(REGS, POP) addi sp, sp, CONTEXT_SIZE mret

• Reading this script really cost me a lot of time, mainly due to its frequent usage of macros.

• The main behavior of this script is:

  • First store all of the data in the registers on stack
  • Set CSR registers(mcause, mstatus, mepc)
  • Jump to interruption handling function __am_irq_handle
  • After the handler function returns, restore the registers using the data previously stored on stack

System Call

• When the application need something to be done by the OS, it would invoke a ‘system call’, which is based on the exception handling/interruption mechanism mentioned above.

• See syscall.c in navy-apps:

  1 2 3 4 5 6 7 8 9 10 11 12

  intptr_t _syscall_(intptr_t type, intptr_t a0, intptr_t a1, intptr_t a2) { register intptr_t _gpr1 asm("a7") = type; register intptr_t _gpr2 asm("a0") = a0; register intptr_t _gpr3 asm("a1") = a1; register intptr_t _gpr4 asm("a2") = a2; register intptr_t ret asm("a0"); asm volatile("ecall" : "=r"(ret) : "r"(_gpr1), "r"(_gpr2), "r"(_gpr3), "r"(_gpr4)); return ret; }

  (All macros are expanded)

  • Here we can see that a system call is basically executing the ecall instruction plus passing some related data to certain registers, in order to tell the OS what the application requires it to do.

  • The registers taken by riscv32 in an exception handling process are a7, a0, a1 and a2.(Specifically, a7 register for storing system call type) After the system call is done, the return value is passed to the OS through register a0, and then returned to the user program.

The Entire Process of a System Call

• User program invokes a system call, which is by executing assemble instruction ecall.
• NEMU interpret ecall and call function isa_raise_intr
• isa_raise_intr set mepc, mcause and returns address of the handler function, which is am_irq_handle, NEMU then jump to it.
• am_irq_handle create an Event object with the exception NO stored in register a7 and pass it to user_handler(if there is one).
• After the user handler function returns, the Context object will be returned in order to restore the context.
• User program resumes.

flowchart TD    A[syscall] --> B[isa_raise_intr]    B --> C[__am_asm_trap]    C --> D[__am_irq_handle]    D --> E[user_handler]    E --> F[restore context & resume program]

Multi-elf Support for Ftrace

Implementation

• Since we already have a single-elf ftrace working, changing the variable holding the file path into a linked list would solve the problem.

_start issue

• There’s a function called _start in a linking script, located at /libs/libos/src/crt0/start.S. It is not labeled as a function and its size is default to 0.

  1 2 3 4 5 6 7

  for (size_t i = 0; i < func_table.size; i++) { FuncSym curr_func = func_table.funcs[i]; if (addr >= curr_func.value && addr < curr_func.value + curr_func.size) { return curr_func; } }

• From the code in ftrace we can see that, the jump address must fall into the range of [value, value + size). While the size of _start is defaulted to 0, ftrace can not find the corresponding symbol when the program invokes _start.

5000 Bytes == 8.0K ?

• When I was checking the size of the file being taken into fsimg, I encountered a strange thing that:

  1 2 3 4 5

  $ du -h fsimg/share/files/num 8.0K fsimg/share/files/num $ du --bytes fsimg/share/files/num 5000 fsimg/share/files/num

  • du -h shows a 8.0K file
  • du --bytes shows a 5000-byte file

• The reason is that, 5000 bytes is the actual content size of the file, while 8.0K is the disk usage of it.

• Filesystems allocate space in fixed-size blocks, often 4096 bytes(4K) each. A 5000-byte file needs two blocks (2 x 4096 = 8192 bytes), rounded to 8.0K.

sbrk Implementation

• man sbrk:

  brk() and sbrk() change the location of the program break, which defines the end of the process’s data segment (i.e., the program break is the first location after the end of the uninitialized data segment (.bss) ).
  Increasing the program break has the effect of allocating memory to the process; decreasing the break deallocates memory.
  …
  sbrk() increments the program’s data space by increment bytes. Calling sbrk() with an increment of 0 can be used to find the current location of the program break.

• We will need a symbol end to get the initial memory address of program break.

• man end:

  end: This is the first address past the end of the uninitialized data segment (also known as the BSS segment)

  • We can get the address this way:

    1 2 3 4 5 6 7 8 9 10 11 12

    #include <stdio.h> #include <stdlib.h> extern char end; /* The symbol must have some type, or "gcc -Wall" complains */ int main(void) { printf("First address past:\n"); printf(" uninitialized data (end) %10p\n", &end); exit(EXIT_SUCCESS); }

• When sbrk is invoked by lib functions, it would invoke a system call called SYS_brk, which is basically requesting the OS for increment bytes of memory section.

• As nanos-lite is now only a single-program OS, all of the free memory is allocatable to the program, so the system call handler in nanos-lite for SYS_brk would just return 0 for now.

• As for syscall.c in navy-apps, _sbrk need to maintain the program break. Specifically, it is required to update pbreak at each time it is invoked, and return the pointer to the old program break.

File System

• File system in nanos-lite is a simplified version of real-world fs. Specifically:

  • The size of each file is fixed
  • Data written into the file is not allowed to exceed its initial limit
  • The number of files is fixed, meaning that we can not create new files
  • There’s no directoy

• These design makes the implementation of file system for nanos-lite much more simpler and easier.

• The abstraction of the files is an array which contains all of the file names stored in fsimg. (file names contains the path)

• The way to achieve this is by executing the script written in Makefile along with some preset files such as stdin & stdout.

• The file list array is defined in fs.c:

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

  typedef struct { char *name; size_t size; size_t disk_offset; ReadFn read; WriteFn write; } Finfo; /* This is the information about all files in disk. */ static Finfo file_table[] __attribute__((used)) = { [FD_STDIN] = {"stdin", -1, 0, invalid_read, invalid_write}, [FD_STDOUT] = {"stdout", -1, 0, invalid_read, serial_write}, [FD_STDERR] = {"stderr", -1, 0, invalid_read, serial_write}, #include "files.h" };

  • files.h is generated by navy-apps’s Makefile:

    1 2 3 4 5 6 7 8 9 10

    $(RAMDISK): fsimg $(eval FSIMG_FILES := $(shell find -L ./fsimg -type f)) @mkdir -p $(@D) @cat $(FSIMG_FILES) > $@ @truncate -s \%512 $@ @echo "// file path, file size, offset in disk" > $(RAMDISK_H) @wc -c $(FSIMG_FILES) | grep -v 'total$$' | sed -e 's+ ./fsimg+ +' | awk -v sum=0 '{print "\x7b\x22" $$2 "\x22\x2c " $$1 "\x2c " sum "\x7d\x2c";sum += $$1}' >> $(RAMDISK_H)

• The last two element of Finfo is the ‘read’ and ‘write’ function for that specific file.

• Noted that, we treat stdin, stdout and stderr as files. This is what the statement ‘Everything is a file’ in Linux means: the system components – including hardware devices, directories, and processes – are represented as files in the filesystem.

• This design simplifies interaction with system resources because they can be accessed, read, and written using standard file operations (e.g., open, read, write).

• With a function pointer set to each file’s struct object, we would only need to call it in fs_read & fs_write.

Compound Literal Issue

• When I was implementing some SDL apis, I encountered yet another subtle issue: defining and retreating the pointer of a compound literal struct object.

• Here’s the initial code:

  1 2	if (srcrect == NULL) srcrect = &((SDL_Rect){.x = 0, .y = 0, .w = src->w, .h = src->h});

• Turns out that (SDL_Rect){...} creates a temporary SDL_Rect object inside the if block. After the if statement ends, the temporary object disappears (goes out of scope).

• As a result, srcrect now holds a dangling pointer (an invalid memory address). Undefined behavior occurs when you try to use srcrect.

• To fix this, we would need a persistent object:

  1 2 3

  SDL_Rect full_src = {.x = 0, .y = 0, .w = src->w, .h = src->h}; if (!srcrect) srcrect = &full_src;

• This way, full_src is defined in the function’s scope, so it will live until the function returns.

Pixel Value Conversion: Palette

• In PAL, the value of each pixel is 8-bit in length, and is not representing the color of that pixel. Instead, it is an index to a palette. We would need to convert that index to a 32-bit color value when rendering the rectangle.

• One thing worth mentioning is that, SDL_Color->val is not the target color value. The format of it does not match AARRGGBB, so we’ll have to manually set the bit of the pixel data:

  1 2 3 4 5 6 7 8

  for (int i = 0; i < h; i++) { for (int j = 0; j < w; j++) { uint8_t idx = read_ptr[j]; buf[i * w + j] = (colors[idx].a << 24) | (colors[idx].r << 16) | (colors[idx].g << 8) | (colors[idx].b); } read_ptr += s->pitch; }

A Way of Passing Graphic Parameter Through Standard File Operation

• In NDL, the api responsible for drawing rectangle is like this:

  1	void NDL_DrawRect(uint32_t *pixels, int x, int y, int w, int h);

• This brings up an issue: write only accept three paramters, while the first of them is the file descriptor. That means, we would need to pass four parameters to a function which could only accept two parameters.

• There’re two ways to solve this that I came up with:

  1. invoke write for each line of the rectangle
  2. write all of the empty pixels as well

• After asking Deepseek, it recommended another way of achieving this: store x and y in the first 8 bytes of pixels.

• Though the top-left corner of the image presented might be a little bit stange, the trade-off for better performance is worthy.

• The most affected application is typing-game, cuz the program would draw a rectangle for each dropping letter.

To Be Continued…