Wu Yuwei

Can we use Wasmtime to build web script engine?

2025-07-09T16:55:00+08:00

A few years ago, there was a discussion around Servo community about using alternative Javascript engine instead of SpiderMonkey. While Servo has a solid bindings to SpiderMonkey, we have to deal with several issues along with it. Servo creates its own fork called mozjs with patches it needs. At that time, people were wondering if there could be a better option. Or, even better, to see if Servo can make script engine pluggable and switch to others like V8. But in the end, we stick to existing choice and keep maintaining mozjs.

For me, I had a wilder idea in my mind back then: What if we could use a Webassembly runtime directly to build a script engine? I know mojarity of browsers can load Webassembly modules already. However, they can't access to most DOM objects and WebAPIs directly. You will need to add bindings to Webassembly modules to actually obtain those features. What if there's a script engine built on top of Webassembly directly? This way, all languages could be the first class citizen when using Web browsers!

Unfortunately, at that time, I found out Webassembly hasn't completed the spec of GC yet. It is necessary for building DOM node tree due to its design nature. DOM objects can reference each other pretty easily. It's pretty common to see a node link to its child, while its child link to its parent. So we must have a garbage collector that can trace these objects. So eventually, I kept the idea for future me to worry.

And a couple of weeks ago, I found that Wasmtime has completed the Wasm GC support already! So I believe it's time to explore this idea again. In this post, I'll share my current progress, explain possible design, and what's next for future roadmap.

DOM `Object`s in Wasm GC

If you want to understand Wasmtime's GC types in details, Their RFC repository has a whole page to explain them exhaustively. What we want to know here is what will the definition of DOM object look like when using these GC types. And the choice is its reference types, more precisely, ExternRef type. The usage of ExternRef is pretty straight forward. We call the new method with provided value and we will get Rooted<ExternRef>. The only problem is the type annotation will be eliminated upon ExternRef creation. You can see this type doesn't hold any generic. So in my attempt, I create a new type for it to contain the type information along with several utility methods:

#[derive(Copy, Debug)]
pub struct Object<T: 'static + Any + Send + Sync> {
    object: Rooted<ExternRef>,
    _phantom: PhantomData<T>,
}

Note that we can still access Rooted<ExternRef> through dereference. But this type helps us understand underlying implementation when defining new DOM objects. We will see more examples with it in later section of the post.

Reflector in Wasm Component

Before we can dive deeper into DOM object implementation details, we need to determine how reflector in Wasm works. When a browser creates a DOM object, it needs a reflector object that can be used in script side. For Servo, you can read its script crate's documentation to understand how Servo uses SpiderMonkey's types to achieve it. For Wasm, each language usually provide codegen or binding libraries to help us instantiate the Wasm module. Take Rust's wasm-bindgen as an example. When we build a wasm module through wasm-bindgen, it will also generate Javascript/Typescript bindings script to instantiage the module. But there's a major issue, these binding codes can vary between different libraries. And this kind of defeat the purpose to make every language as first class citizen of the script engine. We can't just choose certain framework to define the reflector bindings.

Fortunately, this seems to be what WebAssembly community faces as well, and they propose another concept called Wasm Component Model. You can think it's like another kind of Wasm module, but it has a pre-defined set called WIT(Wasm Interface Type). Let's say we want to define Document WebIDL interface. We can define it through resource type. This is a type that only exposes behaviour through methods. We can think it as a object that implement an interface. To define Document in resource type, it can be listed as following:

interface node {
    resource node {
        append-child: func(child: node) -> node;
    }

    resource document {
        constructor();
        url: func() -> string;
        document-element: func() -> option<element>;
    }

    resource element {
        has-attributes: func() -> bool;
    }
}

Since this is for demo purpose, I won't explain all concepts of WIT and every steps on how to use it. Instead, I'll only list out the necessary methods that could explain our proof of concept. In this example, we define resources node, document and element. They are corresponding to Node, Document and Element as DOM objects. I would like to showcase that once we get a document, we can use it to call several methods, including methods that can get another DOM objects linked to it. The document-element will return option<element> which element is another resource represent as another DOM object. Next, we will demonstrate how to implement the detail in Host side, and then use it in the script side. Or in Wasm's term, script side is usually called Guest side.

Implement Resources in Host Side

To get the bindings from the host side, Wasmtime provides bindgen! macro to generate the code based on provided WIT files. What we care the most is what are the exact type of each resource we will define. Let's we already have a few types called Node, Document, Element (We will further explain their details later). They can be specified in the macro as following:

wasmtime::component::bindgen!({
    path: "wit",
    with: {
        "ohim:dom/node/node": Node,
        "ohim:dom/node/document": Document,
        "ohim:dom/node/element": Element,
    },
    trappable_imports: true,
});

"ohim:dom/node/node" is the full path to node resource we defined in WIT file. In the bindgen macro, we specify the exact implementation type of document is Document. And then the macro will generate a HostDocument trait with all related method defined. Our job is to fulfill all these resource traits. Now, it's time to see what's inside of the DOM objects and how do we implement to those resource traits.

`Node` and `NodeImpl`

As we mentioned above, we intend to use Object<T> to define DOM Object. For Node type, it will basically be a new type of Object<T> with NodeImpl as the actual data:

pub struct Node(Object<NodeImpl>);

pub struct NodeImpl {
    event_target: EventTarget,
    parent_node: Option<Node>,
    first_child: Option<Node>,
    last_child: Option<Node>,
    next_sibling: Option<Node>,
    pub(crate) data: NodeTypeData,
}

Let's focus on fields related to Node and itself first. Node is a GC object which can be created by Object::new. And this method is essentially a ExterRef::new. All the implement details are in NodeImpl. Node will become an opaque GC rooted reference to the public, so users can have confident to link it to anywhere without worrying circular reference. You can see NodeImpl's node fields like parent_node would take a Option<Node>. When we implement the methods, we just need to get the NodeImpl data from one Node and link the other one to it.

Inherent `Node`

Next, let's talk about inherence. We know Document and Element need to inherent Node, but neither Rust nor Wasm component have builtin support to it. I've thought about similar casting mechanism like Servo did based on SpiderMonkey. However, it resolves with tons of unsafe usage and it still bothers us when we need to implement some complicated types in script crate. Wasmtime already provide pretty safe and ergonomic APIs to use. I feel like we should chase for same direction as well. So I decided to make types who inherent ancestor type as a sum type which is the NodeTypeData listed in NodeImpl's definition:

pub enum NodeTypeData {
    /// `ELEMENT_NODE`
    Element(ElementImpl),
    /// `DOCUMENT_NODE`
    Document(DocumentImpl),
    /// Similar to `Option::None`.
    None,
}

With From trait implements to related DOM Object new types and methods that are exclusive to these types to get the deeper Impl types, it should be possible for a DOM Object casts to correct type and use the right implementation data.

Implement resource traits

Now we have explained the definition of DOM Objects and their implementation details. It's time to implement to resource traits generated from bindgen!, so the Guest script side can actually use these types. Let's use HostDocument to demonstrate because it can showcase how to implement the constructor and also showcase how to link an object to the other:

/// `Store` states to use when `[Exposed=Window]`
pub struct WindowStates {
    table: ResourceTable,
    ctx: WasiCtx,
    store: Store<()>,
}

impl HostDocument for WindowStates {
    fn new(&mut self) -> Result<Resource<Document>> {
        // This is only for demo purpose
        let element = Element::new(&mut self.store)?;
        let document = Document::new(&mut self.store)?;
        document
            .data_mut(&mut self.store)
            .as_document_mut()
            .document_element = Some(element);

        Ok(self.table.push(document)?)
    }

    fn drop(&mut self, rep: Resource<Document>) -> Result<()> {
        self.table.delete(rep)?;
        Ok(())
    }
    // ...other methods
}

To implement traits, we need to define a state data that can put into Wasmtime's Store. I found this is perfect match to WebIDL's extend attribute Exposed as we can decide which WebIDL interfaces can expose to certain target. In this example, we want to expose to Window.

If you look at the signature of new and drop, you can see what Wasm component provides to guest side isn't the actual object. Instead, it returns a Resource<T>. You can think this type as a handle. We will put the actual data that say Document into ResourceTable, and it will return Resource<Document>. And the guest will use it to call all methods related to this resource. For example, if the guest want to call document-element, it will use this handle to call the method. What we need to do is implement the trait method to get the actual object from the table, get the Element object it wants, and then return the Resource<Element> handle it needs:

fn document_element(&mut self, self_: Resource<Document>) -> Result<Option<Resource<Element>>> {
    let self_ = self.table.get(&self_)?;
    match self_.document_element(&self.store) {
        Some(e) => Ok(Some(self.table.push(e)?)),
        None => Ok(None),
    }
}

With all necessary resource traits implemented, it's now possible to create a wasm component and use these host resources! There's cargo-component tool that can compile your crate into a Wasm component. In the code, we just need to use wit_bindgen to get all the WIT bindings we need:

// cargo component build
wit_bindgen::generate!({
    path: "../wit/",
    world: "imports",
});

struct GuestComponent;
export!(GuestComponent);
impl Guest for GuestComponent {
    fn test() -> String {
        let document = dom::node::Document::new();
        let element = document.document_element();
        format!(
            "Document has url: {} with element has attributes: {}",
            document.url(),
            element.unwrap().has_attributes()
        )
    }
}

`EventTarget` As a field

Last, we need to talk about EventTarget. If you look at the definition of NodeImpl mentioned above. you can see I treat EventTarget as a field instead of making all other Impl types into a sum type of EventTarget. The reason of this choice is because there are hundreds of WebIDL interfaces inherent EventTarget. The main reason they need EventTarget is because they can be added to EventListner. Otherwise, they don't share any similarity with each other. So I decided to make it as a field instead to prevent endless casting starting from it. Node, on the other hand, has more frequent requirement to update its Node tree. Many interfaces who inherent it will usually edit its node pretty oftehn. So I think defining sum type for it is more justified. EventTarget will probably be the only special case here.

There's also another issue that WIT spec currently hasn't support function callback yet. The closest thing is scoped callbacks mentioned from the link, but it's still far away. So right now, I define EventListner as good old FnMut that can import/export to Wasm module. Hopefully, WIT reference can be expanded in the near future. Or perhaps Wasm component can get some features from Wasm module that can pass func directly.

Next steps

So that's all the code I'd like to explain. Full example can be viewed in Ohim repository. For the next steps, I wish to collect feedback and starting to evolve current example into full Node tree. Either it can be an alternative script backend or not, I plan to reuse as many Servo components as possible. Once we have minimum functioning script engine, I would try to pass the tree to Servo's layout. And hopefully, it can generate the display list and ask Servo's webrender to render the webpage! The road is still far far away. But it seems to be the time to kick-start the journey!

Behind the Scenes of Verso Browser Development

2025-05-13T12:17:07+08:00

In the past few months, we are trying to evaluate Servo web engine and see if we could build a proper web browser application. In this post, I’d like to share some insights into the challenges we’re tackling, and where we are in the journey to transform Servo from a web engine into a fully functional, user-friendly browser.

Why Build Verso? From Servo Minibrowser to a Stable Application

Servo itself is a powerful and modern web engine, but it has traditionally not been treated as a fully functioning browser. Instead, the Servo project provides a minimum working example called servoshell, often described as a mini-browser, mainly serving as a testing ground for the engine’s capabilities.

Our vision with Verso is to take this starting point and gradually expand it into a formal, stable, and feature-rich browser — something that ordinary users would comfortably use as their daily web browser. The goal is to build an application on top of Servo that delivers a native, complete browsing experience.

By attempting to implement a fully functional browser with Verso, we also identify gaps and missing features in Servo itself. This creates a win-win situation: as we build out needed capabilities in Verso, we contribute improved implementations and bug fixes back upstream to Servo, strengthening the engine for the entire community.

This long-term ambition is why you’re seeing the broad scope of features we’ve implemented recently—from window management and menus to prompt dialogs and notifications.

The Big Picture: Engine Versus Browser Responsibilities

One key motivation behind building Verso as its own separate repository is to cleanly separate concerns:

Servo should stay focused primarily on what it does best—the web engine itself. This includes implementing web standards, improving style, layout, and web APIs.
Everything else that builds a full browser experience — windowing, UI, user interactions, menus, file dialogs, bookmarks, history, notifications, and more — should left for embedders to decide.

This approach not only prevents Servo from being bogged down with application-level chores but also helps distribute resources and responsibilities clearly across projects and teams.

Recent Development Highlights from Our Perspective

Working on Verso, I’ve had the opportunity to collaborate closely with Jason, TeKai, and others. Here are some key features and improvements we’ve tackled recently, reflecting our progress toward a full-fledged browser.

Borderless Window Dragging

A simple but critical UX feature was missing from the minibrowser — the ability to drag and maximize a borderless window smoothly across platforms.

The tricky part is that borderless windows lose native dragging features on Linux and Windows, and on macOS, the draggable area was limited and inconsistent.

We had to reimplement dragging from scratch, carefully ensuring the drag functionality wouldn’t interfere with dynamic UI elements like panels. On macOS, we tracked down subtle bugs to provide a reliable, uniform dragging experience (issue #192).

Context Menus

Context menus are a cornerstone of desktop usability. But context menu support across OSes is fragmented:

Windows/macOS offer native context menu, for which we leveraged the muda crate — originally developed for Tauri — adapting and improving it to fit Verso’s context menu needs (PR #226).
On Linux, especially with Wayland, native context menus are not available. We opted to draw menus inside Servo itself using an embedded webview (PR #237).

This hybrid approach took around three weeks of work and allows us to provide native-like context menus on all platforms.

In the meantime, Working closely with the Servo upstream, we also marked the first pointer event API implementation inside Servo itself.

This was a multi-month effort involving the team, laying a foundation for many UI features, including the later improved context menu (Servo PRs #34437, #35364).

Prompt Dialog Support

From simple confirm dialogue to authentications prompt dialogue is used everywhere, which makes it a fundamental API that users expect to work flawlessly.

Jason took the lead on implementing these dialogs across platforms (PR #250).

Tabs for Multi-Page Browsing

Tabs are a defining feature of any modern browser. Jason dived straight into adding tabs for Verso, building both the core logic and the panel UI (PR #260, panel PR #10).

With this we have tabs work smoothly on all desktop platforms, including creation via keyboard shortcuts.

IME Input Events

Input Method Editor (IME) support is crucial for many users worldwide. Languages like Japanese and Chinese relied heavily on IME support.

We contributed multiple PRs to Servo and Verso that handle pre-edit text, caret positioning, and related operations, ensuring IME input flows correctly and synchronizes with the UI (Servo PRs #35535, #35623 and Verso PR #282.

File Input Dialog Support

File inputs require integration with native file pickers.

We enhanced Servo’s FileSelection embedder message to properly display file counts and names, sorted out related testing issues, then integrated native file dialogs in Verso (Servo PR #35789, Verso PR #286).

Notifications with WebAPI Support

Notifications are an important part of modern web applications.

We added basic Notification and NotificationEvent WebAPI support to Servo, including image caching for notification icons (Servo PRs #34842, #35878, #36055). On Verso, we integrated a third-party library to render platform-native notifications across Linux, Windows, and macOS (Merge Request #308).

Caret and Text Selection display in Text Input

We contributed to Servo’s text input and textarea elements to ensure caret and selection display matches the layout, (Servo PR #35830).

Browsing History and Bookmarks in Profile Config

We started to build out essential browser infrastructure:

Adding a history menu accessible by long-pressing navigation buttons, rendered on top of Servo webviews for cross-platform consistency (Panel PR #11, Verso MR #322).
Implementing bookmark management through panel UI and backend interaction, allowing users quick access to favorite sites (Panel PR #13, Verso MR #327).

What's next?

Our work on Verso seeks for modularity of Servo and hope to improve its ecosystem. One of the major milestones we wish to achieve is to make more Servo components modular and able to be used in other projects. This is also why we have some good news from Tauri community on Verso integration.

Sine we've added multiple application features mentioned above, we are confident it's possible to evolve Verso into a mature application one day. But before that, I think it's also a good time to look back into windowing and rendering management again as we encountered some blockage from time to time.

What's worrying me is Servo's webrender is still using OpenGL, while many other projects have moved to wgpu. I hope we could also get a solid wgpu backend one day, so Servo can collaborate with more projects. In the next few month, I'll share more info on my progress and see what we could do.

Should we add wgpu support to webrender?

2025-04-21T12:17:07+08:00

I've been thinking about adding wgpu support whenever I need to mess around with rendering context and compositor of Servo. The core component of these parts is webrender and it uses OpenGL for graphics. While it works most of the time, it has many workarounds on different platforms. On Windows, it needs ANGLE to guarantee the GL version. On macOS, it stucks on version 4.1 forever since Metal has been the latest official support. It is also worrying that OpenGL hasn't been updated ever since because Khronos decideds to move on to Vulkan. Whenever I look into webrender, I also fear it will become the part that might be unable to maintain in one day. There are some solutions in my mind that we could take depending on the situations and the resources we could use.

Build on top of ANGLE

The easiest and minimum effort we could take is, of course, extending the support of ANGLE. Servo already uses it on Windows and has a fork called mozangle. It shouldn't be a problem to extend the support to other platforms. This should resolve the worry if macOS doesn't want to support CGL(legacy openGL) anymore.

However, there are some disadvantages that will restrict Servo's development. First is the binary size. Building the shared libraries of ANGLE are around 20MB of DLLs on Windows. If we extend to all platforms, Servo will increase this amount of size. And Servo already needs to include GStreamer and SpiderMonkey already. Another issue is moudlarity, keep using OpenGL means anyone who wish to adopt Servo need to use this graphic library. If you browse through Rust's GUI ecosystem, you can see many frameworks are migrating to wgpu. Some even don't have OpenGL support anymore. It will be a growing problem for people who wish to integrate Servo and many other crates.

Implement Compositor trait

If we are able to spare some resources to look into, I think the experiment we could do is implementing the Compositor trait. This is the trait for webrender managing surfaces and framebuffers. It can be None which is what Servo does, and it will let external usage to decide how to bind the buffers and surfaces. For Firefox, it does implement this trait instead.

The only issue I found is webrender still use OpenGL APIs internally. I'm not sure if wgpu has any interoperability to OpenGL. Perhaps it needs to lock into OpenGL backends as well. But this will circle back to the need of ANGLE or similar tools again.

Add wgpu version of Renderer

The one true solution in my opinion is adding a wgpu version of Renderer to webrender if we have enough resource. While it sounds crazy because webrender is a huge project which is over 200k LOC, the GL usage is limited to Device and Renderer. Although they are still pretty large, I believe with someone who understand WebGPU, it can build the minimum support in reasonable amount of time. The only worrying is probably shader support. However, there're only a few shader in Servo. I also believe we are able to translate them.

If we can get the wgpu support, I believe it can bring lots of benefits to Servo ecosystem. For maintainers, it's already fewer workarounds need to worry about. This also means we can obtain better WebGPU support, because the current one needs to copy the buffer to openGL which is not ideal in terms of performance. And for the cummunity, it will be easier for people to integrate into other projects.

Why I voted for Servo's AI policy change despite I don't use those tools

2025-04-08T12:17:07+08:00

Before we start, I want to claim this post is written without any usage of AI tools, even without Grammarly which I've added the plugin into Firefox way before AI mania and usually use it to fix my grammar. With Servo's recent controversial AI policy update, I would like to share my two cents on it. However, it's not going to be all about this policy only and will be a bit off topic, so I suppose it's better to publish on my own blog.

I am one of the Servo TSC members. Before this, I tried to casually contribute to various browsers and projects related to browser ecosystems. Servo became the browser engine I would like to push the most, and it came a long way for me to be able to steadily contribute to it. To this day, the commits I pushed never use any AI tools. I don't even use Github Copilot which is a very popular one and can be integrated to your IDE pretty easily. Most of my work is dealing with embedding or rendering side of Servo engine. My experience when testing with Copilot was terrible. All code suggestions to platform stuff like Objc runtime, COM, and even just some unix sockects are either plain wrong, or seem to work but have deep flaws that require deep know-how to identify.

It came to my conclusion that LSP is still the best assist tools to help me code. Servo book has "Editor Support" page to help you add rust-analyser support when you develop Servo. I know it's still not perfect, and my friend also encountered some pitfall. But we are adding the support as much as we can.

However, I still voted for the change. The closest statement to describe my stand point is Ladybird's contributing guide. I won't allow gibberish if I need to deal with the issue or feature. But if it could help you and you can take the responsibility to meet the standard we set, I'm happy whatever tools that assist you. In Servo's script component, the common standard is to keep the WPT coverage and pass more scores. And this is what policy update mentioned: someone experimented with WritableStream and their experience is positive. However, we already set the restriction that any AI tools are not allowed. And this was how the debate among TSC members began and the proposal Servo published this week.

I think the biggest mistake and lesson we should learn from is this kind of topic should open to public in the first place. We didn't gather the opinion from community to discuss the solution. I believe some members who vote for the change is also similar to my stand. But the proposal appeals to no one despite it's a compromise already. Servo is a very unique browser engine shared by the community. It's not dictated by any corporation or BDFL. This is why Servo is the project I wish to push the most and hope it could be the real open-sourced browser that offers freedom. I'm confident this topic will be resolved by the community in the end, whether we keep the restriction or not.

With the topic we have recently, I would like to take this chance to discuss the code contributors ourselves. I believe one of the huge factors that lead to this topic today is because of how we contribute. Like I mentioned before, Servo isn't controlled by a single person or corporation. This means contributors are responsible for their own finance. Servo's donations are primarily used for operation costs. While some people are hired by certain companies to contribute, others need to find their way to sustain.

Around a year ago, I tried to put my best effort together with the help of several people from Servo and Tauri to see if we can make practical usage for Servo and get the stable funding options. Versotile is the organization we formed under Commons Conservancy. For now, we only applied NGI grants because we believe this aligns with our vision the most. However, we also need to make sure the task is delivered the actually get the grants with a given deadline.

One of the blockers from the tasks we want to do is to remove the patch of jsstreams feature. The reason of the patch is because upstream has removed whole implementation completely, this led to worry about annual updating of spidermonkey ESR version and we expected it to be more and more difficult to update each year. So I tried to find the people can help me rewrite ReadableStream in Servo. The scope of stream spec is enormous, even ReadableStream itself only is huge. Fortunately, we managed to find the people and resolved the issue. And then there's the follow-up issue to WritableStream which resulted into the controversy policy change I saw.

What worries me the most is the potential of losing major contributors. If you contributed to Servo before, you should understand how difficult it is to land the features you wish to happen. Especially when there are components like script and layout requiring deep know-how to understand how it actually works. There are PRs with lots of comment back and forth and still got stuck for months because no one entirely sure how certain types work. This is why I voted for the policy change despite I'm not fond of AI tools either. In fact, I stated it clearly Versotile has nothing to do with AI when we were applying for grants. But I also hope to see other contributors can receive the help they need when contributing to the project.

Sorry if this sounds like a rant on latter half of the article. I'm confident the feedback from the community will take a huge role on the policy change. But in the meantime, I want to let people understand the difficulty of smaller contributors that wish to devote to the project in the long run. No matter what the change will be, I wish the follow-up can focus on helping contributors next. I hope people can keep sponsoring Servo , and if possible, also sponsoring us. If we have more stable funding option, I believe we can deliver more features to Servo that can meet community's needs and expectations. Welcome to send me a mail, if you wish to discuss in details.

Verso: initial multi-window support

2024-08-10T12:17:07+08:00

The multi-window has landed! We are fortunate that refactoring worked as planned. Although it opened some follow-up issues to triage, I'm glad we got the initial support to open more windows instead of just only one in the very beginning. This is one of the most difficult challenge when it comes to develop GUI tools and frameworks. This opens more opportunities to implement further features such as prompt dialog and directory selector, etc. This post is actually the third part of previous series, but I think it worths an unique title for it. In this post, I'll explain what are the key changes to enable multiple windows.

Multiple surfaces

To achieve multi-window, we need, of course, multiple windows (Duh). Winit can already open and manage more than one window. What we need to do next is create individual surfaces for each window. A surface is a collection of pixel buffers that are rendered via GPU and displayed in the final target. The target could be either a window or a texture that can be saved in the file or offscreen. In our case, we only need the window surface for now. We will explore offscreen rendering in the future. We extended the capability of RenderingContext to be able to create and destroy additional surfaces in Servo#32933. And then we try to swap the surface whenever we need the Compositor to deal with different windows.

This change is easier said then done. Although it essentially just needs to add the method of swapping surfaces to the Compositor, updating the window fields to a hashmap of windows requires a lot of fields to be updated as well. I'm also surprised that many changes in the PR are actually updating the parts related to windows instead of dealing with surface.

Multiple display lists

Let the Compositor manage multiple surfaces is the first half. The other half is telling WebRender to render the correct display list. A display list is used to supply a new frame to the WebRender. When building the display list, we could decide which webviews are in such window and push to the list. Finally, we will see the Compositor displays the different surface when we swap the window. It will call the method that can update the display list when the surface is changed.

And that's how Verso gets its initial support of multi-window. There are some follow-up issues we need to triage further. For example, it seems to have some trouble when we try to close the window on macOS and X11. On Wayland, it still displays in the same window. We will have to spend some more time to fix these issues and polish the multi-window feature. Nevertheless, I'm still happy with what Verso achieved. Because even Firefox is still creating multiple contexts to deal with multi-window. We managed to do it with a single context with multiple surfaces.

What's next?

After we polish the multi-window feature. We will explore the multi-process mode, which is already a configuration option in Servo, but it only supports Linux and macOS for now. I want to even improve it via sandboxing on all platforms. Then, we plan to figure out the set-up of Gstreamer with the best DX experience and enable the media feature back. We should also revision the IPC mechanism again since we can communicate with the Constellation directly now. If I still have some free time, I would like to implement ReadableStream in the script crate again. So we can remove the heavy patch from mozjs.

There are many challenging tasks ahead, but I'm excited to see what Verso will become. I'm also looking for new sponsors since this work is probably the final grant from NLNet. If you are also interested in supporting Verso, a new web browser written in Rust, please don't hesitate to donate or contact me.

Verso: Writing its own compositor part 2

2024-07-30T12:17:07+08:00

In the previous post, we extended the embedder to handle more jobs like thread and channel creations. We also tried to communicate with Constellation directly to reduce the overhead. In this post, I'll demonstrate how we implemented our own compositor that fits our needs. This part may seem like just writing the same module, but I believe it did more than that and established a solid foundation to support multi-surface in rendering context.

Clarify which component should own which states

One of the major goals of the custom Compositor is to figure out which state should stay in which type. Because we are going to use the same rendering context with multiple surfaces to achieve multi-window support, this means the rendering context should, of course, belong to the Compositor. This also means all the types around webrender will stay in the Compositor. However, other fields that are not GL-related should be removed from the Compositor, and it should only get access to them when it's necessary. So here are some major fields that got removed, and I'll explain the reasons.

Window

This field is very obvious because we want to support multiple windows in the future, so the Compositor shouldn't own only one window in its field. In Servo's compositor, it uses WindowMethods to get the generic of the Window. Its trait methods cause a little overhead because they are not granular enough. For example, when it wants to get the viewport size, it always needs to get the whole EmbedderCoordinates. And the rendering_context forces the window to hold a copy of the rendering context as well. The Compositor should only get access to a window in methods when it really wants to get the states of the window. After removing, it also helps the window type remove some redundant types.

Webview

A webview is essentially an alias of a top-level browsing context. Previously, the Compositor had a WebViewManager to handle them, but now it's removed. This sounds a bit weird but let me explain. In the multi-window environment, I would prefer a window that contains and manages the web views instead of the compositor. If the Compositor wants to know the painting order of webviews for the current frame, it can ask for Window::painting_order to get the order the window wishes to composite. It will be the Window to actually own its WebView. This will also be the same when we introduce more window types like headless windows in the future.

CompositeTarget

CompositeTarget was used for checking what's the target that the Compositor should display. So it can render to offscreen framebuffers or create images in shared memory instead. However, this creates additional texture and framebuffer objects that are not owned by the RenderingContext. This makes it difficult to figure out what are all these GL objects that the compositor is handling. It should be the job of rendering context to tell the compositor which exact surface it should use. So, right now, they are all removed, and there's only one single surface in the rendering context that needs to be handled. We will extend the functionality of rendering context to support multiple surfaces in the next part.

The next step

With the custom compositor added, the current Verso instance workflow remains the same. For each run iteration, it will handle the winit event first and then handle servo messages from the Constellation. But this time, it's the Window and the IOCompositor working with each other to handle all the messages from the Constellation. The next step will be the most significant step: We will extend the rendering context to support multi-surface. And if it works perfectly, it should enable us to implement multiple windows with a single context. We are close to complete the journey, stay tune for the next and hopefully the final part!

Verso: Writing its own compositor part 1

2024-07-20T12:17:07+08:00

In previous post, I mentioned we probably should research our own compositor to get multi-windows support. The compositor is a component in Servo that composites graphical contexts and decides which browsing contexts should be displayed on the surface of the window. Servo's compositor isn't exposed to users directly, despite its being in the same thread as the embedder and being a public module. This makes it difficult to get the work we want the compositor to do. And because we use the channel to send EmbedderEvent for compositor to handle, there's always a delay for compositor handling its messages, which makes it difficult to predict when the frames will be rendered. In the hope of understanding more about how to enable multiple rendering contexts to compositor, I decided I should write at least one for an experiment. Verso#86 is the first step to this exploration.

What has changed

However, this PR hasn't actually written the compositor yet. It just extends embedder's work to what Servo instance does. So now Verso itself will handle all channel and thread creations, and it can call the compositor methods directly. I have to say this is not my first choice, to be honest. I actually prefer using channels to send EmbedderEvent and receive EmbedderMsg to communicate. They are very clean enumerations that help users understand what kind of task the embedder should handle. But like I said I wish to get more control to understand the whole behavior of compositor. So Verso now calls the compositor directly and sends ConstellationMsg itself to the constellation thread. Surprisingly, I think it didn't change a lot. We are still using channels, but we can communicate directly with Constellation and Compositor at this time.

Thread creation

The most obvious benefit is that I have a clear overview of what threads require Embedder to create now. The constellation thread requires several channel senders of these threads when creating. We can potentially spawn the thread lazily or even disable them based on preference. This could reduce huge amount of memory usage at the beginning. Here are threads that Embedder is responsible for spawning and the improvement we can achieve in the future:

Constellation: This is the main station of all Servo components.
Memory and Time Profiler: There's no preference option to toggle. But since there's a constellation message to disable profiler, maybe it can be disabled by default.
DevTools: This can be toggled by Opts::devtools_server_enabled.
Webrender: This is Servo's renderer and has its own thread pool. Perhaps we can set the size of thread pool.
WebGL: It must be created for now because WebXR needs to use it to create a registry. Perhaps there's a way to disable them by default and only spawn it lazily.
Bluetooth: It doesn't have preference option either. We should look for a way to spawn it lazily.
Resource threads: This is a thread pool with the size based on CPU core. This is the one that really needs to be improved in the net crate because it can be spawned multiple times. There's also a Tokio runtime in net that will spawn its thread pool. I think this is the main reason we saw hundreds of MB memory usage upon creating the browser. If you have 32 cores, that means 64 threads will be created already!
Font Cache
Canvas: It should be spawned lazily as well.
Web Driver: This can be toggled by Opts::webdriver_port.
JS engine: Spidermonkey also has its own thread pool.

As you can see, that's quite a few threads and will already use some MB of memory. One of the improvements we should constantly push is trying to spawn only necessary threads at the beginning.

Constellation messages

Another benefit we got is we can focus on handling constellation messages only. But I would say this is a subtle benefit. We change from EmbedderEvent to ConstellationMsg. The improvement we got I think is more about finding some redundant parts that can be eliminated. For example, I found GlFns::load_with is called multiple time during thread creation and event handling, even Verso itself will load again when creating a window. And that's 60 KB each time will be included in the binary. We can manage it to call only once. I also found we can send the web driver message directly to the Constellation without starting a server. Of course, we can also extend EmbedderEvent to do so. But I guess I will never find out if I can reach deeper. This can benefit us by sending some light weight messages without spawning a web driver thread for the more trivial use cases.

The next step

So right now, it's more like a preparation before writing our own compositor. The next step is trying to replicate the existing compsitor in Verso, so we can make sure it can work at least. Then, I want to understand which parts belong to which component, primarily the parts from Webrender. Should they all belong to the compositor? Or should they be kept in the window? Can we also just create one compositor and give it different contexts to handle? The whole compositor is around 4000 LOC. So I think it will take a while. But I'm confident we can clear this out one by one. I'll also upload more posts about this series in the near future.

Verso: A new browser based on Servo

2024-07-13T12:17:07+08:00

Yep, I'm building a new web browser called Verso based on Servo. If you don't know what is Servo yet, it's a web engine written in Rust from the ground up. I think it would be cool to see a browser that's built on top of it instead of creating yet another chromium fork. I also have personal milestones want to achieve. One of them is building the UI from Servo itself. Right now I can already render two views: One for the webpage, the other for the navbar UI. The image below is the Verso window navigating the demo page:

I know it's still a bit rough but what I want to showcase is that the navbar can already perform some basic actions. There are still a few blockers I prefer to resolve first before improving the UI. Like I said I would like to dog food eating which should look inside both Verso/Servo and improve them. Here are some list served as my remainder and hopefully attract some contributors to help as well.

Multi-Windows

Last year, I spent a lot of time to look into multi-views support. And thanks to Delan from Igalia, it's added in Servo this Januaray. So the next milestone would be adding multi-windows support. I have some idea but not sure how to execute yet. Servo's compositor only accept one rendering context at the moment. With multiple windows, I believe there will be multiple contexts need to handle. Another restrcition is the embedder couldn't access to the compositor directly despite they are in the same thread. They use channels to communicate with each other. I'm thinking maybe I should implement another compositor as experiment to see how it goes.

Better IPC

The navbar UI I showcase in the image above is essentially a web page as well. The embedder sends events and receives messages with existing channels. For example, the UI may send the message by prompting a dialog. But instead of actually showing the dialogs, the embedder will process the message and perform actions like navigating the URL and minimize/maximize the window. But there are some advanced features that current event variants couldn't satisfy them, such as changing the history session and reflect to the input bar. We could try to add more variants but some may contain security violation concerns. Perhaps Servo can public the DOM module in script crate. And we add a custom DOM API similar to postMessage that only accepts special origin like about:.

Multiprocess

Servo actually has multiprocess mode but it only supports Linux and macOS. I feel like multiprocess is a must have feature after Spectre. At least we should provide some basic site isolation. It would be great that Windows can get the benefits too. To achieve this, we will need to fix this issue: ipc-channel#310 which is caused by this panic. Another good to have is sandboxing but gaol hasn't supported Windows yet either. We should either add the support or see if there are other crates already add the implementation like AppContainer.

Flatpack Support

Linux remains as the most difficult target when it comes to packaging. There are so many distributions and package formats. We also have to worry about both X11 and Wayland at the same time. Althouh Servo has a book to get started with the setup, it still lists lots of dependencies compared to other platforms. I think we should figure this out in the first place, writing Flatpak manifests to clarify the dependencies, and make the final packaging easier to distribute.

Looking toward the future

There are more items in the roadmap but I guess these milestones will take quite some time already. I have to say I'm more and more excited to the Verso project as I engage into the Servo community deeper. Nico from Taffy is also trying to add flexbox support to Servo and it looks pretty promisng! I believe we can see a web browser that's made in Rust in the foreseeable future!

Install Windows 11 the hard way

2023-03-14T12:01:00+08:00

Recently, I got my hands on a Framework Laptop DIY Edition. I wanted to set up a dual boot system, but I didn't want to install Windows 11 on my primary SSD due to some bad experiences in the past.

I planned to install Windows 11 on an storage expansion card. While this is possible theoretically, Microsoft's boot driver may not work with its default interface for various reasons. We will have to create the required partitions manually. In this article, I will share my experience for installing Windows on an external drive and provide some tips during the process.

Create a USB Installer

First of all, we need to create a USB installer for Windows 11. If you have a device with any Windows OS, you can download the installation media from the official page. Download it, plug in a USB drive, and follow the instructions. You should complete it in no time.

Boot into Installer

Once you boot the laptop, repeatedly press F12 to enter the boot selection screen, and then select your USB device. When the installer appears, proceed through each step until you accept the license agreement. After this point, we won't be able to use the installer any longer. We'll need to create the partitions ourselves.

Create Partitions Manually

Proceed with caution during this step, as you will need to create several partitions, and selecting the wrong disk may potentially overwrite the internal disk.

Essentially, Windows requires the following partitions to be created:

Windows RE Tools partition
System partition
MSR partition
Windows partition
Recovery image partition

Now let's use diskpart to open the built-in partition tool. And then select the disk x where x is the number of you expansion card:

diskpart

list disk

select disk x

Now, we need to format the disk to GPT format. Please double-check that you have selected the right disk before proceeding!

clean

convert gpt

Windows RE Tools partition

Let's start with RE Tools partition. Note that I increase the size slightly since the size of Windows build has grown too. Some following partitions will also apply to this tip. There's lots of 0 when assigning gpt attributes. Just remember there are 14 zeros:

create partition primary size=670

format quick fs=ntfs label="Windows RE Tools"

assign letter="T"

set id="de94bba4-06d1-4d40-a16a-bfd50179d6ac"

gpt attributes=0x8000000000000001

System & MSR Partition

Next is system partition and MSR partition:

create partition efi size=100

format quick fs=fat32 label="System"

assign letter="S"

create partition msr size=128

Windows Partition

Now here the important part: you should choose proper size for Windows partition depending on the size of your expansion card. If you use 250GB drive, then set the size to 23000. If you use 1TB drive, then set the size to 949044.

create partition primary size=230000

format quick fs=ntfs label="Windows"

assign letter="W"

Recovery Image Partition

The last is recovery image:

create partition primary size=5120

format quick fs=ntfs label="Recovery Image"

assign letter="R"

set id="de94bba4-06d1-4d40-a16a-bfd50179d6ac"

gpt attributes=0x8000000000000001

View the disk volume to confirm that the partitions were created successfully. Take note of the drive letter assigned to your USB drive containing the Windows installer. In my case, it's E. If everything goes well, you can exit the diskpart tool.

list volume

exit

Copy Windows Data to Partitions

Now we install the Windows 11 by copy data to partition manually. When you see E:\ in following instructions, you should replace it to the letter you have. And when you see index, you should enter the Windows 11 version you want to install. Here's overall list, but you probably just need to enter 1 or 6:

Windows 11 Home
Windows 11 Home N
Windows 11 Home Single Language
Windows 11 Education
Windows 11 Education N
Windows 11 Pro
Windows 11 Pro N
Windows 11 Pro Education
Windows 11 Pro Education N
Windows 11 Pro for Workstations
Windows 11 Pro N for Workstations

One last thing to note is that the extension of some files may differ depending on the installer you use. If you can't find install.esd, for example, try looking for install.wim, and vice versa.

md R:\RecoveryImage

copy E:\sources\install.esd R:\RecoveryImage\install.esd

E:\Windows\System32

dism /Apply-Image /ImageFile:R:\RecoveryImage\install.esd /Index:1 /ApplyDir:W:\

md T:\Recovery\WindowsRE

copy W:\Windows\System32\Recovery\winre.wim T:\Recovery\WindowsRE\winre.wim

bcdboot W:\Windows /s S: /f UEFI

W:\Windows\System32\reagentc /setosimage /path R:\RecoveryImage /target W:\Windows /index 1

W:\Windows\System32\reagentc /setreimage /path T:\Recovery\WindowsRE /target W:\Windows

Restart and Boot into Windows

If everything goes well, we can exit the installer! Remove the USB drive, restart the machine, and keep pressing F12 again to choose the drive containing Windows 11 to boot. If you want to default to boot Windows, you can press F2 instead to change the boot order. It's in Boot > EFI Boot Order.

Install Driver Bundle

Once you boot into Windows, you will be prompted to complete the setup process. Just proceed as usual. If you finally reach the desktop, you should have a functional Windows installation! However, we're not done yet. We have to install Framework's Driver Bundle.You can install the bundle and just copy to the USB drive you use for installer. And then plug into the laptop to install it.

Restart and congratulation! You have a Windows installed in an external disk!

Environment Setup for Building Webkit on Linux

2023-03-04T12:01:00+08:00

Although I've always wanted to contribute to Webkit, I've often found the issues to be too difficult or too time-consuming to tackle amidst my regular workload. However, I recently found myself with enough free time after Rust Nation, and decided to take on an issue that seemed straightforward enough to contribute to. Indeed the Webkit wiki provides comprehensive information for contributors, I wanted to share my own steps and tips for setting up the environment in the hopes of helping future developers get started on Webkit more quickly and painlessly.

Choose git repo as Source

Back in the days, I used to download release tarballs to test and debug, only to discover that they could conflict with builds installed by package managers in my distribution. Even worse, their build scripts didn't provide an uninstall option, so once you run ninja install, there's no turning back. Because of this, I recommend building from the git repository, even though it takes longer to build from scratch. This way, you can avoid conflicts with other builds and easily uninstall if necessary.

Since Webkit has migrated to git, it's really easy to access it. Their main upstream is now on Github!

git clone https://github.com/WebKit/WebKit.git WebKit

Installing Dependencies

Before starting to build the project, it's important to make sure that all dependencies are up-to-date. Luckily, Webkit provides a flatpak runtime and SDK to simplify this process. However, these files can be quite large and need to be re-downloaded each time a new version is released. The worst part is that download speeds can sometimes be painfully slow. I've tried changing DNS or using a VPN, but none of them helped. If you find that the download speed is unreasonably low, try rerunning the following command. Whole flatpak dependency could be 5+ GB and take hours to download.

Tools/Scripts/update-webkitgtk-libs

Building and Running

The steps to build and run Webkit are quite straightforward; you can follow the instructions provided on the project's wiki, specifically the build page). However, it's important to note that building the project can take several hours to complete. If you want to perform debug builds, simply pass --debug to each command. But the debug build will run pretty slow:

Tools/Scripts/build-webkit --gtk
Tools/Scripts/run-minibrowser --gtk

The source code of mini browser demo can be found in Tools/MiniBrowser/gtk/main.c. It has a custom url scheme minibrowser-about. But if you type about: it will also redirect to this scheme.

Webit can also perform incremental compilation. So if you just edit some GTK related files under Source/, it should take a few minutes to compile again. But if you have to edit the interface of WebCore, it will need to relink the libraries and hence take several hours to compile again. Try some advice from this page, if you want to speed up the build time.

Debugging and Testing

When you start fixing some issues or adding some features, you might want to search the codebase. Since the codebase of Webkit is huge, I suggest just browse the code through https://searchfox.org/wubkat/source. Even using ripgrep can take minutes to do the job.

Debugging page on wiki has pretty good advice about how to debug Webkit. There are two test suites that might relate to you when you need to perform some testing. And if you want specific test, simply add the path of the test to them:

Tools/Scripts/run-webkit-tests --gtk  http/tests/media/video-play-stall.html
Tools/Scripts/run-gtk-tests WebKitBuild/GTK/Release/bin/TestWebKitAPI/WebKitGTK/TestWebKitWebContext

Contributing

Again, contributing page has detailed walkthrough about it. Basically, yo need to make sure the tests you would like to run have to pass at least. And then check your code obeys the code style guideline:

Tools/Scripts/check-webkit-style

If you haven't made any commit yet, be sure to run the checkout setup script:

Tools/Scripts/git-webkit setup

This will give you a commit template when you are adding commit. You'll just need to fill out the required information. The last thing to note is webkit only allow one commit per PR. So remember to squash or amend the commit when updating PRs.

GAT 懶人包

2022-11-08T12:04:23+08:00

Rust 1.65 提供了大家期待已久的功能「Generic Associated Types」，這是在 Functional Programming 中 Higher-Kind Types 的其中一種實現。對於已經有這樣需求的人來說，這些概念應該並不陌生，或是早已知道如何善用它們了。但對於從未接觸過的人來說，我想應該就會遇到一些困難。通常看到新出的 Rust 進階功能，我們都會推薦大家去看 RFC，而我近日也將 GAT 的 RFC 翻譯完畢。但我並沒有相當的把握確保新手能了解文中舉的例子「StreamingIterator」，因為它的泛型用到了生命週期，尤其是後面又繼續提到了各種進階的用法，像是怎麼與 Higher-Rank Trait Bounds 一起使用等等。我有點擔心新手一開始接觸時就會看的眼花撩亂。這次我們不妨把所有概念都拋諸腦後，看看在寫程式的過程中，到底為何會遇上這樣的需求。

讓我們用各型別都有的方法 map 來作為例子，這在 Option 和 Result 都有。如果今天我們想定義一個 Trait 將該方法抽象化成泛型（generic）型別的話，我們會發現這是做不到的！其中一個得回傳 Option<T> 而另一個得回傳 Result<T>。這時你可能就會想將 Option 或 Result 作為泛型的引數（argument），但是這也是做不到的！泛型型別的名稱在 Rust 不是一個基礎的型別！

而 GAT 能夠允許你達成這樣的事，這也是為何 RFC 一開始得先介紹 Kind 以及 Type Constructor 等概念，我非常推薦有時間可以讀一讀這段。不過畢竟這篇是懶人包，怕太難懂我們可以直接先來看看真正的例子會怎麼寫。我們可以宣告一個這樣的 trait：

trait Mappable {
    type Item;
    type Target<U>;
    fn map<U, F: FnMut(Self::Item) -> U>(self, f: F) -> Self::Target<U>;
}

然後針對 Option 和 Result 實作它們：

impl<T> Mappable for Option<T> {
    type Item = T;
    type Target<U> = Option<U>;
    fn map<U, F: FnMut(Self::Item) -> U>(self, f: F) -> Option<U> {
        self.map(f)
    }
}

impl<T, E> Mappable for Result<T, E> {
    type Item = T;
    type Target<U> = Result<U, E>;
    fn map<U, F: FnMut(Self::Item) -> U>(self, f: F) -> Result<U, E> {
        self.map(f)
    }
}

這樣一來你就能使用「泛型的泛型」來寫出這樣的函數：

fn absolute<M: Mappable<Item = i32>>(m: M) -> <M as Mappable>::Target<u32> {
    m.map(|x| x.abs() as u32)
}

這還能用在 Vec 上，完整的範例可以參考 Rust Playground 的連結。在 RFC 中稱這樣的模式為「Family」模式，同樣的作法也能套用在指標的泛型上，像是 Arc 與 Rc。當然 GAT 也可以用在生命週期上，就如同 RFC 上的 StreamingIterator，而這種 trait 的用途就是希望能只可變借用到特定片段的切片，而非平常 IterMut 得借用一整個集合。而在往下還有更多複雜的用法，不過希望看完這篇懶人包你能對 GAT 有初步的了解，在閱讀 RFC 時就不會那麼令人望之卻步了。

After half a year, what now?

2022-09-09T11:04:23+08:00

At the beginning of this year, I was planning to contribute to Servo and wish to restore its glory. But after diving into the code base and understanding its landscape, I accepted the cruel reality that it's impossible unless Servo can be adequately funded again, just as previous Servo members advised. So I will not continue the series of Servo posts. However, I hope I can demonstrate the situation it faces well in this post, grasp the remaining we have, and look for where we can explore further.

What happened after Mozilla layoff?

After Mozilla layoff in 2020, most members from Servo are fired AFAIK. Despite being moved under Linux Foundation, the foundation would only cover its cost of CI/CD. So technically speaking, the project was already in maintenance mode at that time. But several parts in Servo are already integrated into Firefox, and some people in Mozilla still maintain them to date. I was hoping if we can fill the missing puzzle in Servo, we can get a minimum viable browser or a webview library. However, it didn't go as easy as I thought would be. There are some blockers just too difficult for normal contributors to refactor.

Unable to upgrade SpooderMonke

Servo, as a project under Mozilla, uses SpiderMonkey as its JavaScript engine. Mozjs and rust-mozjs are its wrappers on top of SpiderMonkey. In the last two years, contributors are trying to upgrade it to the latest version but they all failed. Servo still uses version 88 nowadays, while SpiderMonkey has already published 108 at the time of this post. And the engine itself is also the problem IMHO. Its types, GC, and design affect not only the script layer, but also the rest of Servo. Although Rust doesn't require any garbage collection, JavaScript in script layer needs it. In order to use the GC from SpiderMonky, Servo has to create crazy amount of types and lints to control it. This makes handling DOM types extremely verbose, and hence also affects whole style crate and layout crate since they all have to deal with these types. I once considered perhaps we could switch to v8 instead which have a well-maintained crate from deno. But after giving a try of its API for dealing with GC and creating JavaScript types, I got a conclusion that it will fall into same scenario like Mozjs already has. Unless Rust has a decent crate for GC, I don't believe we can work with a GC language seamlessly. Shifgrethor is the closest we could get, and I also forked it into elise for testing multi-thread situations. But it relies on several nightly features.

Spaghetti inside script/style/layout

One of the main goals of Servo is to extract each feature from a browser into individual crates. This has been succeed in some features like HTML parsing, selecting CSS, and rendering etc. But there are some crates still tangle around and unable to do so which are script, style, and layout crates. We already see types from GC affect all these crates. It's also difficult to distinguish which document traversals should belong to whom. The worst part is the old layout is sort of incorrect. Back in the day, they want to make the layout to be parallel as possible. But this didn't work well in some attributes like flex and absolute. When they tried to rewrite a new one, the layoff happened. So now we have two layout crates: the old one is more complete but would be wrong in specific properties; the new one has almost nothing but should be correct if only it could be complete. If you try to fix some layout issues, you will have to jump around different crates again and again. And the amount of issue is massive already!

Crates that still work well

With huge blockers like those mentioned above, I tend to agree it will require proper funding to be able to start developing again. In the near future, I feel like we should focus on those crates which are already mature and explore further on top of them. Take crates like html5ever, cssparser for example, they become the bedrock of every modern web framework. There are also crates like kuchiki and scraper which build on top to make users easier to use. And I hope perhaps same thing can happen to webrender.

Webrender is one of a few crates still maintained by Mozilla and is being used by Firefox directly! There was a GUI crate called Azul that once used Webrender to build the layout system. Although Azul is also no longer maintained due to personal reasons, I feel like we could give it another shot and see if an HTML/CSS layout system can work again. I understand it will be very limited without any scripting functionality. But I hope we can try something other than DOM layer built by JavaScript engine. Maybe an API for document tree could work, or just doing regular XML parsing as other GUI frameworks do is enough. I don't have any conclusion yet, but I haven't come this far just to end the journey here either!

Rust Kernel Module: Pinning

2022-06-04T12:04:23+08:00

Let's talk about pinning! This is a concept we usually don't encounter often. It's introduced in the update of Rust 1.36 which brings async syntax and many other related types to build the async executor. And Pin is one of them. If you want to understand it comprehensively, documentation of std::pin has excellent explanation of why we need to pin the data. But in short, it's basically a type to pin data to its location in memory.

This is in fact rarely seen in the world of C/C++ which doesn't construct movable objects frequently. Even when we work with std::move in C++, we will make sure move constructor is equal to delete. However, cases like moving data are the default behavior in Rust. Its cloning requires explicit semantics.

The problem requires pinning

When everything is under the context of Rust, it's of course not a problem. Ownership model can take care of it. But this is not the case in our kernel module. Instead of rewriting everything in Rust, it's still more reasonable to build on top of something that already exists. This is how kernel crate wraps around the existing kernel interface. And that's why you see we reuse the refcount_t wrapped by Ref type instead of using Arc like normal rust program.

This is the point that pinning matters to us. Because many kernel data structures are actually self-referential. Either it is a list self-reference itself directly, or it points to other structure which points back to it eventually.

Let's look at the definition from kernel's mutex which we will discuss how to use it soon in the future post. It has a wait_list which is an intrusive, circular, double-linked list.

struct mutex {
	atomic_long_t		owner;
	raw_spinlock_t		wait_lock;
#ifdef CONFIG_MUTEX_SPIN_ON_OWNER
	struct optimistic_spin_queue osq;
#endif
	struct list_head	wait_list; // <==================
#ifdef CONFIG_DEBUG_MUTEXES
	void			*magic;
#endif
#ifdef CONFIG_DEBUG_LOCK_ALLOC
	struct lockdep_map	dep_map;
#endif
};

If we represent it visually, you can tell it's self-referenced as soon as you see it. When we define the abstraction in Rust, we of course include this binding and the data we want to protect. So this list is included in the type of Mutex:

pub struct Mutex<T: ?Sized> {
    mutex: Opaque<bindings::mutex>,
    _pin: PhantomPinned,
    data: UnsafeCell<T>,
}

And because we already know Rust is move by default. When type like this is contained in the field of other struct, it's very trivial to move it in basic operations. For example if we declare a struct contains a mutex and we want to make it a reference count object, we will see the problem as shown in below:

Ref::new(AStruct{
    //...
    innner: Mutex::new(Inner { /* ... */ })

})

We have an original list in inner field, and when we called Ref::new, we need to move that structure to the Ref type we are going to create. This means create and copy the object bit by bit from the original. And because we copy the data the pointer points to instead of pointing to the newly created one, this causes the new list points to the old one.

Miscdev initialization

This also happens to misc device we just learned. Its definition also has an intrusive, circular, double-linked list. That's why methods signature of miscdev::Registration always requires Pin upon registration:

struct miscdevice  {
	int minor;
	const char *name;
	const struct file_operations *fops;
	struct list_head list; // <==================
	struct device *parent;
	struct device *this_device;
	const struct attribute_group **groups;
	const char *nodename;
	umode_t mode;
};

pub fn new_pinned(name: fmt::Arguments<'_>, open_data: T::OpenData) -> Result<Pin<Box<Self>>> {
    Options::new().register_new(name, open_data)
}

pub fn register(
    self: Pin<&mut Self>,
    name: fmt::Arguments<'_>,
    open_data: T::OpenData,
) -> Result {
    Options::new().register(self, name, open_data)
}

You can call new and pin it manually before register, or just call new_pinned to do both thing at the same time. The interface enforces you to pin the date before registration.

Conclusion

And that's the reason we use new_pinned to create the misc device in previous post. The question we haven't solved is how do we also pin the mutex we just mentioned. This will leave to the next post to answer and I think it will also be the good timing to introduce what built-in concurrent primitives we can use in kernel.

Reference

Rust for Linux by Miguel Ojeda and Wedson Almeida Filho

Rust Kernel Module: Character Device Driver

2022-05-25T12:04:23+08:00

There's one kind of module called device driver which provides functionality for hardware like a serial port. On Unix, each piece of hardware is represented by a file located in /dev named a device file (or sometimes called device node) which provides the means to communicate with the hardware. Devices are divided into two types: character devices and block devices. Block devices are usually used for storage hardwares since have buffers to handle requests with different scenario. Character device, on the other hand, can accept any length of bytes as they like.

Device File and Device Driver

In our simple initramfs, we can see our console device file is controlled by a character device:

# Add this line in the init script `qemu-init.sh` then run.
$ busybox ls -l /dev/
crw------- 1 0 0   5, 1 May 21 12:43 console

If it starts with c then it means character device. And if it's b, it would be block device. Notice there are two numbers separated by a comma. These are driver's major number and minor number. The major number is a unique number tells you which driver is used to access the hardware. If you see multiple device file with same major number, they are controlled by the same device driver. The minor number is used by the driver to distinguish between the various hardware it controls. Imagine there's a storage hardware might contain multiple partitions, so there might be multiple device files in /dev with same major number. The device driver will use minor number to distinguish different partitions.

To create a device file, we can use mknod command to create the node. For example, mknod /dev/covfefe c 12 2 will create your device file dev/covfefe as character device with major number 12 and minor number 2. And since we use usr/gen_init_cpio to generate our initramfs, it also supports creating nodes with nod <name> <mode> <uid> <gid> <dev_type> <maj> <min>. So if you want to create console statically, you can add the line like nod /dev/console 0600 0 0 c 5 1.

While we can create device files from this for sure, this isn't the best way to do it because we might create files with conflicted major number accidentally. Kernel can create and generate major number dynamically nowadays. We could choose this approach instead. There are also another kind of module even suit for us. I will demonstrate it pretty soon along the way.

More File System Support

Before we proceed, I would like to introduce a few more file systems for us to mount. So we can interact to our character devices and get some more information about them. Let's add following configurations:

Run make menuconfig and check these options:

$ Device Drivers -> Generic Driver Options -> Maintain a devtmpfs filesystem to mount at /dev
$ File Systems -> Pseudo filesystems -> /proc file system support
$ File Systems -> Pseudo filesystems -> /sysfs file system support

In qemu-initramfs.desc, it should have these at least:

dir     /bin                                          0755 0 0
dir     /sys                                          0755 0 0
dir     /dev                                          0755 0 0
dir     /proc                                         0755 0 0
file    /bin/busybox  busybox                         0755 0 0
slink   /bin/sh       /bin/busybox                    0755 0 0
file    /init         .github/workflows/qemu-init.sh  0755 0 0

file    /rust_chrdev.ko  samples/rust/rust_chrdev.ko  0755 0 0
file    /rust_miscdev.ko samples/rust/rust_miscdev.ko 0755 0 0
# Other kernel modules...

Update our qemu-init.sh. You can add whatever commands you want to add. Just don't rmmod modules we just list. To interact with our character devices, we need a shell with job control enabled. The last line in init script is usually used for rescue shell, but it also works perfectly in our case. You can also unmount at the end of the script. But since we are not going to do anything afterwards, it's not really necessary.

#!/bin/sh

busybox mount -t devtmpfs none /dev
busybox mount -t proc none /proc
busybox mount -t sysfs none /sys
busybox insmod rust_chrdev.ko 
busybox insmod rust_miscdev.ko
busybox insmod rust_semaphore.ko
busybox setsid sh -c 'exec sh -l </dev/ttyS0 >/dev/ttyS0 2>&1'

Okay let's build the kernel and image again, run via qemu, and you should get the shell prompt. This time you should see devices created by devtmpfs, and it should also contain some we just installed:

$ busybox ls -l /dev
crw-------    1 0 0   10, 126 May 21 15:59 rust_miscdev
crw-------    1 0 0   10, 125 May 21 15:59 rust_semaphore
...

Device Registration and file::Operations

Alright! Let's see how does the code work, starting with rust_chrdev.rs.

struct RustChrdev {
    _dev: Pin<Box<chrdev::Registration<2>>>,
}

impl kernel::Module for RustChrdev {
    fn init(name: &'static CStr, module: &'static ThisModule) -> Result<Self> {
        pr_info!("Rust character device sample (init)\n");

        let mut chrdev_reg = chrdev::Registration::new_pinned(name, 0, module)?;

        // Register the same kind of device twice, we're just demonstrating
        // that you can use multiple minors. There are two minors in this case
        // because its type is `chrdev::Registration<2>`
        chrdev_reg.as_mut().register::<RustFile>()?;
        chrdev_reg.as_mut().register::<RustFile>()?;

        Ok(RustChrdev { _dev: chrdev_reg })
    }
}

First we can notice the module declares a new field with type of pinned chrdev::Registration. We create the instance via new_pinned with arguments name, module, and a number 0 indicate the starting minor number. Don't worry about what's Pin for now. We will discuss it in the future post. To register a character device, we call register method. It accept any generic has the trait file::Operations which we will explain later. In this case, we define a RustFile for it. Notice we can register the same kind of device twice because our type uses const generic and its type is chrdev::Registration<2>. This matches what we just said above: a device driver can control multiple minors. Next, let's shift our focus to RustFile.

struct RustFile;

impl file::Operations for RustFile {
    kernel::declare_file_operations!();

    fn open(_shared: &(), _file: &file::File) -> Result {
        Ok(())
    }
}

As you can see it doesn't contain many things yet. But the file::Operations trait actually has more methods can implement, we just define an pretty empty one first. The whole trait definition looks like this:

pub trait Operations {
    type Data: PointerWrapper + Send + Sync = ();
    type OpenData: Sync = ();

    const TO_USE: ToUse;

    fn open(context: &Self::OpenData, file: &File) -> Result<Self::Data>;

    fn read(
        _data: <Self::Data as PointerWrapper>::Borrowed, 
        _file: &File, 
        _writer: &mut impl IoBufferWriter, 
        _offset: u64
    ) -> Result<usize> { ... }
    fn write(
        _data: <Self::Data as PointerWrapper>::Borrowed, 
        _file: &File, 
        _reader: &mut impl IoBufferReader, 
        _offset: u64
    ) -> Result<usize> { ... }
    //...
}

All methods except open have default implementation which just returns EINVAL invalid argument signal. So types implement file::Operations trait must define open at least. The trait has two associated types OpenData and Data. OpenData is used for open method, it's passed as an argument when we call register. And Data is returned by open method and made available to other methods. Since we haven't done anything yet, they are both () for now and Rust can derive them automatically so we don't need to specify them explicitly.

Last, we have macro kernel::declare_file_operations!() to help generating TO_USE constant. It's a list of bool to decide which methods will be used as callbacks in the end. In our example, we do nothing for now, so all methods except open will be None (and hence be NULL in files_operation bindings.)

Miscellaneous Device Driver

We discussed that it's not safe to assign a major number to create device file manually. And when we called register method, it pass 0 under the hood which will let kernel dynamically allocate the major number. The newly registered device will have an entry in /proc/devices. We can see the major number by command busybox more /proc/devices. To make the device file, we can either call mknod command or use device_create function in C FFI manner. But we also have another choice which can create the device node when we just call register. It is called Miscellaneous Character Drivers.

Miscellaneous character drivers (short for miscdev) is a subset of character drivers which different drivers will all share the same major number and make minor numbers as their identifier. This is pretty useful when your driver only controls one device, because it will save all the unnecessary minor space. Running busybox more /proc/misc will show all miscdev's minor numbers. What's really convenient is when a miscdev is registered, kernel will create a device node under /dev right away. This suits us pretty well for our upcoming examples. So let's update our chrdev sample to become a miscdev and find how to interact with it! We'll create a module that can show some strings when it's being opened and read, such as cat /dev/rust_chrdev.

// Update your imports to these
use core::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use kernel::io_buffer::*;
use kernel::prelude::*;
use kernel::str::CString;
use kernel::sync::{Ref, RefBorrow};
use kernel::{file, miscdev};


struct SharedState {
    already_opened: AtomicBool,
    count: AtomicU64,
}

struct RustChrdev {
    _dev: Pin<Box<miscdev::Registration<RustFile>>>,
}

impl kernel::Module for RustChrdev {
    fn init(name: &'static CStr, _module: &'static ThisModule) -> Result<Self> {
        pr_info!("Rust character device sample (init)\n");

        let state = Ref::try_new(SharedState {
            already_opened: AtomicBool::new(false),
            count: AtomicU64::new(0),
        })?;

        let miscdev_reg = miscdev::Registration::new_pinned(fmt!("{name}"), state)?;

        Ok(RustChrdev { _dev: miscdev_reg })
    }
}

You will notice a few signatures have been changed but their types should still be similar. We now declare the module with miscdev::Registration and it accepts just a generic that has file::Operations trait instead. Parameters of new_pinned is also a little bit different because miscdev can take an argument for OpenData. This time we actually want to pass some thing for our driver. So we declare a new type SharedState which contains a few atomic types. Notice we also create the instance with Ref type. This is the reference counted pointer refcount_t in kernel which serve the same purpose as Arc in rust std.

In the multiple-threaded environment, without any protection, concurrent access to the same memory may lead to the race condition, and will not preserve the performance. In the kernel module, this problem may happen due to multiple instances accessing the shared resources. Fortunately, OpenData and Data in file::Operations are passed as immutable reference. You can't modify it unless you define with types that promise synchronization. We will introduce other concurrency primitives in later posts. For now, let's just use reference count with atomic combination to let processor handle for you. Now let's update our RustFile as well to see how it utilize SharedState:

struct RustFile;

impl file::Operations for RustFile {
    type OpenData = Ref<SharedState>;
    type Data = Ref<SharedState>;
    kernel::declare_file_operations!(read, write);

    /// Called when a process tries to open the device file, such as `cat /dev/rust_chrdev`.
    fn open(shared: &Ref<SharedState>, _: &file::File) -> Result<Ref<SharedState>> {
        if shared
            .already_opened
            .compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed)
            .is_ok()
        {
            shared.count.fetch_add(1, Ordering::AcqRel);
            Ok(shared.clone())
        } else {
            Err(EBUSY)
        }
    }

    /// Called when a process closes the device file.
    fn release(shared: Ref<SharedState>, _: &file::File) {
        shared.already_opened.store(false, Ordering::Release);
    }

    /// Called when a process, which already opened the dev file, attempts to read from it.
    fn read(
        shared: RefBorrow<'_, SharedState>,
        _: &file::File,
        data: &mut impl IoBufferWriter,
        offset: u64,
    ) -> Result<usize> {
        // Succeed if the caller doesn't provide a buffer or if not at the start.
        if data.is_empty() || offset != 0 {
            return Ok(0);
        }

        let msg = CString::try_from_fmt(fmt!(
            "This is my {} times saying Hello World!\n",
            shared.count.load(Ordering::Acquire)
        ))?;
        
        // Put the message to the buffer
        data.write_slice(msg.as_bytes())?;
        // Most read functions return the number of bytes put into the buffer.
        Ok(msg.len())
    }

    /// Called when a process writes to dev file, such as `echo "hi" > /dev/hello`
    fn write(
        _: RefBorrow<'_, SharedState>,
        _: &file::File,
        _: &mut impl IoBufferReader,
        _: u64,
    ) -> Result<usize> {
        pr_alert!("Sorry, this operation is not supported.\n");
        Err(EINVAL)
    }
}

We need to declare the type of Data and OpenData since we now want to share some states. They can be different types, but it doesn't need to in this case. In this example we use already_opened field which is a AtomicBool to determine whether the file is currently opened by someone or not and then add the counter.

This time we also have more operation methods, so we need to add them into declare_file_operations! macro. Usually the only required methods are open and release, so what we only need to list in the macro would be read and write. In read method, you can see how to create a message and put into buffer. While we don't do anything in write method, we still add this to demonstrate how to catch these attempts and tell the user that the operation is not supported.

Build and run the kernel again and you should find there's a device file rust_chardev under /dev and see how many times "Hello World" are being called via busybox cat /dev/rust_chrdev. Running command busybox more /proc/misc will show that is now a miscdev and you can get its minor number.

Device Unregistration

Last we need to talk about unregistration. We can not allow rmmod to remove the kernel module that is being used. When you call cat /proc/modules or lsmod, the third field is the counter of how many processes are using that module. It's increase when open is called and decrease when release. The check is performed by system call sys_delete_module.

Conclusion

Congratulations! Your kernel module start doing something. While it's not pretty meaningful, it will get more and more powerful as we add more types and functions into our tool belt. Next will be concurrency primitives like Mutex lock. But before we explore them, we will have to figure out why some types must be pinned.

Reference

The Linux Kernel Module Programming Guide: Character Device drivers

Rust Kernel Module: Hello World

2022-05-18T12:04:23+08:00

In previous post, we set up our environment to develop Linux kernel module in Rust. Now we can kick start our journey. Like every programming tutorial, we must start with a "Hello World" example. It is the law!

While there are already many samples under samples/rust directory, I'll still write a simple example to showcase how to add a module to our compiled kernel. Once you learn how to do it, you can add as many as you want.

The Simplest Module

To add a kernel module, there are a few files need to configure since we choose to compile Linux kernel on our own. But this is safer approach IMHO. This doesn't need to be the final workflow for you, but you should follow the safety measurement it obeys. First of all, let's add additional option to build a new kernel module called rust_hello. Try to add following configurations and files under other modules:

In samples/rust/Kconfig:

config SAMPLE_RUST_HELLO
	tristate "Hello"
	help
	  This option builds the Rust hello module sample.

	  To compile this as a module, choose M here:
	  the module will be called rust_hello.

	  If unsure, say N.

In samples/rust/Makefile:

obj-$(CONFIG_SAMPLE_RUST_HELLO)	+= rust_hello.o

Add a new rust file samples/rust/rust_hello.rs:

// SPDX-License-Identifier: GPL-2.0

//! Rust hello sample.

use kernel::prelude::*;

module! {
    type: RustHello,
    name: b"rust_hello",
    author: b"Rust for Linux Contributors",
    description: b"Rust hello sample",
    license: b"GPL v2",
}

struct RustHello {
    message: String,
}

impl kernel::Module for RustHello {
    fn init(_name: &'static CStr, _module: &'static ThisModule) -> Result<Self> {
        pr_info!("Rust hello sample (init)\n");
        pr_info!("Am I built-in? {}\n", !cfg!(MODULE));

        Ok(RustHello {
            message: "on the heap!".try_to_owned()?,
        })
    }
}

impl Drop for RustHello {
    fn drop(&mut self) {
        pr_info!("My message is {}\n", self.message);
        pr_info!("Rust hello sample (exit)\n");
    }
}

Build and Run the Kernel again

This is in fact just rust_minimal example with renaming. It's okay to skip adding this if you just want to learn how to do it instead of practicing yourself. To enable the module, run make menuconfig and toggle it to M in Kernel hacking --> Sample kernel code --> Rust samples --> Hello. Next, we have to build it and include it into our file system:

Build Linux kernel again. But this time, it should just build the kernel module we added:

make LLVM=1 -j$(nproc)

Build new image to include our kernel module. In .github/workflows/qemu-initramfs.desc, add another line under other modules and then build it again:

file /rust_hello.ko samples/rust/rust_hello.ko 0755 0 0

usr/gen_init_cpio .github/workflows/qemu-initramfs.desc > qemu-initramfs.img

Also add another command under other modules in .github/workflows/qemu-init.sh. This script is what we tell busybox to do upon initialization:

busybox modinfo rust_hello.ko
busybox insmod rust_hello.ko
busybox lsmod
busybox rmmod rust_hello.ko

Run the kernel via qemu again. This time you should see the log from the kernel we just built.

Command Helpers and Tools

We'll introduce a few commands relate to kernel module. modinfo will show the info of our kernel module. lsmod will show what modules are already loaded within your current kernel. Modules are stored within /proc/modules, so you can also see them with cat /proc/modules. inmosd will load the module you provide, and rmmod will remove it. If you follow this guide from the start, you should see the logs about kernel module when running qemu. But if you run the kernel natively, you can run journalctl to get the logs. Or if you are debugging with GDB like we mentioned before, run lx-dmesg in debugger to see them.

Now we know how to create, compile, and install the new kernel module. Let's see how the kernel module actually works. Before we deep dive into the code, please allow me to introduce a few tools and commands that will benefit us significantly. The first is documentation, Linux can build and read rustdoc for its kernel crate with this command:

make LLVM=1 rustdoc
xdg-open rust/doc/kernel/index.html

The documentation is pretty comprehensive, I believe many people can even read it themselves and learn even more beyond our guides could teach. Next is formatting and lints. Linux also supports rustfmt and clippy, so you shouldn't be afraid of inconsistent code style. Rust will guide you how to comply:

make LLVM=1 rustfmt
make LLVM=1 CLIPPY=1

Finally, we have language server protocol support. Yes! Linux supports rust_analyzer too! Run the following command to create rust-project.json configuration and you will gain full LSP support on whatever IDE you uses:

make LLVM=1 rust-analyzer

Macros and Types from `kernel` Crate

Alright! Everything is set! Let's see how does the code work. Unlike normal Rust program, we can't simply use standard library std. But we can still import core and alloc crates, types require heap allocation like String is still possible to use. And the most important crate is probably the kernel crate. It contains kernel APIs that have been ported or wrapped for usage by Rust code in the kernel and is shared by all of them. Like most rust crates, it provides a prelude module for us to import some common items.

The first one we must add is module! macro. This is the macro to declare a kernel module. You can see its description from documentation or even just hover it via rust-analyzer. You'll learn its usage, example, and all supported argument and parameter types. There are three argument types you must add to complete the macro:

type: The type we are going to implement the Module trait which we will demonstrate soon.
name: Your kernel module name.
license: Your kernel module license. Some examples include "GPL", "GPL v2", "GPL and additional rights", "Dual BSD/GPL", "Dual MIT/GPL", "Dual MPL/GPL" and "Proprietary".

To add logics for the kernel module, we can define any type as long as it implements Module trait. The trait's signature looks like this:

pub trait Module: Sized + Sync {
    fn init(name: &'static CStr, module: &'static ThisModule) -> Result<Self>;
}

The method init is equivalent to the module_init macro in the C API. We create the instance via this method. Since Rust ownership can manage our memory properly, it's not necessary to implement Drop trait which is equivalent to the module_exit macro in the C API. In our hello world example, we still do this to show when will the module exit.

Notice we use pr_info macro instead of println, but the usage is pretty similar. This maps to kernel's print macros. It follows most log level for different conditions. There are also other print macros like pr_err, pr_alert.

Passing Command Line Arguments to a Module

Modules can take command line arguments too, but not from env::args() you might used to. To allow arguments to be passed to your module, declare the parameter types in modules! macro. Let's see the example from samples/rust/rust_module_parameters.rs:

// SPDX-License-Identifier: GPL-2.0

//! Rust module parameters sample.

use kernel::prelude::*;

module! {
    type: RustModuleParameters,
    name: b"rust_module_parameters",
    author: b"Rust for Linux Contributors",
    description: b"Rust module parameters sample",
    license: b"GPL v2",
    params: {
        my_bool: bool {
            default: true,
            permissions: 0,
            description: b"Example of bool",
        },
        my_i32: i32 {
            default: 42,
            permissions: 0o644,
            description: b"Example of i32",
        },
        my_str: str {
            default: b"default str val",
            permissions: 0o644,
            description: b"Example of a string param",
        },
        my_usize: usize {
            default: 42,
            permissions: 0o644,
            description: b"Example of usize",
        },
        my_array: ArrayParam<i32, 3> {
            default: [0, 1],
            permissions: 0,
            description: b"Example of array",
        },
    },
}

struct RustModuleParameters;

impl kernel::Module for RustModuleParameters {
    fn init(_name: &'static CStr, module: &'static ThisModule) -> Result<Self> {
        pr_info!("Rust module parameters sample (init)\n");

        {
            let lock = module.kernel_param_lock();
            pr_info!("Parameters:\n");
            pr_info!("  my_bool:    {}\n", my_bool.read());
            pr_info!("  my_i32:     {}\n", my_i32.read(&lock));
            pr_info!(
                "  my_str:     {}\n",
                core::str::from_utf8(my_str.read(&lock))?
            );
            pr_info!("  my_usize:   {}\n", my_usize.read(&lock));
            pr_info!("  my_array:   {:?}\n", my_array.read());
        }

        Ok(RustModuleParameters)
    }
}

impl Drop for RustModuleParameters {
    fn drop(&mut self) {
        pr_info!("Rust module parameters sample (exit)\n");
    }
}

To add a parameter, we declare its type, default value, permission, and description. As we already saw the documentation of module! macro, it supports most primitive types. It can also support arrays via const generic ArrayParam<T, N>. At the time of this post, const generic only support numeric types, but this should cover most of our use cases.

In the init script .github/workflows/qemu-init.sh, insmod will fill the variables with any command line arguments that are given. The parameter that doesn't get the value from here will set to default value. We can pass the argument like this:

busybox insmod rust_module_parameters.ko \
    my_bool=n \
    my_i32=345543 \
    my_str=🦀mod \
    my_usize=84 \
    my_array=1,2,3
busybox  rmmod rust_module_parameters.ko

To read the values, some types require scoped lock, we can get it from module.kernel_param_lock(). Then you'll retrieve values from read() method. The lock will be dropped once it's out of the scope. Kernel parameters are usually used to have the module variable’s default values set, like a port or IO address. If the variables contain the default values, then perform auto-detection (explained elsewhere). Otherwise, keep the current value. This will be made clear later on.

Conclusion

And that's it! Now you should have the basic idea about how to write and build the kernel module. Feel free to play around with config files, scripts, and kernel modules either it's existing one or the one you create. The documentation is also comprehensive enough, I'm confident many people can even learn it themselves starting from here. But don't worry if you don't know how to proceed. I'll publish more posts in the future. Next time we will try to write another simple kernel module: Character Device drivers.

Rust Kernel Module: Getting Started

2022-05-04T12:04:23+08:00

Linux-next has Rust support for a while. While it's still not really in the mainline yet, the whole Rust stack in Linux is pretty solid already. From compiling to debugging, I can confirm the development workflow for Rust kernel modules is surprisingly seamless. In this post, I'm going to introduce you how to setup the development environment for Linux Kernel. So you can build the modules and test it.

I know setup whole kernel is incredibly cumbersome, and theoretically we can just build the modules from linux headers. In fact, the old project for Rust kernel module actually did this approach already. But testing programs without any kind of sandbox is dangerous and error prone. We should build common sense that sandbox is crucial for any project IMHO. Just bear with me throughout these steps. It's going to be easier and more fun after all of these.

Getting Started

To get the source code, we can clone the Linux repository from Rust-for-Linux organization:

$ git clone https://github.com/Rust-for-Linux/linux.git

Dependencies

Next we need to prepare all dependencies required. Quick start guide from Documentation/rust also lists all the requirements already. Feel free to follow it instead for this step.

System Requirements

The first one is of course all dependencies for compiling the kernel. For some distributions, they might already ship some of the packages. I'll only provide commands for debian-related distributions. But others should follow the same:

$ sudo apt install libncurses-dev flex bison openssl libssl-dev \
    dkms libelf-dev libudev-dev libpci-dev libiberty-dev autoconf

QEMU & GDB

And then is tools for testing and debugging, this includes all dependencies required from QEMU and GDB. In later post, we'll show how to run and debug kernel via attaching QEMU to GDB.

$ sudo apt install qemu qemu-system qemu-kvm libvirt-daemon-system \
    libvirt-clients bridge-utils
$ sudo apt install gdb

LLVM (or libclang)

For simplicity, we will compile the kernel with LLVM. This is because we will use bindgen to help Rust connect to the C code which requires libclang. We will compile the kernel with LLVM=1, or if your distribution doesn't support full toolchain, use with CC=clang. Again, most distributions should ship with LLVM already. But if you are afraid of missing anything, run the following command:

$ sudo apt install llvm lld libclang-dev

Rust

For your sanity, I really recommend download and install Rust from the official site and remove other versions installed from other package managers. But if you insist, Documentation/rust should also cover that. For the time of this post, Linux is still stick to a certain Rust version instead of stable. To get the toolchain of that version, run the following commands:

$ rustup override set $(scripts/min-tool-version.sh rustc)
$ rustup component add rust-src # Rust standard library source

And we also need to install bindgen:

$ cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen

Compiling Kernel

Alright, this is where the fun begins! We are ready to compile the Linux kernel. Before we start, let's check again and make sure the toolchain is correct:

$ make LLVM=1 rustavailable

This will use the same logic by Kconfig to determine if RUST_IS_AVAILABLE should be enable. When you get a fresh kernel, it usually starts with make menuconfig to create the .config file. While we can use it to toggle the Rust support and all modules we want to build, we can also copy existing one from its CI workflow. We could get the most similar configurations from the upstream. In this post, I will assume you are under x86_64 architecture. If it's not, please take a look of its ci.yaml and choose the closest possible config for you.

$ cp .github/workflows/kernel-x86_64-debug.config .config

AAAAAAAAAAAAAAAAAAAAAND COMPILE!

make LLVM=1 -j$(nproc)

Take a coffee or go for a walk. It will take some time to complete. Once the compilation is done, you should found the kernel binary image under arch/x86/boot/bzImage in Linux source directory.

Build initramfs

Now we have the kernel, we could run with QMEU right? Well not quite, we still need a root filesystem for the kernel. Starting from here, there could be multiple approaches. Depends on your need, it could be totally different. I would say there's no one true ring to rule all of them. For example, You can use Buildroot to setup as your drive. For us, we can just follow how CI does: Building initramfs. If you don't know what is initramfs, here's the quote from Linux kernel documentation:

All 2.6 Linux kernels contain a gzipped "cpio" format archive, which is extracted into rootfs when the kernel boots up. After extracting, the kernel checks to see if rootfs contains a file "init", and if so it executes it as PID 1. If found, this init process is responsible for bringing the system the rest of the way up, including locating and mounting the real root device (if any). If rootfs does not contain an init program after the embedded cpio archive is extracted into it, the kernel will fall through to the older code to locate and mount a root partition, then exec some variant of /sbin/init out of that.

I hope you got it, because I'm going to introduce another tool we need: busybox. And I'll also drop another quote for you to understand:

BusyBox combines tiny versions of many common UNIX utilities into a single small executable. It provides replacements for most of the utilities you usually find in GNU fileutils, shellutils, etc. The utilities in BusyBox generally have fewer options than their full-featured GNU cousins; however, the options that are included provide the expected functionality and behave very much like their GNU counterparts. BusyBox provides a fairly complete environment for any small or embedded system.

Whew that's quite a read. Don't worry about not fully understanding what they do. Because we only care about the setup and how to create the image for now. We'll come back to this if we really need some advanced configurations. The project itself already offer a script for us to create image:

$ wget https://www.busybox.net/downloads/binaries/1.35.0-x86_64-linux-musl/busybox
$ usr/gen_init_cpio .github/workflows/qemu-initramfs.desc > qemu-initramfs.img

qemu-initramfs.desc might contain modules we didn't build. Just remove those lines if you get the errors.

Running on QEMU

Alright! This time is real. We are going to start QEMU on the compiled kernel:

In case you don't know how to exit ~~vim~~ qemu: Ctrl+A then X

$ sudo qemu-system-x86_64 \
    -kernel arch/x86/boot/bzImage \
    -initrd qemu-initramfs.img \
    -M pc \
    -m 4G \
    -cpu Cascadelake-Server \
    -smp $(nproc) \
    -nographic \
    -vga none \
    -no-reboot \
    -append 'console=ttyS0'

See QEMU's Invocation if you want to understand what each parameter does. If everything runs smoothly, it should look like this:

Hooray! You just built a Linux kernel with Rust kernel modules loaded!

Debugging with GDB

Before we end the post, there's one more thing we haven't done yet. Running the kernel is one thing, how to debug it is another. While it's definitely a huge topic, I would like to give an entry point to let everyone know how to start the first step at least.

To enable debugging, we need to make sure option CONFIG_GDB_SCRIPTS is on and CONFIG_DEBUG_INFO_REDUCED is off when building kernel. If you configure with make menucofig, you can use / to search these options and find their path to toggle. Build the kernel with make LLVM=1 -j$(nproc) will create the kernel with symbols we need. With incremental compilations, it should take way lesser time to complete. This is also true when we focus on kernel modules later. We just need to compile the modules afterwards.

Once it's finish again, you should see vmlinux and vmlinux-gdb.py in the root of project. vmlinux is the target for GDB and vmlinux-gdb.py is pre-defined GDB helpers. To get the commands (lx-*) defined in vmlinux-gdb.py, we add the script file to GDB’s auto load path. Some usages of the commands can be found in GDB Kernel Debugging Page.

$ echo "add-auto-load-safe-path path/to/vmlinux-gdb.py" >> ~/.gdbinit

Let's run the kernel on QMEU again, but this time with a few more parameters added:

$ sudo qemu-system-x86_64 \
    -kernel arch/x86/boot/bzImage \
    -initrd qemu-initramfs.img \
    -M pc \
    -m 4G \
    -cpu Cascadelake-Server \
    -smp $(nproc) \
    -nographic \
    -vga none \
    -no-reboot \
    -append 'console=ttyS0 nokaslr' \
    -s -S

We add nokaslr boot parameter because GDB doesn't work well with KASLR on. We also use -s -S combination to hold QEMU from booting the kernel until a GDB instance is attached. Now let's create another shell window to start GDB and attach then to QEMU. Starting from here we can now set breakpoints and debugging the kernel.

$ gdb vmlinux

(gdb) target remote :1234   # Attach to QEMU
(gdb) hbreak start_kernel
(gdb) c
(gdb) b mm_alloc
(gdb) c
(gdb) lx-dmesg  # Display kernel dmesg log in GDB shell
(gdb) ...

Conclusion

Okay we are finally done with building our first kernel. While this is just the first step, I believe this is the most difficult one and it will be more and more interesting from now on. In the next post, we'll start exploring the joy of writing kernel modules!

Reference

https://mirrors.edge.kernel.org/pub/linux/kernel
https://wiki.gentoo.org/wiki/Custom_Initramfs
https://busybox.net/FAQ.html
https://www.qemu.org/docs/master/system/index.html
https://github.com/d0u9/Linux-Device-Driver/blob/draft/02_getting_start_with_driver_development/03_build_initramfs.md
https://www.josehu.com/memo/2021/01/02/linux-kernel-build-debug.html#fn:2

Overview of Servo

2022-04-21T12:04:23+08:00

Before we deep dive into the code base of servo, I guess it's better to have a high level overview of it. Servo is a huge project and it contains over million lines of code. Sometimes it might be diificult to graspe where are you looking at or how each component interact with others. Getting a high level overview could help you building your own mental model. So let's get started:

And that's it! Don't worry about what is each component and how do they do. We'll talk about them along the way. And of course it still simplifies and ignore many parts. These include Webrender, Surfman, Mozjs, and many other web features like WebXR, media, and WebGPU etc.

What this overview trying to represent is how the main trunk of Servo looks like and where is the part handles web pages mostly. There are other processes and threads, but they will behave similar to how pipelines do.

Constellation

Let's start with the main process. There isn't actually a module called main process. But this helps us to understand who takes the big part in the center of Servo. Every rectangles it contains is a thread. Threads with plural name mean they could be multi-threads.

The most important thread we want to focus on is the "Constellation". It is the centeral station of the engine. It stores core states of the engine like "User Agent" and also handles any workflow involving several components. The constellation the unique thread in Servo and there's no the other one. This means it couldn't get the deadlock and is also responsible for crash reporting.

Interestingly, the constellatiion doesn't receive all messages from other processes directly. Main process has a IPC Router and receiving messages is its job instead. Every arrow you see is a Channel. This allows the router thread to use select! macro to re-route all IPC messages. The router also allows other threads in other processes to register callbacks to do some operations.

Embedder

Embedder itself in servo is actually just a few traits. It's a interface requires code who uses servo to implements. Thinking it's like several methods servo need users to define. So the implementation would be able to receive message from servo and handle its own event loop. For servo's demo, it uses winit's event loop and implements those traits for it.

Compositor

Graphic compositor is a thread renders the necessary pieces of the web pages. This includes iframe, animation and scroll bars etc. You can think it as a layer design to show what parts should be painted on the screen eventually.

Resource Thread

Resource thread's purpose is just like the name itself. Getting the resources from I/O, either from network or file system. It's a bit weird to include this thread into the main process instead of pipeline. But it will be created soon after constellation, because it will have to load some initial assets real soon. It's the few thread that doesn't communicate via IPC router. Script threads in pipeline are able to talk to it directly.

Pipeline(s)

A pipeline is a process for servo to load your page and maintain it. It's servo's view of a "web page" or a "iframe", or we could just call it a "Window". When the constellation want to load an url, it will get or create a "BrowsingContext". It's servo's view of "WindowProxy" and it contains several states related to the page like session history. The constellation will spawn a pipeline and pair with it. You can treat them like a key value pair of a HashMap.

And yes, you can see there's a IPC router again. This is just like how main process routing incoming messages.

Script Threads

Script thread is the "main thread" of a pipeline. It runs the window event loop of a web page that belongs to the same BrowsingContext and Origin. A pipeline could possibly share the same script thread because thread itself could potentially process multiple iframe with same origin.

Script threads also connect the javasvript engine: Spider Monkey. In Rust, it's a wrapper crate called mozjs. Script itself defines the webIDL interface to communicate with it.

Layout Threads

For each pipeline, it will spawn a layout thread and it doesn't share between pipeline. It process DOM tree and stylist created from CSS selector to produce the display lists. These lists are used for final graphic rendering. For example there might be a list to tell we need to render a rectangle and a triangle.

Web workers

And of course there will be web workers running scripts in the background. But the web workers shown in the picture is more like dedicated workers belong to script thread. There could be another process that has standalone web workers running other web features.

What's next

There you have it! This is basically how the overview of Servo could look like. There are indeed many more processes and threads. But you should already get the insight and idea how will they interact and communicate. In the next post, we'll see how an url being loaded and its journey to finally being rendered.

Getting Started with Servo

2022-04-03T12:04:23+08:00

Servo is a browser engine developed by Mozilla and now running individually. It shared many philosophies from gecko and one of its original goals is to make more components in a browser more modular. Despite it's not pretty active after the layoff of Mozilla, there are many crates still being maintained pretty well. Crates like url, html5ever, selector are widely used by many organizations like Deno, Vercel, and Rome. There are also non-web related crates that are actually came from Servo too, such as bindgen, core-foundation, brotli. Servo itself shaped the foundation of many rust ecosystems and is still worth exploring it IMHO. It still has the potential to become a competent engine for general usage. I would like to encourage people to participate Servo again and getting familiar with it. And perhaps in the future, we can push its boundary further. In this post, I want you to let you know how to run a minimum demo to play around with it.

Setting up environment

Aka the most difficult part.

Setting environment is usually the least interesting part, but bare with me, it will become better after this step. Basically you should just need to follow these instructions from Servo's README and it will be good to go.

Building

Mozilla has a passion that really really likes to utilize python scripts for building projects. So in Servo, it uses ./mach build scripts to do most jobs. Servo comes with two build mode: dev and release. One for developing and debugging purpose, the other for optimized build. To build the project, run one of the following commands:

./mach build --dev
./mach build --release

This will build library crates under components directory and build winit port binary. There are other ports can be built, but winit one is the most common option when developing it.

Since this is a fairly large project, it usually takes several minutes to complete the build. If you are developing it and just want to check build errors, you can run this command:

./mach check

Running

To run the winit port binary, we could run one of the following commands with file path or url as argument:

./mach run --dev [url/path]
# For example
./mach run --release https://www.google.com

Unlike cargo run, this will not run the build command again. It executes the built binary directly and open a window as a web page. There are more arguments and shortcut listed in Servo's README.

Testing

There are several test suite with commands to run them. But what we care about the most right now is the compatibility of wpt.fyi. It's a test suite to check how complete a web engine is. Wpt runs daily pipeline for Servo, and Servo also include these tests too. To run a wpt test, we can choose one test under tests/wpt directory and run following command:

./mach test-wpt tests/wpt/mozilla/tests/mozilla/input_value.html

You can also just run the directory, it will run all tests under that directory. As the time of this post written, the main focus is full coverage of CSS 2 which tests can be found at tests/wpt/web-platform-tests/css/CSS2. We will talk about wpt testing and how to debug them in the future posts.

Documentation

The generated documentation can be found on official website. But of course this means only default features. If you want to see the documentation from different features, you can go with ./mach doc.

Summary

That's pretty much it! There are definitely more commands and tools you can use. You can run ./mach --help or browse Servo's wiki search them. In the next post, I would like to talk about the overview structure of Servo. So people can get the idea how it looks like and could dive into the part they are interested the most.

Mutex 的大小

2022-03-24T12:04:23+08:00

以下討論的鎖全以 x86_64-linux-gnu 目標為準

一個簡單的 futex 在 Linux 上是 4 bytes 而已，不過 pthread_mutex_t 為了支援一些額外的功能，所以最後是 40 bytes。這些功能包含像是 reentrance 和 robust 等等。一個 robust mutex 會在擁有該鎖的執行緒死亡時自動釋放，讓其他執行緒在必要時能清理殘骸。不過這些 flag 預設都是關閉的。

同樣地，在 glibc 中 pthread_cond_t 是 48 bytes，也提供了不少額外功能像是防止錯誤的喚醒、儲存 flag 紀錄哪些核心在用且是否有被共享。但是在 Boost 的 condition_variable 又多存了一個 mutex，所以加總其來是 88 bytes，這個額外的 mutex 是用來支援執行緒的取消與中斷。因為 pthread_cond_wait 會在回傳前重新鎖住 mutex，這樣在 mutex 是鎖住時是無法中斷的，所以 Boost 改在每個條件變數(condvar) 都加一個 mutex 來等待。

而不像 pthread_rwlock_t，Boost 的 shared_mutex 能夠將 reader 升級成 writer。該實作是用一個 40 bytes 的 mutex 保護一個 4 bytes 的狀態，並用到了三個 88 bytes 的條件變數：一個給 reader、一個給 writer、一個給升級用。最後加上 padding 就是 312 bytes。

最後 Rust 的 Mutex 本質上就只是 Box<pthread_mutex_t>，一樣是 40 bytes，不過會被分配到 heap 上。

你想要多安全的記憶體安全？

2022-02-13T12:04:23+08:00

記憶體安全通常是指針對軟體在處理記憶體存取時的措施手段，像是防止 Buffer Overflow 或 Dangling Pointer 等等。大多數擁有 Garbage Collection 的語言會在 Runtime 自動幫忙管理記憶體，而且不會暴露出太危險的抽象化型別給使用者直接使用。但在 C 和 C艹則允許在沒有任何防護或檢查下，直接使用指標直接操控記憶體位置，我們通常就會稱這些語言是記憶體不安全的語言。

為何我們需要討論記憶體安全?

我們之所以一而再再而三地討論並思考記憶體安全性的問題，無非是因為仍有非常多的軟體程式仍然是用記憶體不安全的語言寫出來的，且很多仍得繼續使用而造成維護的困難。這些很多是效能敏感的程式，無法負擔 Garbage Collector 在 Runtime 上產生的開銷。抑或是歷史的包袱，複雜的架構已經無法再改用其他語言重寫或維護。

當我們仔細分析像是 iOS/macOS、Android、Windows、cURL 這些重要的專案，我們可以發現所有專案的 CVE 有 60 ~ 90% 全都是來自記憶體安全相關的錯誤。用比較負面的觀點來說的話，也就是會有這些記憶體安全的錯誤全都只是因為用了 C 和 C艹來寫。

不過當然隨著時代在進步，C 和 C艹的生態系也出現不少檢查工具鏈來改善，除了 Valgrind 能用來檢查記憶體洩漏，其他還有像是 AddressSanitizor、ThreadSanitizor 能來分別檢查記憶體位址與執行緒的安全。上面分析 iOS/macOS 的文章就可以看到，記憶體安全的錯誤比例有逐年遞減到約略 60% 左右。

但能視為通用程式語言並用在系統開發上的語言當然不是只有 C 和 C艹而已。早在 1980 年就已經有 Ada 語言存在，並廣泛運用在美軍的系統程式上。而甚至有人開發過 Lisp 機器嘗試將 Lisp 作為該電腦的主要開發語言。

而近年來還有許多新興的程式語言能選擇，有些承襲了些傳統語言預設會去做的檢查並在編譯時就做好優化，有些甚至帶來了有趣的概念像是 Rust 的所有權與 Borrow Checker 來治本解決根本性的問題。許多諸如 Linux 的 Kernel Module、Amazon 的虛擬化技術 Firecracker、Google 的 Android 與 Chrome 甚至是 Fuchsia 以及 Windows，這些大型企業以及開源的專案都開始嘗試使用 Rust 來寫。

那該選擇哪些記憶體安全語言?

所有具有 Garbage Collection 的語言都算是記憶體安全的語言，盡管在執行時會有一定程度的開銷，但是它們可沒有想像中的那麼笨重緩慢不堪。JVM 和 .NET 都有十分強而有力的 Garbage Collector 實作，如果無法完全理解記憶體與抽象指標的概念，或是手動的記憶體管理反而是負擔的話，仍然非常推薦有 Garbage Collection 的語言像是 Elixir、F# 和 Racket 等等。

但很多時候不如在一開始就搞定問題，Garbage Collector 產生問題時要解決的時間與人力成本也不亞於非記憶體安全的語言，最常見就像 Java 的記憶體卡在老生代釋放不掉造成 Out of Memory，且並行程式下也可能防止不了 Data Race。在 Oracle 和 Line 等企業中都得培養整個部門團隊去維護優化它們的 JVM。

回到不用 Garbage Collection 的語言，像是 C 和 C艹也不是都沒在做檢查，除了上述提到的檢查工具，也有許多標準規範像是 MISRA C 來限制。不過這些畢竟不全是預設行為，對自己的要求標準高，其他的開發者或團隊可能並沒有跟你站在同個標準上。所以使用 Ada 和 Zig 這些預設在編譯時就會做諸多記憶體安全檢查的語言會是我推薦的選項。在先不討論 Allocator 的情況下，要在 Zig 做記憶體不安全的行為是要明確指定的，從 Build Mode 就可以略知該程式提供的保障到哪。

接下來我們還有 Rust，所有權和 Borrow Checker 能在編譯時釐清記憶體的歸屬問題，任何人都能夠寫出既迅速又安全的程式碼，讓魚與熊掌可以兼得。而所有權當然其實和 C艹的 RAII 類似，且 Borrow Checker 在做的也是我們平時在寫程式時腦海裡就會勾勒出的藍圖。然而讓編譯器也一同檢查比你自己一個人檢查更清楚多了，有許多專案重寫後還發現原來沒找出的 bug。

這些語言有多安全?

最後我想我們可以來看看上述的語言相比到底多安全。確實使用 C 夠謹慎的話，的確能一掃所有記憶體安全問題。寫 Rust 使用 unsafe 也能把 Undefined Behaviour 玩得天花亂墜。但我們想知道在預設行為下，這些語言到底提供了怎麼樣的保障。Garbage Collection 的語言不用說，本文提到的多數問題應該都不必煩惱。至於 C、Zig 與 Rust 相比的話，我們有以下 Jamie Brandon 整理的列表:

問題	C	Zig	Rust
Out-of-Bounds Heap Read/Write	❌	⭕️	⭕️
Null Pointer Dereference	❌	⭕️¹	⭕️¹
Type Confusion	❌	⭕️²	⭕️
Integer Overflow	❌	⭕️	❌³
Use After Free	❌	❌⁴	⭕️
Double Free	❌	❌⁴	⭕️
Invalid Stack Read/Write	❌	❌	⭕️
Uninitialized Memory	❌	❌⁵	⭕️
Data Race	❌	❌	⭕️⁶

上面的列表我有更改一些，以確定真的都是預設的行為。在 Zig 我們討論的是 Debug / ReleaseSafe Mode，而 Rust 則是 Debug / Release Profile。而有附上數字的欄位就是接下來需要近一步解釋，或是某方面其實還是能視為安全的地方：

其實就是提供 Option 型別作為第一公民。
只有 Union 會造成型別混淆，雖然 Zig 可以用 enum 組合成 Tagged Union，但這必免不了持有指標數值的同時更改 Tag。
在 Debug 時 Overflow 會 Panic，在 Release 則是會 Wrap。實際在做數值運算時通常都是使用型別提供的方法像是 wrapping_add 或 overflow_add 來確定想要的行為。
Zig 的作者 Andrew Kelley 有解釋其標準函式庫提供的 Allocator 會防止這些常見的記憶體分配錯誤。C 也有像是 hardened_malloc 的概念，不過並沒有什麼標準函式庫，預設就能拿來使用。
Zig 的安全檢查會檢測未初始化的記憶體，且使用的關鍵字是 undefined。在 Debug 時寫入的值是 0xaa 以方便做檢查。
所有權和 Borrow Checker 能完全杜絕 Data Race，我發現這是很少被提到的，在有些 Garbage Collection 的語言甚至沒有辦法完全防範。

最後有一些問題並沒有列上去，因為這在所有語言都存在，而且有時候是刻意為之的：

Race Condition：因為整個系統本質上就在互相爭奪資源的寫入與讀取，當程式需要依賴這些系統進行操作的話，難免會在非常極端的狀況出現微妙的問題，而且有時是非常難以重現的，這個我覺得值得獨立一個話題討論。
Memory Leak：記憶體洩漏不像其他行為會觸發到 Undefined Behaviour 進而造成程式錯誤，而且有時候是刻意洩漏的。在 Valgrind 的檢查中洩漏就被分成好幾種類別，有些其實使用者自己知道且仍在掌控中。

fn 與 Fn

2021-01-01T12:04:23+08:00

大家在其他語言中大部分的時候可能可以將 fn 與 Fn 視為同樣的語意來處理，可是這在 Rust 中會需要多一些操作，比方說以下的做法就是不可行的：

fn foo<A, B>(f1: Fn(A) -> B, f2: Fn(B) -> A) {
    todo!()
}

因為 fn 才是函式（更確切地說是函式指標），而 Fn 是 trait，我們得改成用 fn 或是真的要用 Fn 的話則是採用泛型 impl trait 甚至是 Trait Object &dyn trait 等等。選擇 impl trait 的話會寫成像這樣：

fn foo<A, B>(f1: impl Fn(A) -> B, f2: impl Fn(B) -> A) {
    todo!()
}

會有這樣的差別的原因是，除了普通的函式以外，閉包也擁有 Fn trait，閉包通常會再有個 context struct 來保存狀態，在大多數的語言中會選擇 Box 起來變成同樣的指標，讓型別之間的區別抹去。在 Rust 預設則不是如此，型別之間的區別是存在的，所以真的想在執行時視為同樣的型別處理，我們就會用 Trait Object Box<dyn trait>，但這樣就是動態調度（Dynamic Dispatch），和其他語言一樣會有額外的開銷。

Fn 預設的行為則不然，它是 trait，用在泛型上會是靜態調度（Static Dispatch），在執行時是沒有任何額外的開銷（不過因為是靜態的，你的程式碼大小的確會增加）。有趣的是 fn 因為是指標，所以拿來當作參數使用的話其實是動態調度的，和使用 Fn 的泛型靜態調度有一點不一樣。詳細的區別可以看看以下例子：https://godbolt.org/z/bexE6v

#![feature(test)]

#[inline(never)]
fn foo() {
    std::hint::black_box(());
}

#[inline(never)]
fn bar() {
    std::hint::black_box(());
    std::hint::black_box(());
}

pub fn run1() {
    #[inline(never)]
    fn run(f: fn()) { f() }
    run(foo);
    run(bar);
}

pub fn run2() {
    #[inline(never)]
    fn run(f: impl Fn()) { f() }
    run(foo);
    run(bar);
}

而產生的組合語言則是如此：

example::foo:
        push    rax
        mov     rax, rsp
        pop     rax
        ret

example::bar:
        push    rax
        mov     rax, rsp
        pop     rax
        ret

example::run1:
        push    rax
        lea     rdi, [rip + example::foo]
        call    example::run1::run
        lea     rdi, [rip + example::bar]
        pop     rax
        jmp     example::run1::run

example::run1::run:
        jmp     rdi

example::run2:
        push    rax
        call    example::run2::run
        pop     rax
        jmp     example::run2::run

example::run2::run:
        jmp     example::foo

example::run2::run:
        jmp     example::bar

run1 會接受的參數是個指標，而 run2 才會確切呼叫實際個別函式。

在 Rust 中讓型別能夠跨執行緒的方法

2020-12-30T12:04:23+08:00

最近我需要用到 Cache 的功能，但在 crates.io 找了一遍後並沒有滿意的 crates，大部分都包含了 unsafe 與裸指標的引用。我自己並不排斥 unsafe 的使用，只要有詳細的註解能讓我理解使用的必要原因就好。不過這些都沒有跑過 miri，而與其要解決出錯的未定義行為，我覺得不如自己寫一個最適用於自己使用情境的一個還比較實際。所以寫了一個之後，我在 benchmark 的同時剛好需要讓該型別能跨執行緒使用，加了一些簡單的修改後我發現這個或許能幫助到剛好正在學習怎麼寫 concurrency 的人，所以我把修改時的思路與過程記錄下來。

當然在現在的程式設計中也有許多其他技巧可以使用，像是 channel、atomics 或者 lock-free 等等。但在這邊只是要用最簡單的方式而已：開多條 thread 並使用互斥鎖。這樣的方式雖然簡單，但沒有處理好的話卻也常常造成許多錯誤。不過在安全的 Rust 中就提供了許多保障，讓你在使用它們的同時就免除了許多不必要的危害。

雖然 Rust 能幫你預防 data race 甚至所有記憶體不安全的問題，但 race condition 仍然是會發生的，因為整個系統環境本來就是在互相競爭的，使用者還是有可能寫出死鎖。

首先 Rust 大部分的基礎型別都有 Sync 和 Send traits，以這些定義的型別也會擁有這些 traits，這用來表明該型別是可以安全在執行緒間同步與傳遞的。不過因為所有權的關係一個數值就算有這些 traits 也只能被一個 thread 所擁有，要讓多條 thread 可以擁有同個實例的話，通常我們就會使用 Arc 型別，此型別在 clone 時不會複製數值，而是仍引用原本的實例然後增加原子引用計數。Arc 型別擁有 Deref trait 讓使用者可以拿到原本的引用。不過此引用是不可變的引用，想要拿到可變得用的話，我們就會再繼續加上 Mutex 來繼續取得可變引用。所以通常要讓一個型別可以跨執行緒並可變的話，我們會很直覺地使用 Arc<Mutex<T>>。 而且這些型別的 API 仍然遵守著 Rust 的所有權與生命週期規則，這直接讓 Data Race 的產生成為不可能。

不過我所實作的 Cache 內部還分成了數個 shard，所以與其將整個型別用 Arc<Mutex<T>> 包起來，我採用了別種選擇：讓 Mutex 鎖的是各個 shard。這樣當某個 shard 被鎖起來時，其他 shard 在別條 thread 仍能使用。而在此 commit 短短幾行修改中，產生了一些有趣的變化，在之後的 benchmark 時我發現變的更好使用了！

首先，我對每個 thread 加上了 Mutex，而要取得每個 shard 的話就是呼叫 lock().unwrap()。取鎖得到的回傳值是一種 Result 型別的原因是因為要是該鎖在其他 thread panic 的話就會被污染。被污染的鎖就會回傳 Err。不過要是確定 thread 不會 panic 的話，直接 unwrap 是不會有問題的，以我自己的經驗要是真的在除錯時也比較容易。這邊最有趣的地方在於原本需要 &mut self 的方法可以改成 &self 就好了，因為 Mutex 提供的是內部可變性，lock() 的需求也只要 &self。

這邊沒有加上 Arc 的原因是因為是使用者才要決定要不要傳給其他 thread，所以使用者不需要的話他們本來就能直接使用，而需要跨執行緒的話，他們就會本能地使用 Arc 包裝起來，而且因為所有方法都只需要不可變引用，所以他們不必再定義 Mutex(要真的定義也不是不行，只是最後會發現完全不需要鎖)。這樣一來就完成能夠跨平台的型別，確保外部不變的同時，提供內部可變性。

以上是快樂的部分，而在剛剛的 commit 中有再定義另一個型別，這則是比較惱人的部分。或者說「遇過太多次這樣的錯誤，所以下意識就會寫的部分」，在剛剛的 commit 中有再定義另一個型別：

pub struct LookupRef<'a, T>(MutexGuard<'a, LRUCache<T>>, usize);

impl<'a, T> LookupRef<'a, T> {
    /// Get the value of the lookup reference and actually update the entry to the head of its
    /// cache shard.
    pub fn value(&mut self) -> Option<&mut T> {
        self.0.lookup(self.1)
    }
}

這是因為 lock() 的回傳值 MutexGuard 是個引用型別，其產生的引用的生命週期當然不能超過它，不然就無效而無法擁有鎖提供的保障了。在 Cache 的 lookup 會希望取得該值的引用，所以常見的做法是把 MutexGuard 延長給使用者，在那裏使用完後才釋放鎖。

以上就是要讓型別跨執行緒時常見的思路，除了 Mutex 以外，RwLock 與 Atomic 型別也都適用這樣的思維。在一開始使用這些型別時，的確可能會覺得卡卡的。但習慣後會發現實際要寫的程式並不多，而且可以安全地定義並使用，享受 fealess concurrency 帶來的好處。

Webassembly 與它們的產地

2020-11-17T16:55:00+08:00

最近看到大家又再討論 Webassembly，讓我想起以前就想寫篇總結了。這篇是我目前接觸 Webassembly 社群大致上的見解，希望可以讓大家能更清楚 Webassembly 的全貌並排除掉一些錯誤的見解。

所以什麼是 Webassembly？

Webassembly 簡稱 wasm 是個可攜式的位元組碼（bytecode），讓開發者可以用自己喜歡的程式語言編譯然後能在不同的系統或平台上快速且安全地執行，而且現在已經能用各大瀏覽器的虛擬機引擎執行。

坦白說這當然不是什麼新點子，同樣的事情 JVM 與 .NET 都做過了，而且都已有一定的影響力並都在自己的市場站穩了腳步。那為何又要重造輪子一次呢？首先來看 JVM 的話，它已經有超過 20 年的歷史了，它原本是為了處理一個程式語言 Java 而設計的，而且是在網路的樣子成熟之前就出來的，當時有很多的設計思維與現在多少有些許的落差，當時甚至不確定 Garbage Collection 的設計對於現在高階且高效的程式會這麼有影響力。至於 .NET 我覺得就真的有點微妙，它在各方面的確做得很好，而且最近又出了 .NET 5 速度與效能又更好了。也許是因為它被微軟的開發生態綁死在一起了吧，就像 Apple 的 Swift 或 Cocoa 框架那樣。

所以有不少原因與動力，況且也沒真的有人阻止大家再去定義出一個更通用、不被特定財閥綁架、且兼容於各個語言的 bytecode 系統與 JIT 編譯器。另外 Webassembly 也有不少優點，像是它不像前者一定需要 Garbage Collector，它沒有許多複雜的型別概念像是 generic 、 class 甚至是 structure，還有更簡單的命名空間（namespace）與連結/讀取模型。所以可以看到它比 JVM 或 .NET 還更像是機器語言。讓其他相對低階的語言像是 C/C++ 和 Rust 也能編譯成其目標（理論上）也不會有 overhead。

經過社群多年的努力，現在所有瀏覽器都支援 Webassembly 了，我也看到不少專案甚至是企業將負擔較重的程式碼段落，像是運算或解析，轉成使用 wasm module 了。而且更棒的是 Webassembly 不只能用在瀏覽器上，別忘了 Webassembly 本來就是 bytecode。它當然可以 port 並跑在任何系統的沙盒上。能讓執行檔與函式庫以 bytecode 形式發布並在不同的平台本地端編譯可以說是最吸引我的賣點了。這對我來說這幾乎能直接取代發布特定系統執行檔這樣的方式。（當然沒人阻止你直接拿原始碼編譯，不過這是另一個話題了）隨著系統架構越來越多元，各領域的開發者們越來越需要考慮到不同平台的支援，這樣的點子我覺得會在近未來成為顯學。Docker 創辦人 Solomon Hykes 甚至發過推說如果 WASM/WASI 在 2008 年就問世的話，根本就不需要有Ｄocker 了。

不過當然 Webassembly 也不是沒有讓人困擾的地方，像是它是從 32 位元開始的，我有點不解為何不一開始就將 64 位元也考慮進去。許多基本的元件像是 interface type 也還在擬稿中。對於系統的介面支援 wasi 也還在進行中，所以只有 Webassembly 是無法呼叫執行緒或開啟檔案等等的。不過先撇除這些瑣碎的不便之處，Webassembly 真的已經開始在真實世界使用了！

所以該怎麼寫 Webassembly 並使用呢？

我想到目前為止對 Webassembly 有興趣的大部分應該都是網路開發者，所以壞消息是你還是得寫 javascript XD，不過你可以直接匯入 Webassembly 來在程式碼內使用。至於要用什麼語言寫就見仁見智了，C/C++ 可以透過 emscripten，其他語言也應該都有對應的工具，但我覺得最簡單的方式還是用 Rust 了，它的社群提供了非常多超好用且簡單的工具可以讓你輕鬆就編譯出 Webassembly 並馬上使用。基本上你會用到的工具有：

wasm_pack 是建立 Webassembly 專案最簡單的 CLI，使用起來也十分直觀，甚至還能將你的 wasm module 發布到 npm 等 registry。
wasm-bindgen 是串接 rust 與 javascript 的函式庫，簡單來說你只要在所有的型別與函式上方加上 #[wasm_bingen] 就完成了。
web-sys 與 js-sys 分別提供 Web 與 Js 相關的 API。

要開始入門試試的話，我非常推薦 Rust 寫的 Webassembly 入門教學，一天內絕對看得完。想更快瞭解的話，MDN 也有提供更簡短的文章說明。

我指的是「真的」Webassembly

上述的工具與建出來的 wasm module 是特別針對給前端來使用的，Webassembly 當然可以產生完整的應用程式並來執行。每個語言的社群應該都有開發出些編譯器來編譯，像剛剛講的 C/C++ 就是用 emscripton，C# 則有 Blazor 等等。Rust 的話交叉編譯（Cross Compilation）則原本就是第一公民，寫好程式後只要用 cargo build --target wasm32-unkown-unknown 就能編譯出 Webassembly，甚至還提供了 wasm32-unknown-emscripten 與 wasm32-wasi 等目標讓開發者還可以使用這些標準提供的功能。

Wasi 的全名是 WebAssembly System Interface 旨在讓 wasm 可以有個符合 POSIX 的系統介面來做系統呼叫，目前 Bytcode Alliance 還在開發 wasi 中，不過許多 wasm runtime 都已經有支援了。 Bytcode Alliance 是由 Mozilla、Fastly、Intel 與 Red Hat 聯合起來的組織，目標就是要讓 WebAssembly 及其生態圈能成熟穩定下來。

既然我們能編譯出 wasm bytecode 了，總要有方式能執行起來，至於要怎麼執行也是見仁見智了，目前最官方的實作大概就是 Bytcode Alliance 的 wasmtime 了。Wasmtime 是原本由 Mozilla 主導，現在由 Fastly 接手開發的 JIT Interpreter，不同的語言如 C 或 GO 也都有使用其函式庫的方法。如果你想用其他 runtime 的話，Awesome WebAssembly Runtimes 也有列出非常多的不同實作。而許多大型專案或框架也有針對不同領域用途的不同實作。

所以的確 Webassembly 要當作完整獨自的生態體系的話還有一小段路要走，不過作為 web 的支援我覺得算是蠻成熟可以實際使用了。另外每個語言都可以一起協助拓展 Webassembly 的生態圈，期望 wasm 在未來可以持續有不錯的進展。

Environment Setup for ESP Development in Rust

2020-08-24T12:01:00+08:00

ESP series are the targets I always want to explore in Rust. Because they have many convenient built-in features like integrated Wi-Fi and dual mode Bluetooth. Unfortunately, both rustc and llvm don’t provide the build target for xtensa by default which means usually we must build the xtensa version for both. Furthermore, it’s not just about the compiler. There’s the whole toolchain from original ecosystem needs to be setup too. In our case, this means installing xtensa-esp32-elf toolchain, esptool, and maybe esp-idf properly. This post is going to provide a guide to setup the development environment with esp32 as an example.

Docker image for xtensa

In order to make cross compilation easier, the rust embedded community proposes a crate called cross which can build the docker image to setup required components for your targets and then build/flash your project from it. While original cross doesn’t have the Dockerfile for xtensa targets, there’s a fork for it thanks to @reitermarkus. Before building the docker image, I highly recommend adding your user to docker group to prevent any environment variable issue. Also make sure you already have Docker and jq installed. If you already have them, just follow instructions below to install the custom cross and required image:

git clone -b xtensa https://github.com/reitermarkus/cross
cd cross
cargo install --path . --force
./build-docker-image.sh xtensa-esp32-none-elf

Project Template

Next, we want to setup the project template that can build and flash our binary to the chip on the fly. Before we start, make sure you have esptool.py installed, this is how we going to flash the binary. Once you have it installed, we can clone the template and start building:

git clone https://github.com/wusyong/esp32-hello.git
git submodule update --init --recursive

This template also provides the ffi of esp-idf and wraps some basic functions to the esp-idf-hal. The main application is right under the app/ directory, there are more examples in the app/examples. To build and flash the application, we could just use the build script:

./build.sh [--chip <chip> (default: esp32)] [--release] [--package <package> (default: app)] [--example <example>] [--flash-baudrate <baud> (default: 460800)] [--erase-flash]

As you can see it's basically calling cross to build and esptool to flash. If you are also using esp32, you probably don't need to edit environment variables in the script. But make sure the SERIAL_PORT is correct just in case (it's /dev/ttyUSB0 for my device), or it's not going to flash successfully. To build the application in release, simply call:

./build.sh

And if you want to build any example:

./build.sh --release --example thread_local

State of the ESP ecosystem in Rust

In this section, I would like to talk about the ecosystem of it and evaluate is it worth it for ESP development using Rust. You don't need to proceed if you just want to setup the environment. It is basically complete.

I do consider ESP series are not the first-class citizen among the rust embedded community. You can’t simply cross compile it like other targets (stm, nrf for instance). And despite there’s an esp-rs organization which provides many helpful crates and even a quick start repository, there are still some obstacles and missing parts I can image many people would just give up if they cannot resolve. Building the compiler for xtensa is not trivial already, it is also very time consuming. It took me an hour or two to build the llvm and rustc. And toolchains can be outdated too! A while ago I have a dockerfile for me to build the imagine. But many tools have changed, and some are not compatible anymore. Even llvm asked me to use new variable LLVM_EXPERIMENTAL_TARGETS_TO_BUILD which is ** undocumented**! Furthermore, many crates are so difficult to seek and acquire. You think something so straight forward like esp32-hal should already on crates.io but it’s actually not. Other crates often scatter across the community, and you have to do the search yourself. But on the other hand, I feel like this is inevitable nature in FOSS. The community is moving for sure, just slowly. We saw that AVR target was merged into Rust recently. It definitely could also happen to ESP in the future.

The reason for me to keep going is probably the potential to develop in Rust. Here’s the example for Wi-Fi scanning in the esp-hello template. You can see how elegant and ergonomic it is. It’s even possible to use async programming to achieve the goal! Indeed, it still depends on esp-idf and FreeRTOS. But it is totally possible to just build an async runtime for it. I know some developers are already exploring this. I am exciting to see more powerful crates and tools for embedded in the future.

Option 的大小

2020-07-27T17:35:00+08:00

在 Rust 中預設是不能使用 Null 指標/引用的，而當時的設計者 Tony Hoare 也說了這是造成數十億損失的錯誤設計。所以通常我們會使用 Option 型態來表示可能會有 Null 值的型態。這麼做帶來很多好處，所有型態預設都是沒有 Null 的，而 Option<T> 剛好也形成一種 monadic structure。你可以在不和原生型態衝突的狀況下，自己定義他的運算行爲。

但是對於資源吃緊的裝置來說，我們就會在意型態的大小了。我們很清楚的知道 u64 就是有 64 bits 所以會佔 8 bytes，但是 Option<u64> 的話就需要多一個 bit 來儲存 None，所以一開始想的話我們應該會覺得它應該會佔 9 bytes，但結果卻是 16 bytes。

playground

assert_eq!(9, std::mem::size_of::<Option<u64>>());

thread 'main' panicked at 'assertion failed: `(left == right)`
  left: `9`,
 right: `16`', src/main.rs:2:5

這是因爲像是在 64-bit 的平台上的 CPU 都是 word-oriented，所有的形態預設都需要 align 爲 8 bytes 的界限。這樣就造成了一些效能的損失，當然這些在平常的應用開發不太重要，編譯器甚至能優化掉，但如果是要寫非常注重空間或記憶體消耗的話（像是寫 file system, kernel module 或嵌入式系統），可能就需要一些考慮了。爲此 std::num 提供了沒有零的原生型態像是 NonZeroU8, NonZeroUsize 等等。因爲他們的 0 是用不到的，所以作爲 Option 型態的話，就可以剛好給 None 使用。這樣一來大小絕對就和原本的型態一樣了。

playground

assert_eq!(8, std::mem::size_of::<Option<std::num::NonZeroU64>>());

Environment Setup for STM Development in Rust

2020-06-30T17:01:00+08:00

STM32 is the recommended choice to start with Embedded System Programming in Rust consider there are many supported libraries for Cortex-m series and STM targets and hals among the ecosystem. If you are already familiar with programming with them, all you have to do is add a few config files in your cargo projects and it's done. If not, fear not then. This post will list all the tools and environment you have to setup. I'm going to use STM32F3DISCOVERY as an example but other STM series should follow similar steps.

Tooling

First of all, we need to install some tools if you didn't have any embedded setup on your computer before. The common choice for our debuggers are usually GDB with OpenOCD. minicom may be helpful if you want to also try out some serail module. The GDB you have to install may be different depends on your distribution. On Ubuntu/Debian, it will be gdb-multiarch:

$ sudo apt-get install \
  gdb-multiarch \
  minicom \
  openocd

While others like arch linux will use arm-none-eabi-gdb:

$ sudo pacman -S \
  arm-none-eabi-gdb \
  minicom \
  openocd

If you want to communicate with bluetooth, there are some more packages recommended to install: bluez, bluez-utils, rfkill.

udev rules

Next, we want to set some rules to let us use those devices directly without root privilege sudo. Here's the example for STM32F3:

$ cat /etc/udev/rules.d/99-ftdi.rules:
# FT232 - USB <-> Serial Converter
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE:="0666"

$ cat /etc/udev/rules.d/99-openocd.rules
# STM32F3DISCOVERY rev A/B - ST-LINK/V2
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE:="0666"

# STM32F3DISCOVERY rev C+ - ST-LINK/V2-1
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE:="0666"

Then reload the rules:

$ sudo udevadm control --reload-rules

Finally, let's plug the device and verify the permissions:

$ lsusb | grep -i stm
Bus 001 Device 006: ID 0483:374b STMicroelectronics ST-LINK/V2.1

This means my device is connected to Bus 001 and enumerated as Device 006. Let's check the permissions according to the number we have:

ls -l /dev/bus/usb/001/006
crw-rw-rw-+ 1 root root 189, 5 Jun 30 17:31 /dev/bus/usb/001/006

We should see that current user does have read/write permissions as crw-rw-rw- shows.

OpenOCD connection

Once we install the packages, we could start to connect to our device using OpenOCD. The cfg file might be different depends on your device. But if everything works as planned, you should see something like following:

$ openocd -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg
Open On-Chip Debugger 0.10.0
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
adapter speed: 1000 kHz
adapter_nsrst_delay: 100
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
none separate
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : clock speed 950 kHz
Info : STLINK v2 JTAG v27 API v2 SWIM v15 VID 0x0483 PID 0x374B
Info : using stlink api v2
Info : Target voltage: 2.910427
Info : stm32f3x.cpu: hardware has 6 breakpoints, 4 watchpoints

You should see it says how many breakpoints and watchpoints are there.

ITM

For ITM protocol, there's itmdump we could install from cargo directly:

$ cargo install itm

And then make sure you start the tool in the same directory of where you start OpenOCD:

$ touch itm.txt && itmdump -F -f itm.txt

Other LLVM tools

If you also want to use some LLVM tools like objdump, size and more. There's also a cargo subcommand already:

$ cargo install cargo-binutils
$ rustup component add llvm-tools-preview

Then you could use those tools like this:

$ cargo objdump --target thumbv7em-none-eabihf --bin app --release -- -disassemble -no-show-raw-insn
$ cargo size --target thumbv7em-none-eabihf --bin app --release -- -A -x
...

Rust Toolchains & Configurations

After installing packages that we needs for general embedded development, we can now start tweaking our rust related stuffs. Like other projects we do in Rust, we usually create a cargo project since it can integrate several important build tools especially toolchains when we want to do cross compilation. For STM boards, or Arm Cortex-m architectures more precisely, here are the targets we could choose:

Cortex-M0, M0+, and M1 (ARMv6-M architecture): thumbv6m-none-eabi
Cortex-M3 (ARMv7-M architecture): thumbv7m-none-eabi
Cortex-M4 and M7 without hardware floating point (ARMv7E-M architecture): thumbv7em-none-eabi
Cortex-M4F and M7F with hardware floating point (ARMv7E-M architecture): thumbv7em-none-eabihf

To install the toolchain, simply run:

$ rustup target add thumbv7em-none-eabihf

Config files

Once toolchain is installed, we can cross compile the project to specific target using cargo build --target. But this will become tedious and there are more steps need to do when you entering gdb. So instead of typing these command manually each time, we could setup config files in the cargo project like this.

.cargo/config:

[target.thumbv7em-none-eabihf]
runner = "arm-none-eabi-gdb -q -x openocd.gdb"
rustflags = [
  "-C", "link-arg=-Tlink.x",
]

[build]
target = "thumbv7em-none-eabihf"

openocd.gdb:

target remote :3333
set print asm-demangle on
set print pretty on
monitor tpiu config internal itm.txt uart off 8000000
monitor itm port 0 on
load
break main
continue

This means we will build the project to specific target thumbv7em-none-eabihf and then run with arm-none-eabi-gdb with gdb config file openocd.gdb. Then we will just need to use cargo run to enter the gdb and see how it goes!

More References

One of great reasons to develop embedded system in Rust is always its community. There are plenty of resources you can find in the ecosystem. Here are some I think are useful and might help you too.

原子類型（Atomics）

2020-06-08T12:17:07+08:00

瞭解原子類型（Atomics）與記憶體順序（Memory Ordering）可以幫助我們更瞭解多執行緒程式設計，但實際上要理解的話可能就會和筆者一樣在網路上找隨機的文章或是官方文件來啃，可能就找個當下適合的選項來用，不再繼續往下理解，直到下一次又遇到更深入的問題。這篇文章算是一個總結，希望從最頭到尾說清楚，並且瞭解 Rust 的很多類型爲何那樣設計，以至於能讓所有人都能寫出安全又高效的多執行緒/並行程式。

以下會先介紹多處理器程式設計，再來才會說明各個記憶體順序的意義，最後講解原子類型怎麼使用這些順序的，結束之前會再補充其他具有內部可變性的 Rust 類型爲什麼也是合理的。

多處理器程式設計

當今幾乎所有程式都已經是跑在多核心 CPU 的機器上了，而這也產生了不少奇妙的問題讓我們得常常處理。在只有一個執行緒的程式是沒有什麼好擔心的，但如果是多核心的話很多麻煩就跟着來了，我們知道編譯器在編譯時會幫忙重新排列你的程式來做最佳化，事實上連 CPU 也會做這樣的事。對於編譯器的重新排列，我們可以檢查產生出來的組合語言知道，但如果是多核心的 CPU 的話我們就沒辦法這樣做了。

當執行緒跑在不同的 CPU，CPU 會去重新排列指令，而這樣的行爲是很難去 debug 的，我們往往只能觀察它們的行爲、執行結果、pipeline 和 cache 等等才能知道。而這就是原子類型（Atomics）想要解決的，這些類型會確保在共用記憶體時它們的指令不會被重新排列。

強記憶體排列與弱記憶體排列

接下來會有很多關於 CPU 的引用都會參考這份文件：Intel® 64 and IA-32 Architectures Software Developer’s Manual Volume 3A。但實際上不同的 CPU 對於記憶體會提供不同的保障，我們通常可以區分爲強記憶體排列（Strong Memory Ordering）和弱記憶體排列（Weak Memory Ordering），但這也只是簡單區隔而已，很多甚至是介於這兩者之間。爲了歸納這些不同，C++ 有一套 Abstraction Machine，而 Rust 也是借鑑於此。這套模型便是希望讓我們有辦法寫出能跑在任何機器上的程式，無論是強記憶體排列或是弱記憶體排列。你會看到 C++ 的 abstraction model 指定了很多存取記憶體的方式，而這幾乎也是必須的，考量到我們得用相同的語法跑在強與弱記憶體排列的處理器上。

強記憶體排列的 CPU 可以給與我們一些非常重要的保障，這些保障可以讓我們的指令縮減到 no-op。No-op 是指 CPU 可以讓整個語義不發生，不會有任何花費與成本的損失。他做的事情其實也沒啥酷炫的。他就只是提醒編譯器，我們寫的程式哪些的地方是不可以讓記憶體重新排列的；而弱記憶體排列的 CPU 就沒那麼好了，我們得親自設置記憶體柵欄（Memory Fence）以及寫些特殊的指令來防止同步問題。當然要完全明白最好的方式就是親自在弱記憶體排列的 CPU 試試看，不過現在的人所使用的 CPU 幾乎都是強記憶體排列了，所以寫的時候可能就觀察不到差別了，下面在解釋時會特別說明兩者之間分別發生了什麼事情。

上面說到現在所有的 CPU 幾乎都是強模型了，無論 AMD 或 Intel 都是，它們能夠對特定的指令給與不重新排列的保障，這些保障我們可以在 Intel 開發者手冊的第 8.2.2 章看到：

讀取不會和其他的讀取重新排列

寫入不會和之前的讀取重新排列

寫入不會和其他的寫入重新排列（有其他例外）

還有最重要的這一條，特別指明不提供保障：

讀取可能會和之前其他位置的寫入重新分配，但不會和之前相同位置的寫入重新分配

這一條要特別注意的原因是因爲和後面的排列選項 SeqCst 有關。先在此注意到就好。接下來的章節會以弱模型爲基準，再補充強模型的說明。

快取記憶體

通常 CPU 有三層快取記憶體：L1、L2 和 L3。L2 和 L3 會在 CPU之間共享。而每個核心會有自己的 L1 快取記憶體，我們所有要解決的問題就是從這裏開始。L1 快取記憶體用的是 MESI 協議，聽起來好像很複雜，其實就只是字面上的意思。他是指快取可以有四種狀態的縮寫（Intel 開發者手冊第 11.4 章有做更詳細的介紹）：

已修改 Modified (M) - 快取行是髒的（dirty），要寫回主記憶體
獨占 Exclusive (E) - 快取行只在當前快取中，但是乾淨的（clean）
共享 Shared (S) - 快取行也存在於其它快取中且是乾淨的，快取行可以在任意時刻拋棄
無效 Invalid (I) - 快取行是無效的，其他快取修改過了

處理器之間的通訊

既然我們真的得存取並修改 Shared 記憶體，那麼其他核心是怎麼知道它們的 L1 已經無效了。一個快取行被視爲無效的規則就是有其他核心的 L1 修改過了，這時雖然自己的 L1 還是在 Shared 的狀態，但在那邊的卻已經是 Modified 了。所以記憶體之間得有個通訊的方法來通知大家，我們就暫且想像每個核心都有個信箱吧。

每個信箱都可以存一些訊息，以避免 CPU 一直被傳過來的訊息給中斷，到某個時間點 CPU 會檢查信箱然後依據收到的訊息來更新快取。所以舉個例子的話就是，有個 CPU 修改了某個快取行，傳送了訊息給其他核心。核心檢查信箱收到訊息後，更新他們的快取行。最後 L1 從主記憶體（或 L2、L3）取得正確的值，讓狀態再次回到 Shared。

在強模型的 CPU 則會有點不同。如果有個 CPU 要修改 Shared 的快取行，它得先通知所有的核心讓該行失效，才能真的進行修改。這類的 CPU 通常會有快取一致性來修改個核心的快取。

記憶體順序（Memory Ordering）

現在我們終於對 CPU 的設計以及它們怎麼溝通開始有點概念了。那麼也是時候來看看這些記憶體順序還有它們代表什麼意思了。無論是 C++ 的 std::memory_order 或是 Rust 的 std::sync::atomic::Ordering，都有五個值。接下來在講解時，我們很難真的用程式範例來說明發生什麼事情，不過我們可以想像一個觀察者的 CPU 在一旁觀看發生什麼事情。

Relaxed

在目前的 CPU：

Relaxed 的記憶體順序會防止編譯器重新排列這些指令，但在弱模型的 CPU，它可能還是會重新排列其他所有的記憶體存取。所以如果只是要作爲計數器的話不會有啥問題，但如果是一個要實作在 lock 裡的 flag 的話可能就會出問題了。因爲這樣會無法確保其他一般的記憶體存取有沒有在 flag 之前或之後遭到重新排列。

在觀察者的 CPU：

編譯器和 CPU 可以任意重新排列記憶體順序，但是不能夠變更 Relaxed 讀寫之間的順序。也就是說觀察者的 CPU 可能會看到與我們寫出來的程式順序不同，但是它們永遠會看到 Relaxed 操作 A 一定會發生在 Relaxed 操作 B 之前。所以說 Relaxed 是最弱的記憶體順序，它不會爲其他 CPU 做同步的事情。

在強模型的話，所有的記憶體操作預設都是 Acquire/Release 語義的。因此 Relaxed 只會是用來告訴編譯器這些指令不能被重新排列的。在強模型用這個順序的原因有助於編譯器去重新排列其他記憶體存取。這也是爲啥你用 Relaxed 的效果會和 Acquire/Release 一樣，不過要注意這當然指存在強模型系統下，面對不同的 CPU 平時還是依照歸納模型說明的爲準，不然程式是會在不同 CPU 下出錯的。可以參考這篇文章看看爲何同個程式碼跑在強記憶體排列與弱記憶體排列會不一樣。

Acquire

在目前的 CPU：

任何在 Acquire 存取之後的記憶體操作都會維持在它之後，它是與 Release 順序一對的，組織成一個「記憶體三明治」。所有在它們之間的記憶體存取會與其他 CPU 進行同步。在弱模型的系統下，這代表在 Acquire 操作之前會需要用到一些特殊的 CPU 指令，強迫目前的核心消化完信箱內的所有訊息，很多 CPU 都有這種序列化和記憶體排序的指令。在 Acquire 讀取之前可能還會在加個記憶體柵欄來防止 CPU 重新排列記憶體存取。這樣 Acquire 的操作就會與其他 CPU 確保修改記憶體是同步的。

記憶體柵欄簡單來說就是個硬體的概念，它會強迫 CPU 在柵欄前完成所有的記憶體讀寫，以防止指令重新排列。這樣一來就能確保沒有任何在柵欄前的操作會與柵欄後的操作重新排列。爲了區分不同操作像是讀寫或者全都有，它們都會有不同的名字。全部讀寫都擋的就叫做 full fence。

你可以在[Intel 開發者手冊]的第 8.2,8.3,8.5 章看到它們的介紹，像是 MFENCE 就是會序列化所有讀寫的柵欄。不過在強模型系統中我們通常看不太到，因爲它們沒有需求。在弱模型的化就不一樣了，它們是實作 Acquire/Release 幾乎必備的指令。

在觀察者的 CPU：

因爲 Acquire 是個讀取操作，不會修改記憶體，所以沒有觀察的必要。不過有點要注意的是如果觀察者核心做了 Acquire 的讀取操作時，它就能夠看到所以從 Acquire 發生的記憶體操作，一直到 Release 儲存。這代表有個全域的同步事件正在發生，我們會在後面的 Release 繼續說明。

Acquire 通常用來寫鎖的行爲，讓一些操作可以維持在成功取得鎖之後。所以說 Acquire 只會用在讀取的操作上。在 Rust 的話許多儲存的原子操作要是你用 Acquire 的話會直接 panic。

在強模型系統的話，這個會是 no-op 也就是不會有任何花費，也不會有效能的損失。不過它還會防止編譯器去重新排列那些在 Acquire 之後的記憶體操作被排列到 Acquire 之前。

Release

在目前的 CPU：

相對應於 Acquire，任何在 Release 記憶體順序之前的記憶體操作都會在它之前。它是與 Acquire 順序一對的。在弱模型系統中，編譯器可能會再加個記憶體柵欄來確保 CPU 沒有重新排列 Release 之前的記憶體操作到它之後。這邊還有一項保障是所有其他核心做到 Acquire 時一定要看到所有在 Acquire 與 Release 之間的記憶體操作。所以不光是所有操作必須在本地端排序正確，還要確保在此時所有的更動都是可以被其他觀察核心看到的。這就代表在 Acquire 開始之前以及 Release 之後都要進行某種全域同步操作。所以我們有兩種選項：

Acquire 讀取必須要消化所有的訊息，如果有任何其他核心讓任和我們要讀得記憶失效的話，它必須要讀到正確的值才行。
Release 儲存必須是原子的並且讓它曾修改的值在其他所有快取都被失效。

只進行其中一個操作就足夠了，所以這比後面要講的 SeqCst 弱一些，但是也比較有效率。

在觀察者的 CPU：

觀察者的 CPU 可能不會看到任何特定順序的變更，除非他有用到 Acquire 讀取記憶。如果有的話，它將會看到 Acquire 與 Release 的所有記憶體，包含 Release 本身。

Release 通常會和 Acquire 一起用於鎖的實作。對於一個鎖的函式，有些操作通常需要維持在成功獲得鎖之後，一直到鎖被釋放爲止。所以說與 Acquire 相反，在 Rust 許多讀取的原子操作要是用 Release 的話會直接 panic。

在強模型的 CPU，所有的 Shared 值一旦被修改的話，在所有的 L1 快取都會失效。這代表 Acquire 讀取時就會取得更新過的相關記憶體資訊，而 Release 會立即讓在其他核心擁有該資訊的快取行失效。這就是爲何這些語義在這類的系統不會有任何效能花費。

AcqRel

這是用在需要同時讀取並儲存值的操作，像是 AtomicBool::compare_and_swap 就是這種。因爲這樣的操作需要同時讀取並儲存，這在弱模型系統下就會有影響，僅使用 Relaxed 的話是不夠的。我們也可以把這個操作想成是某種柵欄，在它之前的記憶體操作不會被重新排列到這之後，而在之後的操作也不會被排列到之前。剩下做的事情就和上面的 Acquire/Release 一樣了。

SeqCst

在目前的 CPU：

到這邊強與弱模型的行爲就一樣了，SeqCst 的意思是 Sequential Consistency，我想就翻作順序一致性吧。它和 Acquire/Release 擁有同樣地保障，但還保證能建立「唯一的總修改順序」。

雖然被視爲最強保障，但其實 SeqCst 還是有被質疑是不是該作爲最推薦的順序，也有些人反對使用它。很多時候似乎還是很難有個很好的理由說一定得用 SeqCst，甚至有些論文有指出它可能是有瑕疵的。總之，這邊只是提一下不是所有人的看法都相同，很多時候說不定 Acquire`/`Release 就能涵蓋所有問題了。

無論如何，讓我們繼續介紹 SeqCst 吧！我們會需要看個範例和產生的組合語言，以下是 playground 連結： https://godbolt.org/z/EFK-qU

use std::sync::atomic::{AtomicBool, Ordering};
static X: AtomicBool = AtomicBool::new(true);
static Y: AtomicBool = AtomicBool::new(true);

pub fn example(val: bool) -> bool {
    let x = X.load(Ordering::`Acquire`);
    X.store(val | x, Ordering::`Release`);
    let y = Y.load(Ordering::`Acquire`);
    x || y
}

movb    example::X.0.0(%rip), %al # load(Acquire)
testb   %al, %al
setne   %al
orb     %dil, %al
movb    %al, example::X.0.0(%rip) # store(Release)
movb    $1, %al                   # load(Acquire)
retq

不同CPU可能產生的指令會有點不同，但結果都是一樣的。store 會用到 Release 記憶體順序也就是 movb %al, example::X.0.0(%rip)。我們知道這樣就能確保有該值得快取行會立即失效。

那問題在哪呢？是時候提起之前其中一項不保證的事情了，Intel 開發者手冊的第 8.2.3.4 章有在更加詳述：

8.2.3.4 讀取可能會和更早之前不同位置的寫入重新排列 The Intel-64 記憶體排序模型允許讀取能和之前不同位置的寫入重新排列。但是讀取不會和相同位置的寫入重新排列。

所以也就是說剛剛的範例可能會被改成：

let x = X.load(Ordering::Acquire);
X.store(val | x, Ordering::Release); # 之前不同位置的寫入
let y = Y.load(Ordering::Acquire);   # 讀取

// 可能會被 CPU 變更成

let x = X.load(Ordering::Acquire);
let y = Y.load(Ordering::Acquire);
X.store(val | x, Ordering::Release);

如果我們現在改成 SeqCst 的話就可以看到生成的組合語言變成：

use std::sync::atomic::{AtomicBool, Ordering};
static X: AtomicBool = AtomicBool::new(true);
static Y: AtomicBool = AtomicBool::new(true);

pub fn example(val: bool) -> bool {
    let x = X.load(Ordering::SeqCst);
    X.store(val | x, Ordering::SeqCst);
    let y = Y.load(Ordering::SeqCst);
    x || y
}

movb    example::X.0.0(%rip), %al
testb   %al, %al
setne   %al
orb     %dil, %al
xchgb   %al, example::X.0.0(%rip)
movb    $1, %al
retq

我們可以看到讀取的指令變成了 xchgb %al, example::X.0.0(%rip)，這是一個原子的操作，[xchgb 有個 lock 的前綴]，lock 相關的指令會確保其他所有核心的快取行存取到的記憶體在獲取時會鎖住，然後在修改時變成無效。除此之外它還可以作爲 full fence，Intel 開發者手冊的第 8.2.3.9 章就如此說道：

8.2.3.9 Lock 指令的讀取和寫入不會被重新排列記憶體排序模型會阻止 lock 指令的讀取和寫入無論是之前或之後都不會被重新排列。此區塊的範例僅展示 lock 指令在讀取或寫入之前的狀況。讀者請注意到 lock 指令後的讀取或寫入是不會被重新排列的。

在觀察者的 CPU：

對於觀察者來說，這項變更非常地顯著。首先就是順序一致性，如果我們要求一個讀取一定得在某個 flag 釋放之後，理論上我們是可以觀察到 Acquire/Release 語義下，它卻在 Release 操作之前就讀取了。使用 lock 可以防止這樣的情況，所以除了擁有 Acquire/Release 的保證以外，它還確保覺不會有其他記憶體的操作會在之間發生，無論是讀取還是寫入。

再來就是唯一的總修改順序，SeqCst 在弱模型的 CPU 可以提供一些我們在強模型 CPU 就有的保障，最重要的就是這個唯一總修改順序。如果我們有兩個觀察者核心，他們將會在 SeqCst 操作下看到相同的順序，Acquire/Release 則沒辦法提供這項保證。一號觀察者可能會看到兩個變動但順序和二號觀察者不同。假如有個一號核心用 Acquire 拿到了 flag X ，而二號核心也一樣以此方式拿到了 Y。兩者再做相同的操作最後使用 Release 將 flag 改回去。這樣不會阻止一號觀察者先看到 flag X 變回去再來看到 Y 變回去，但二號觀察者卻看到相反地順序。SeqCst 可以防止這發生。在強模型下，甚至連儲存都會馬上被其他核心看到，所以修改的順序在這不會是問題。

**所以說 SeqCst 是最強的記憶體順序，但同時花費也比其他順序高一些。**你可以看到上面的每個原子指令都會有些開銷，因爲這會用到 CPU 的快取一致機制以及鎖定其他快取的記憶體位置等等。

原子操作（Atomic Operation）

除了上述講到的記憶體柵欄，使用 std::sync::atomic 提供的原子類型還可以使用到一些 CPU 重要的指令，這些是我們平常在 Rust 看不到得：

在 [Implementing Scalable Atomic Locks for Multi-Core Intel® EM64T and IA32 Architectures] 一文中有提到:

User level locks involve utilizing the atomic instructions of processor to atomically update a memory space. The atomic instructions involve utilizing a lock prefix on the instruction and having the destination operand assigned to a memory address. The following instructions can run atomically with a lock prefix on current Intel processors: ADD, ADC, AND, BTC, BTR, BTS, CMPXCHG, CMPXCH8B, DEC, INC, NEG, NOT, OR, SBB, SUB, XOR, XADD, and XCHG...

也就是說當我們使用原子類型的方法，像是 AtomicUsize 的 fetch_add 的話，編譯器實際上會變更原本指令的行爲，在 CPU 除了加兩個數字以外還會做其他事。用組合語言來看的話就會像是 lock addq ... 而不僅僅是我們平常預期的 addq ...。

一個原子操作其實是一系列的執行操作組合成一個不可分割的操作單位。任何觀察者是沒辦法看到底下的細部操作或者嘗試在操作執行時獲得相同的資料的。任何在其他核心且會造成的的 B 操作都得等擁有相同資料的操作 A 先完成才行。我們用計數器來舉個例子，總共有三個步驟：讀取資料、修改資料、儲存資料。每一步之間，其他核心都可以跟着採取想要的操作進行讀寫。通常我們希望可以在我們讀取資料一直到儲存回去時，不被其他人干擾到，確定操作正確無誤，這就是原子操作想要解決的。

原子類型常見的用途之一就是 spinlock，而最簡單的範例大概長得像這樣：https://godbolt.org/z/GxS_bp

static LOCKED: AtomicBool = AtomicBool::new(false);
static mut COUNTER: usize = 0;

pub fn spinlock(inc: usize) {
    while LOCKED.compare_and_swap(false, true, Ordering::Acquire) {}
    unsafe { COUNTER += inc };
    LOCKED.store(false, Ordering::Release);
}

xorl    %eax, %eax
lock    cmpxchgb %cl, example::LOCKED(%rip)
jne     .LBB0_1
movb    $0, example::LOCKED(%rip)
retq

lock cmpxchgb %cl, example::LOCKED(%rip) 就是我們的 compare_and_swap，lock cmpxchgb 就是我們的 lock 操作，它會讀取 flag 的值然後如果條件符合的話就變更它。我們可以看到Intel 開發者手冊的第 8.2.5 章的說明：

多處理器的同步機制可能會需要依賴強記憶體排列的模型。在這裏一個程式可以用 lock 指令像是 XCHG 指令或是 LOCK 前綴來確保記憶體的讀取、修改、寫入都是原子的。Lock 指令通常就像 I/O 操作一樣，它們等待之前所有的指令完成以及所有緩充區的寫入都寫進記憶體了。

接下來要釐清的就是 lock 指令前綴是在做什麼了。用最簡短的方式說明的話就是當有記憶體讀取時，它就馬上將該快取行設置爲已修改（Modified）。這樣一來從記憶一被讀取到核心的 L1 快取開始就是 Modified 的了。接着就算每個核心都還沒開始處理他們信箱的訊息，處理器就會用[快取一致性機制]讓所有其他核心的狀態都直接變爲無效（Invalid）了。

如果說訊息傳遞是一般的同步方式的話，那 lock 操作以及其他記憶體順序或序列化操作則是包含更昂貴但強大的機制可以繞過訊息傳遞，直接鎖定其他核心的快取行，讓任何讀寫都沒辦法在這過程中實現，然後將它們設爲無效（Invalid），進而引導快取去索取更新的值。

快取行通常在 64 位元的系統都是 64 bytes，不同 CPU 可能還是會有差。不過會特別提起的原因是如果鎖定機制在鎖定時會橫跨兩行快取行的話，花費會變得更昂貴，因爲這會需要再用到一些硬體的技術像是 bus locking 以及更多等等。而且對於會橫跨快取行的原子操作在不同架構擁有支援也大相徑庭。

Rust 的引用型態

到這邊就算是講完整個原子類型了，希望這些說明能幫到想瞭解的人，至少能夠深入去理解整個原子操作的心智模型我覺得非常有利於往後實際的使用。而在 Rust 也是如此，所以差不多也是時候來深入理解一下 Rust 的引用形態了。我想熟悉 Rust 的人讀完上面應該就會發現這和 Rust 的引用 & 和 &mut 有點像，尤其是整個 MESI 協議定義的狀態。當然我們在學的時候，大家是稱 & 爲不可變引用（Immutable Reference）；稱 &mut 爲不可變引用（Mutable Reference）。書上會說對於那些可以違反 Rust 的型態模型的型態，像是我們本文的重點 Atomics 以及其他諸如 Rc/RefCell 等等，是因爲它們有內部可變性（interior mutability），才能在不可變引用做改變。現在你可以換個角度來看了，& 就是共享引用（Shared Reference），而 &mut 則是獨佔引用（Exclusive Reference）。這剛剛好可以對應到 MESI 的 E 和 S，擁有這樣的模型可以作出其他語言做不到的優化。在 Rust 裡，也確實只有被視爲 Exclusive 記憶體能夠被修改。

這代表只要我們不違反修改 Shared 記憶體的規則的話，所有的 Rust 程式可以將所有核心上的 L1 快取視爲是有更新到最新，而且無需進行同步的。

當然我們是需要在不同核心間共享記憶體的，但是顯式地表達出來，並特別注意的話是可以寫出品質更好地程式碼的。

內部可變性

既然我們可以更改我們觀看得角度，那麼我們也可以一一來解釋哪些具有內部可變性的型態是說的通的了。標準函式庫裡的 UnsafeCell<T> 唯一可以擁有可變資料的共享引用，這是一個底層的 unsafe 元件平時這個型態我們是不會直接使用的。其他所有具有內部可變性的型態都是以此打造出安全的界面和不同的功能需求，畢竟 Rust 的初衷就一款能寫出安全程式的語言，這些型態本來必須達到這樣的條件。所以除了原子類型以外，標準函式庫內中含有內部可變性的類型有：

`Cell<T>`

我們可以改變 Cell<T> 的值，就算有其他的引用存在。但這是安全的因爲它的 API 有保障：

不同的執行緒絕對不可能引用同個 Cell<T>，這是因爲 Cell<T> 本來就沒有 Sync trait，也就是說 Cell<T> 只能存在單一執行緒。
沒有辦法取得 Cell<T> 裏面內容的引用，因爲要是能這樣拿到引用的話，就有可能去改變內部的值違反規則了。它所有的存取動作都是將 Cell<T> 裡的資料複製出去。

`RefCell<T>`

我們可以改變 RefCell<T> 的值，就算有其他的引用存在。但這是安全的因爲它的 API 有保障：

RefCell<T> 一樣也只能存在單一執行緒，它和 Cell<T> 一樣都不能在多執行緒間引用。
而在單一執行緒時，動態借用檢查規則會去檢測並防止取得 RefCell<T> 引用並拿到內部資料的人改變其值。

`Mutex<T>`

我們可以改變 Mutex<T> 的值，就算有其他的引用存在。但這是安全的因爲它的 API 有保障：

只有一個引用可以對內部的 T 進行操作，無論是讀取或寫入。其他的存取都會被擋住直到當前的人將鎖釋放。

`RwLock<T>`

我們可以改變 RwLock<T> 的值，就算有其他的引用存在。但這是安全的因爲它的 API 有保障：

只有一個引用可以對內部的 T 改變其值，而且必須在沒有任何引用用來讀取的情況下。要是這條件成立的話，其他的存取都會被擋住。也就是同時只能有一個寫入，或者多個讀取。

總結

這篇原本是想寫個簡單概述，不過看着像是 dtolnay 和 cfsamson 的文章，覺得還是都寫下來好了，以上的資訊大部分都來自於此。回過頭來看，我也一樣不覺得一開始在學習時用可變與不可變是錯的，畢竟 Rust 的學習曲線在一開始就算蠻斗的了。不過要是能夠轉換觀看這些類型的心智模型的話，我自己覺得很多事反而更說的通了，不必特地去煩惱哪些型態有內部可變性而哪些沒有，又或者得想很久爲什麼這些 API 得這樣設計。這篇文章的確主軸仍然是原子類型，但我想順便偷渡一下這些觀點，可以發現 Rust 的整個設計模型的確可以直接的對應到底曾的記憶體管理設計。在寫程式時，變能夠特地注意到這些特點，進而寫出品質非常好的程式出來。

Peh-oe-ji Lite

2020-06-03T21:11:42+08:00

Peh-oe-ji Lite (POJL) is a dialect of Pe̍h-ōe-jī, one of the first orthography in Taiwan and is still widely in use nowadays. It's literally the same BUT:

No need for tone marking anymore. You can type Goa (我) instead of Goá.
Special letters, ⁿ and o͘, are simplified to n and o. Mo͘ can now be Mo (毛), and Saⁿ can just be San (衫). Here's the compaison of all letters between original and lite: TODO
(Optional) Hyphens - can be removed or become a space instead. Peh-oe-ji, peh oe ji, and pehoeji are all valid in POJ lite. Just choose the one you think is the most readable.
(Optional) Same with double hyphen --. chiah-pa--be (食飽袂), chiah-pa-be, chiah pa be, and chiahpabe are all valid.

The reason that hyphen elision is optional is because there are more scenarios need to be considered actually. We will figure this out once the proposal is finalized.

Motivation

Pe̍h-ōe-jī and Tâi-uân Lô-má-jī are two mainstream romanization systems in Taiwan that are easy to read and write until they meet modern computation systems. Despite there are so many input methods to support on different platforms. It's still a huge gap to actually type these words. IMHO, we should be able to just use simple alphabet characters to express our sentences. Furthermore, it also increases the readability a lot once tone marks are removed. After all, we usually read texts in any language instead of pronunciation.

To be clear again, POJL is just a dialect and is not trying to replace any existing format. It aims to help people type Taiwanese easier, and potentially flatten the learning curve for beginner. Eventually, we expect POJL can be commonly used in casual situations.

Sample

Here's what it looks like if we type in POJL:

Peh-oe-ji (POJ) si 1 khoan iong Latin (Lo-ma) pheng-im he-thong lai sia Tai-oan e gi-gian e su-bin bun-ji. In-ui tong-chho si thoan-kau-su in--jip-lai e, so-i iah-u-lang ka POJ kio-cho kau-hoe Lo-ma-ji, hek-chia si kan-chheng kau-lo. Put-ji-ko hian-tai e su-iong-chia be-chio m-si kau-to, kau-to ma chin che be-hiau POJ.

100% 確定清空並釋放記憶體

2020-05-21T17:35:00+08:00

要安全地清空記憶體通常不是我們會在意的事情，在 Rust 因為所有物件都有其生命週期並會在 scope 結束時就被釋放掉，但如果今天的對象是敏感的資訊像是 secret 的話我們就得另當別論了。編譯器一直以來都會自動幫我們最佳化，所以他們很可能會把一些他們認為不必要的呼叫給優化掉，另外如果是在 stack 上的變數則是直到下一次存取才會覆蓋掉。而且當你想交叉編譯的話情況會變得更複雜，當然如果你願意的話可以在 regression 特地編出所有目標然後用 valgrind 之類的檢查有沒有記憶體洩漏，但這似乎太大費周章了。通常這樣的情形我們可以簡單有幾行程式顯式地確定有被清空釋放掉。

首先我們知道有 Drop trait 讓物件在 drop 時可以多作一些事，可以把這個想成相當於 Destructor 的概念。再來 Rust 雖然還沒有 volatile 的語法，但是在標準函式庫中的 ptr 模組就已經有 volatile 的方法可以使用，而我們可以在釋放前用 ptr::write_volatile 清掉我們的敏感資訊，而且確定不會被編譯器重新排列或者優化掉。最後我們加上 atomic::compiler_fence 來確保所有的存取在這時看到的 secret 已經是被清掉的訊息了。這樣一來就能 100% 確定我們想釋放的記憶體是真的會被 drop 掉。

Playground link

use std::sync::atomic::compiler_fence;
use std::sync::atomic::Ordering;
use std::ptr::write_volatile;
use std::ops::Drop;

#[derive(Default)]
struct Secret(String);

impl Drop for Secret {
    fn drop(&mut self) {
        unsafe{ write_volatile(self, Default::default()); }
        compiler_fence(Ordering::SeqCst);
        println!("Secret is dropped for sure!");
    }
}

fn main() {
    let _secret = Secret(String::from("Sensitive info"));
}

用 grcov 收集整合 code coverage

2020-04-30T06:37:23+08:00

在 Rust cargo 專案中進行 code coverage 比想像中輕鬆許多。透過 grcov 兩三行指令就能產生出報告來了。首先要先下載 release，不過既然有 cargo 我們只要 cargo install grcov 就好了。

再來設置一下環境變數，以下能夠防止 dead code 簡化才不會影響 coverage

export CARGO_INCREMENTAL=0
export RUSTFLAGS="-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort"
export RUSTDOCFLAGS="-Cpanic=abort"

然後就像平時一樣測試就好了

cargo build
cargo test

這樣就能在 target/debug/deps/ 看到產生的檔案 .gcdo .gcda。如果要在產生 html coverage report 的話像這樣作就好

grcov ./target/debug/ -s . -t html --llvm --branch --ignore-not-existing -o ./target/debug/coverage/

最後報告的位置就在 target/debug/coverage/index.html，整個過稱輕鬆寫意大概花不到五分鐘就完成了。

Arch Linux 與 Windows 雙系統安裝方法

2020-03-16T18:00:00+08:00

Arch 其實我已經用好一陣子了，當時在安裝前就有想過裝好後就要寫個文章還願一下，畢竟在這過程中也受益於不少社群的幫助，但是安裝時忘了一一截圖所以後來就懶了。現在想起來覺得還是該寫一下算是有個交待。首先，如果你的電腦沒有啥特別的需求像是一定得玩遊戲之類的，我是覺得可以直接裝任一 Linux 發行版了，畢竟現在是個什麼都是 Web app 或 Electron 的時代，你常用的各式程式像是 Spotify 或 Discord 等在 Linux 上都絕對都能安裝，你會用到的 IDE 通常在 Linux 上的支援都會更完備，想省麻煩的話就直上 Linux 吧！不過說到底有時還是會有些不得不保留 Windows 的需求在，如果你想體驗看看輕量化且十分彈性的 Arch 並參與它熱絡的社群的話，希望這篇能幫助到大家。

事前準備

在開始之前，我誠心建議還是看一下 Arch 維基 Dual boot with Windows 的說明，下面等會會一一說明叫大家注意的，其實在這篇都有列舉出來。再來是兩個系統安裝的順序，我也是建議先安裝 Windows 在裝 Arch，而且在安裝 Windows 時最好將 boot partition 設為 512 MB 以上（預設好像會是 100 MB）。然後如果你是 Windows 8 以上應該都是用 UEFI，所以請記得關掉 Secure Boot，每家韌體的停用方法都會有點不一樣所以可能得自行搜尋一下。最後是到 Windows 控制台的的電源選項停用 Fast Startup 和 hibernation，這兩個預設應該都是開啟的。

製作 Arch Linux 安裝 USB

在這邊我預設大家是用 Windows 來製作，先到 Arch 官網下載，然後用 Rufus 製作安裝碟。如果你是 Linux 的話可以直接用 dd 。

如果你的電腦是 UEFI 在燒錄時就選擇「GPT Partition」（大多數 Windows 7 以上應該都是這個），如果還是不是的話就選「MBR partition」。如果你完全不清楚的話可以按下「開始鍵 + R」，然後輸入 msinfo32，按下去之後應該會看到你的 BIOS 模式，如果顯示 UEFI 就選「UEFI-GPT mode」，如果是 Legacy 就選「BIOS-MBR mode」。

製作完後，就重開機然後開 BIOS 調整開機順序用讓 USB 先執行吧。一樣每個人開 BIOS 的按鍵通常也不一樣，就 del, F12, ESC 都按按看吧。

分割磁區

通常我們會開出三個 partition 給 Linux：/(root), [swap], /home，/boot 在前面已經提過了而我建議是 512 MB 以上。這邊算是比較頭痛的地方，因為要開多少見仁見智。Arch 維基也有一篇在介紹該如何分割 Partitioning，不太確定該怎麽開的話可以參考看看。基本上來說會建議 root 開至少 20 GB 以上，swap 開跟你的 RAM 一樣的大小，剩下的全給 home。在開始分割之前先用 lsblk 確定你的硬碟：

$ lsblk
sda      8:0    0 465.8G  0 disk 
|-sda1   8:1    0   512M  0 part /boot
|-sda2   8:2    0    16M  0 part 
`-sda3   8:3    0   464G  0 part

然後用 cfdisk 開始設置，以下是我設好後的樣子：

所以這些是我會用到的磁區，以下請依照你分割對應的磁區來輸入指令

/dev/sda4 : root
/dev/sda5 : swap
/dev/sda6 : home

格式化 Linux 磁區

分割好後再來就是格式化我們的 root 和 home 磁區，我這邊會繼續用 ext4，如果你想要的話也可以試試潮潮的 Btrfs:

$ mkfs.ext4 /dev/sda4
$ mkfs.ext4 /dev/sda6

建立 swap

$ mkswap /dev/sda5
$ swapon /dev/sda5

掛載磁區

所有磁區都設好後就可以掛仔他們了。

$ mount /dev/sda4 /mnt

$ mkdir /mnt/home
$ mount /dev/sda6 /mnt/home

$ mkdir /mnt/boot
$ mount /dev/sda1 /mnt/boot

開始安裝

萬事就緒！開始來安裝 Arch Linux 吧！

網路連線

如果你要用 wifi 的話，先用 wifi-menu 來選擇連線，不然直接 ping 即可測試：

$ wifi-menu
$ ping  -c 3 www.google.com

驗證與更新

這邊更新 gpg key 好讓 pacman (Arch 的套件管理工具) 可以驗證安裝套件：

$ pacman-key --refresh-keys

順便更新一下系統時間

$ timedatectl set-ntp true

開始安裝

接著就可以一路按 Enter 或 Y 直到安裝進行。你也可以再多裝 base-devel 不過我打算需要的工具再裝就好：

$ pacstrap /mnt base linux linux-firmware

產生掛載設定檔

Linux 需要除存掛載以便之後自動掛載：

$ genfstab -U /mnt >> /mnt/etc/fstab

Boot Loader 設定

接下來的步驟我們都可以切到我們的系統上進行了：

$ arch-chroot /mnt

我一開始是用 systemd-boot，但為了省掉一些麻煩我們還是用大家耳熟能詳的 GRUB 吧。我們會需要 grub 和 efibootmgr。

$ pacman -S grub efibootmgr

安裝 GRUB:

$ grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id=GRUB

安裝 os-prober 讓 Windows 可以出現在 GRUB 的選單中：

$ pacman -S os-prober

掛載 Windows 的磁區，像我的是 /dev/sda3：

$ mkdir /mnt/windows10
$ mount /dev/sda2 /mnt/windows10

產生 grub 設定檔：

$ grub-mkconfig -o /boot/grub/grub.cfg

網路設定

我們希望開機後能夠自動連上網路：

$ pacman -S netctl wpa_supplicant dialog

如果你是用 wifi 的話，跟之前一樣：

$ wifi-menu

如果是用 LAN 的話：

$ systemctl enable dhcpcd@enp0s31f6.service

dhcpcd@ 後面要輸入的是你的 interface name，你可以用 ip link 或 ls /sys/class/net 查到：

$ ip link
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group def
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp0s31f6: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAult qlen 1000
    link/ether 4c:cc:6a:ba:86:bb brd ff:ff:ff:ff:ff:ff

系統設定

在設定其他東西之前，推薦裝一下自動補完，方便你輸入指令

$ pacman -S bash-completion

root 與使用者密碼

先設定 root 的密碼

$ passwd

到這邊為止你已經可以直接重開機了，不過想將設定一次到位的話，我們可以繼續下去

$ reboot

再來建立一個新的使用者並加入相對應的 group，這個會是你平時用來登入的使用者

$ useradd -m -g users -G wheel,storage,power -s /bin/bash yourusername
$ passwd yourusername

接著我們要讓 wheel group 的使用者可以用 sudo 執行管理員相關的任務，如果你不熟悉 vim 的話也可以用 nano 就好

$ EDITOR=vim visudo

找到這行並解除留言（去掉 # 符號）

%wheel ALL=(ALL) ALL

設定時間與語系

編輯語系檔案(一樣選你熟悉的編輯器)然後解除留言en_US.UTF-8 UTF-8，你也可以再選擇其他語系，以台灣來說的話就是找到 zh_TW.UTF-8 UTF-8 解除這行的留言：

$ vim /etc/locale.gen

接著用此檔案產生語系

$ locale-gen
$ echo LANG=en_US.UTF-8 > /etc/locale.conf
$ export LANG=en_US.UTF-8

時區

你可以用這個指令搜尋時區

$ ls /usr/share/zoneinfo/

當然你要是就在台北時區這樣設定就好了

$ ln -s /usr/share/zoneinfo/Asia/Taipei /etc/localtime

硬體時鐘

讓硬體時鐘在作業系統之間一致，以防它去複寫改變了顯示的時間

$ hwclock --systohc

Hostname

命名你的主機名稱，這邊我就只叫做 arch 就好：

$ echo arch > /etc/hostname

調整 mirror list

pacman-contrib 這個套件有個腳本 /usr/bin/rankmirrors 可以幫你排出最快的 mirror，不過要是嫌太麻煩的話就用 Pacman Mirrorlist Generator 吧！然後寫進這邊：

$ vim /etc/pacman.d/mirrorlist
Server = http://archlinux.cs.nctu.edu.tw/$repo/os/$arch

桌面環境

桌面環境想用那家一樣見仁見智，如果這些你打算自己摸索的話，那麽到這邊我們就算是告一段落了，已經可以開始你的 arch 探索之旅！不然這邊我們將還是先裝最大宗的 gnome，想找更多可以參考 Desktop environment，裡面也有台灣之光號稱最輕量的 LXDE/LXQT。

$ pacman -S gnome gnome-extra
$ systemctl enable gdm.service
$ systemctl start gdm.service

大功告成！恭喜！

References

https://wiki.archlinux.org/title/Dual_boot_with_Windows
https://gist.github.com/xtrymind/b895c640231adde21598d5188c75d4b5
http://lampjs.com/easy-installing-arch-linux-dual-boot-with-windows-uefi-for-beginners/

Waker Practice: Attempt to Unwrap a Future

2020-03-15T16:13:00+08:00

Many enum types like Option and Result provide method like unwrap to retrieve the field immediately. It panics if it can not get the value we want. This gives me an idea to do a silly exercise. What if we can also unwrap a future? "But why?" you said. Because why not. Consider when we use .await syntax on futures from async blocks or functions, it will poll the future and see if it is ready. The compiler transforms the whole block into some sort of state machine, and each .await represents a potential state transition. And now I would like to make this exit to be unwrap which attempts to resolve a future immediately.

Wake up Mr. Freeman

The entire method is quite easy actually, we just need to match the poll and then return the value. But the missing puzzle is the waker. In real executor system, it will provide all required contexts for us. But we are going to poll it manually ourselves, we need to define our waker function. Fortunately, the standard library already provide all the components we want. We just have to assemble them, so let's wake up and smell the ashes!

pub fn waker<F: Fn() + Send + Sync + 'static>(f: F) -> Waker {
    let raw = Arc::into_raw(Arc::new(f)) as *const ();
    let vtable = &RawWakerHelper::<F>::VTABLE;
    unsafe { Waker::from_raw(RawWaker::new(raw, vtable)) }
}

We create a waker function which outputs, well, a Waker. This type is a wrapper of inner instance RawWaker which provides customized wakeup behavior. It consists of a pointer to data and vtable to customize the behavior we mentioned before. Since there's a method in vtable for cloning and we want the waker and future we are dealing with are still the same one, we wrap up with Arc and turn it back to raw pointer. I will show you what's going to be next.

struct RawWakerHelper<F>(F);

impl<F: Fn() + Send + Sync + 'static> RawWakerHelper<F> {
    const VTABLE: RawWakerVTable = RawWakerVTable::new(
        Self::clone_waker,
        Self::wake,
        Self::wake_by_ref,
        Self::drop_waker,
    );

    unsafe fn clone_waker(ptr: *const ()) -> RawWaker {
        let arc = ManuallyDrop::new(Arc::from_raw(ptr as *const F));
        mem::forget(arc.clone());
        RawWaker::new(ptr, &Self::VTABLE)
    }

    unsafe fn wake(ptr: *const ()) {
        let arc = Arc::from_raw(ptr as *const F);
        (arc)();
    }

    unsafe fn wake_by_ref(ptr: *const ()) {
        let arc = ManuallyDrop::new(Arc::from_raw(ptr as *const F));
        (arc)();
    }

    unsafe fn drop_waker(ptr: *const ()) {
        drop(Arc::from_raw(ptr as *const F));
    }
}

As you can see the rest parameters that RawWakerVTable requires are here. Since it demands raw pointers which already touch the unsafe field. We are able to play around out Arc pointer in several way and still be sound. Take a look a little bit more if needed, all methods and modules used are documented in standard library.

Time to `uwrap`

Once our waker is done, the last thing left to do is to write out one and only function unwrap. And it's way simpler than you thought:

pub fn unwrap<F: Future>(f: F) -> F::Output {
    let waker = waker(|| ());
    let mut f = Box::pin(f);
    match f.as_mut().poll(&mut Context::from_waker(&waker)) {
        Poll::Ready(output) => output,
        Poll::Pending       => panic!("future not ready"),
    }
}

That's it! Although this is probably very useless unless you are prototyping some executor or reactor systems. Still a good practice imho. Here's the link to the playground. Hope you can get more familiar with modules beneath the future system.

DST 和 ZST 兩種願望一次滿足

2020-01-25T18:40:07+08:00

我們知道 Rust 大部分情況下要求要知道型態的 size 與 alignment，不過同時也支援一些特殊的型態可以忽視這些條件。首先我們最常遇見的就是 Dynamically Sized Types (DSTs) 它們就不會靜態地知道 size 與 alignment，所以它們得透過指標 (pointer) 指向它們才得以存在，這樣的指標是一個寬指標包含一個指針以及一些額外資訊來滿足 Rust 的要求。而這樣的型態也許沒察覺到但其實我們已經遇到而且也用到非常多次，其中最主要的兩大型態就是 trait object 和 slice，更多詳情可以參考 Rustonomicon 的解釋。在平時使用泛型時我們可以用 ?Sized 來指定 DST，以下是將 trait 的 associate type 指定為 DST 的範例：

trait EncodedBuf {
  type Slice: ?Sized;

  fn new() -> Self where Self: Sized;

  /// View the bytes in this buffer as a slice
  fn as_slice(&self) -> &Self::Slice;

  //...
}

當然 DST 實際上在很多函式庫中的使用都是很受限的，大部分當然對型態的要求都是 Sized。在標準函式庫中我們也不乏看到諸多類似的設計像是 &str 之於 String、 &[] 之於 Vec 、 Path 之於 PathBuf 等等。前者均為 DST 都是設計成不擁有其數據的引用 (reference) 型態，需要用後者才能獲得所有權並作為可變 ( mutable) 數據來使用。

而另一方面 Rust 也還支援 Zero Sized Types (ZSTs) 顧名思義就是沒有大小的型態，當然一開始想到的話的確沒有任何意義。當然對於編譯也是如此，所以 Rust 在編譯時可以將一些型態轉為 ZST 並讓它們的動作最終變成只有 nop。原因很簡單，一來是它沒有大小，開空間給它們來儲存沒有任何意義，二來它們也只會有一種值甚至可以憑空產生，所以直接轉為 nop 的確很合適。我們最常用到的 ZST 大概就非 empty tuple () 莫屬，常常用在 Enum 像是 Result 的 match 配對等等。

fn return_ok() -> Result<(), io::Error> {
  Ok(())
}

既然知道有這兩種型態後，現在就讓我們用上面的 EncodedBuf trait 嘗試一些有趣的東西，當然還有很多方法和 trait 沒寫上去，不過實作均類似所以不贅述：

pub struct NewByte([()]);

impl NewByte {
    unsafe fn make(ptr: *const u8, offset: usize, len: usize) -> *const Self {
        std::mem::transmute((ptr.offset(offset as isize), len))
    }

    unsafe fn ptr(&self, index: usize) -> *const u8 {
        (self.0.as_ptr() as *const u8).offset(index as isize)
    }

    pub fn slice(&self, range: Range<usize>) -> &Self {
        assert!(range.end >= range.start && range.end <= self.len());
        unsafe { &*Self::make(self.ptr(0), range.start, range.end - range.start) }
    }

    //...
}

pub struct NewByteBuf(Vec<u8>);

impl EncodedBuf for NewByteBuf {
    type Slice = NewByte;

    fn new() -> Self {
        Self(Vec::new())
    }

    pub fn as_slice(&self) -> &Self::Slice {
        unsafe { &*Self::Slice::make(self.0.as_ptr() as _, 0, self.0.len()) }
    }

    //...
}

簡單來說，我們嘗試定義兩種新的型態而他們的關係就類似 Path/PathBuf，它們的長度可能就不是一般的 byte，也許是 3 bits 就一個 byte，不過為了方變我們還是先用 8 bits = 1 byte 作為範例。接著有趣的地方是 NewByte，這是一個 DST 包住了 [()]：一個只包含 zero-sized item 的陣列而且沒有定義長度。由於對 DST 的引用是個胖指針 (我們可以下 assert_eq!(16, std::mem::size_of::<&[u8]>()); 來確認這點)，也就是 8 bytes 的指標加上 8 bytes 的長度，我們可以利用這點來儲存 bit offset。我們拿了一個 zero-sized 的 slice 型態，Rust 不必知道 slice 的長度，因為對 ZST 而言永遠會是 0 且 constant，所以長度這欄位變成沒有使用到，我們便能用此來位我們的型態來定義自己想要的長度了。所以神奇的事情發生了 NewByte 同時是 dynamically-sized 以及 zero-sized！

DST 與 ZST 個別都會帶來一些有趣的特性，舉例來說有 DST 的性質的話，因為本身是指標這樣一來 NewTypeBuf 想要 deref 的話就可能變成 NewType，標準函式庫中的 PathBuf 與 Path 就是這種關係。而如果 ZST 的話，由於很多動作最終能夠成為 nop，這讓我們能更直接地存取到我們想使用的位置。當然這在一般狀況下的確不須用，而且用到這樣子的黑魔法的確需要處理並確保能解決 unsound 的問題，像是使用 miri 反覆確認。不過當我們要處理的資料屬於非常低階，當占用到一點空間都成為關鍵性的考量時，這的確是非常有趣的使用方法之一。我們可以在像是 bitvec 或 dashmap 等這類的 crate 看到這樣子類似的實作應用。

Rust 錯誤處理函式庫推薦：Anyhow + thiserror

2019-11-22T12:04:23+08:00

在開始講解前我想開門見山講結論，Rust 在針對錯誤處理已經有 Result<T> 這個非常好用的型態，而且在 TRPL 中也有一章在專門講解了。如果只是要寫個簡單的測試你可以只定義一個基本的 enum，而如果是正式的專案也更推薦定義好屬於自己的錯誤型態，依賴第三方的函式庫總是會發生不可預期的狀況出現。但有時候在錯誤處理方面的確會遇到一些障礙是我們得花時間特別去解決的，如果這是一個普遍的問題通常大家便會用些方便的依賴來解決。在過去一兩年我想最常用的就是 failure 了，而過去幾年這類型的 crate 更是如雨後春筍般冒出來，再過不久大概就能像 go 和 npm 有上百萬種錯誤處理的函示庫了(笑)。總之目前更好更方便的選擇就是這次要講的 anyhow + thierror。

anyhow

anyhow 首次公開於 2019 年十月，它主要是一個能夠讓我們方便傳遞錯誤的函示庫，就像 failure 的訴求之一一樣。不同於 failure 用了自己定義的 trait Fail，anyhow 定義的形態和 trait 都是基於標準函式庫的 std::error::Error，除此之外無其他依賴，所以他也同時號稱是更好的 Box<dyn Error>。不過也因如此 anyhow 用到了 RFC 2504 的一些改進，所以會需要 Rust 1.34+ 以上>。

首先最重要的當然就是更方便的錯誤型態 Result<T, anyhow::Error> 或者也等同於 anyhow::Result<T>，只要在函式內有實作 std::error::Error trait 的型態，都能夠只使用 ? 來回傳：

use anyhow::Result;

fn get_cluster_info() -> Result<ClusterMap> {
    let config = std::fs::read_to_string("cluster.json")?;
    let map: ClusterMap = serde_json::from_str(&config)?;
    Ok(map)
}

再來 anyhow 也提供了擴展 Result 增加更多 Context(上下文) 的功能。要是遇到錯誤時我們只能看到 "No such file or directory" 的話還是很難知道錯在哪。Context 能提供更高階的錯誤形式來幫助 debug。

use anyhow::{Context, Result};

fn main() -> Result<()> {
    ...
    it.detach().context("Failed to detach the important thing")?;

    let content = std::fs::read(path)
        .with_context(|| format!("Failed to read instrs from {}", path))?;
    ...
}

Error: Failed to read instrs from ./path/to/instrs.json

Caused by:
    No such file or directory (os error 2)

anyhow 也有 Downcasting 能夠用 call by value, shared reference, mutable reference 等方式取得。除此之外還有 Chain 能夠方便迭代出結果

pub fn underlying_io_error_kind(error: &Error) -> Option<io::ErrorKind> {
    for cause in error.chain() {
        if let Some(io_error) = cause.downcast_ref::<io::Error>() {
            return Some(io_error.kind());
        }
    }
    None
}

最後我們常見的各式錯誤處理 macro 也都有提供，像是 bail!, ensure! 以及將字串轉換成錯誤的 anyhow!(相當於 format_err!)：

return Err(anyhow!("Missing attribute: {}", missing));

thiserror

不過這樣只涵蓋到了動態錯誤處理的部份，如果你想要用外部依賴來定義出架構完善的錯誤的話，那麼就是使用 thiserror 的時候了。它和 anyhow 都是由 dtolnay 在同時間釋出的，某方面來說可以把它們想成是原本 failure 拆開來後並改善後的版本。thiserror 最主要的功能就是透過 #[derive(Error)] 來幫你的型態實作 std::error::Error:

use thiserror::Error;

#[derive(Error, Debug)]
pub enum DataStoreError {
    #[error("data store disconnected")]
    Disconnect(#[from] io::Error),
    #[error("the data for key `{0}` is not available")]
    Redaction(String),
    #[error("invalid header (expected {expected:?}, found {found:?})")]
    InvalidHeader {
        expected: String,
        found: String,
    },
    #[error("unknown data store error")]
    Unknown,
}

std::error::Error

最後的最後筆者覺得還是講一下標準函示庫裡最基本的 Error 比較好，在一開始學習實在完全不清楚的情況下，的確都過第三方依賴能夠輕鬆解決錯誤處理，而這也是大多數社群會推薦的。但隨著經驗累積後不免會發現一些負擔，如果時間充裕當然推薦親自實作在標準函式庫內的錯誤型態。而 Error trait 隨著這幾年也有一些轉變，以下是值得注意的改變：

Error::description 已經被半棄用中，因為直接 impl Display 會更好
Error::cause 已被棄用，因為有了 Error::source
Error::iter_chain 和 Error::iter_sources 可在 nightly 上使用了
Error::backtrace 以及 module 模組也能在 nightly 上使用了

除了 Error 外再加上原本的 Result、? 到詳盡的錯誤代碼。這是筆者覺得 Rust 在錯誤處理做得十分不錯的地方，雖然對於一個通用的錯誤處理函示庫該有什麼樣的功能，社群仍在摸索當中。但底層的基本架構的確是非常的穩固完善。

Slides

2019-08-04T19:55:46+08:00

你的不可變引用不是你的不可變引用 @ rust.tw meetup 2020/08
Smol Talk on async/.await @ COSCUP 2020 2020/08
FFI @ rust.tw meetup 2019/10
Async @ rust.tw meetup 2020/02

Rust Webinar

2018-03-15T19:00:00+08:00

"The Book" is all you need

Optional:

Rust playground: Write and test your simple code
Rustling: Super easy exercises
Rust by example: Examples for each subjects

Getting Started

Linux/MacOS:

curl https://sh.rustup.rs -sSf | sh

Windows: https://www.rust-lang.org/tools/install

What you installed:

rustc: compiler
- rustc --verision
- just like gcc
rustup: toolchain manager
- rustup update to update Rust
cargo: build system & package manager
- cargo new hello-world to create a project
- cargo build to build the project
- cargo run to run the project binary
- carrgo test to run test case

Slides

Chapters without slides:

Ch1. is just installation
Ch2. is a simple exmaple
Ch12. is a summary example of previous chapters

TODO:

Ch19: advanced usage
Appendex(?)

Chapter	Slides
3	Common Concepts
4	Ownership
5	Structs
6	Enums
7	Crates & Modules
8	Collections - Vector, String, HashMap
9	Error Handling
10	Generic, Traits, Lifetime
11	Testing
13	Iterator & Closure
14	Cargo & Crates.io
15	Smart Pointers
16	Fearles Concurrency
17	Trait Object
18	Pattern Matching

Wu Yuwei

Can we use Wasmtime to build web script engine?

DOM Objects in Wasm GC

Reflector in Wasm Component

Implement Resources in Host Side

Node and NodeImpl

Inherent Node

Implement resource traits

EventTarget As a field

Next steps

Behind the Scenes of Verso Browser Development

Why Build Verso? From Servo Minibrowser to a Stable Application

The Big Picture: Engine Versus Browser Responsibilities

Recent Development Highlights from Our Perspective

Borderless Window Dragging

Context Menus

Prompt Dialog Support

Tabs for Multi-Page Browsing

IME Input Events

File Input Dialog Support

Notifications with WebAPI Support

Caret and Text Selection display in Text Input

Browsing History and Bookmarks in Profile Config

What's next?

Should we add wgpu support to webrender?

Build on top of ANGLE

Implement Compositor trait

Add wgpu version of Renderer

Why I voted for Servo's AI policy change despite I don't use those tools

Verso: initial multi-window support

Multiple surfaces

Multiple display lists

What's next?

Verso: Writing its own compositor part 2

Clarify which component should own which states

Window

Webview

CompositeTarget

The next step

Verso: Writing its own compositor part 1

What has changed

Thread creation

Constellation messages

The next step

Verso: A new browser based on Servo

Multi-Windows

Better IPC

Multiprocess

Flatpack Support

Looking toward the future

Install Windows 11 the hard way

Create a USB Installer

Boot into Installer

Create Partitions Manually

Windows RE Tools partition

System & MSR Partition

Windows Partition

Recovery Image Partition

Copy Windows Data to Partitions

Restart and Boot into Windows

Install Driver Bundle

Environment Setup for Building Webkit on Linux

Choose git repo as Source

Installing Dependencies

Building and Running

Debugging and Testing

Contributing

GAT 懶人包

After half a year, what now?

What happened after Mozilla layoff?

Unable to upgrade SpooderMonke

Spaghetti inside script/style/layout

Crates that still work well

Rust Kernel Module: Pinning

The problem requires pinning

Miscdev initialization

Conclusion

Reference

Rust Kernel Module: Character Device Driver

Device File and Device Driver

DOM `Object`s in Wasm GC

`Node` and `NodeImpl`

Inherent `Node`

`EventTarget` As a field

Macros and Types from `kernel` Crate